CLI Reference
Global
o2idctl <command>
| Command | Aliases |
|---|---|
config | |
use | |
login | |
users | user |
applications | application, apps, app |
roles | role |
agents | agent |
resource-servers | resource-server, resourceservers, resourceserver |
help | -h, --help |
version | --version |
config
Interactively creates or updates a saved profile with an API base URL and name.
o2idctl config
Prompts:
| Prompt | Description |
|---|---|
API base URL | Base URL for an O2ID API instance |
Profile name | Name used later with o2idctl use <profile> |
use
Selects a saved profile for the current terminal session.
o2idctl use <profile>
login
Logs in via the browser (OAuth2 authorization code + PKCE, using a local loopback redirect) and stores the resulting access and refresh tokens on the currently-selected profile. Every other command requires this to have been run at least once — see Using o2idctl for the full login flow and the API Reference for how roles/scopes gate each endpoint.
o2idctl login
Users
Every users command below requires the users:read, users:create, or
users:update scope, depending on the operation.
users create
Creates a new user. A password is optional — omit it for passwordless users.
o2idctl users create --email <email> [--display-name <name>] [--password <password>]
| Option | Required | Description |
|---|---|---|
--email <email> | Yes | User email address |
--display-name <name> | No | User display name |
--password <password> | No | User password |
users get
Fetches a single user by its internal ID.
o2idctl users get <id>
users list
Lists all users.
o2idctl users list
users assign
Assigns a role to a user. Assigning a role the user already holds is a no-op.
Requires the roles:assign scope.
o2idctl users assign --user <userId> --role <roleId>
| Option | Required | Description |
|---|---|---|
--user <userId> | Yes | Internal user ID |
--role <roleId> | Yes | Internal role ID |
users unassign
Removes a role from a user. Unassigning a role the user doesn't hold is a
no-op. Requires the roles:assign scope.
o2idctl users unassign --user <userId> --role <roleId>
| Option | Required | Description |
|---|---|---|
--user <userId> | Yes | Internal user ID |
--role <roleId> | Yes | Internal role ID |
Applications
Every applications command below requires the applications:read,
applications:create, applications:update, or applications:delete
scope, depending on the operation.
applications create
Registers a new OAuth 2.0 client application. Use --public for clients that
can't hold a secret, or --client-secret for confidential clients.
o2idctl applications create --name <name> [--callback-url <url> ...] [--scope <scope> ...] [--client-secret <secret>|--public]
| Option | Required | Description |
|---|---|---|
--name <name> | Yes | Application name |
--callback-url <url> | No | OAuth redirect URI. Repeat for multiple callback URLs |
--scope <scope> | No | RBAC scope this application's tokens may carry. Repeat for multiple scopes. Omit for none (deny-by-default) |
--client-secret <secret> | No | Creates a confidential client |
--public | No | Creates a public client |
applications get
Fetches a single application by its internal ID.
o2idctl applications get <id>
applications list
Lists all registered applications.
o2idctl applications list
applications update
Updates an application's name, callback URLs, and/or client secret. A field you omit is left unchanged.
o2idctl applications update <id> [--name <name>] [--callback-url <url> ...] [--scope <scope> ...] [--client-secret <secret>|--public]
| Option | Required | Description |
|---|---|---|
--name <name> | No | Replacement application name |
--callback-url <url> | No | Replacement OAuth redirect URI. Repeat for multiple callback URLs. Replaces the full list — a partial list isn't merged with the existing one |
--scope <scope> | No | Replacement RBAC scope. Repeat for multiple scopes. Replaces the full list — a partial list isn't merged with the existing one |
--client-secret <secret> | No | Sets or replaces the client secret |
--public | No | Clears the client secret and makes the application public |
applications delete
Permanently deletes an application. This cannot be undone.
o2idctl applications delete <id>
applications resource-servers
Lists the resource servers an application is authorized for, and the
scope subset granted on each. Requires applications:read. See
Managing Resource Servers.
o2idctl applications resource-servers <app-id>
applications authorize-resource-server
Authorizes an application to mint or introspect tokens for a resource
server, granting it the given subset of that resource server's own
defined scopes. Re-running this replaces any previously granted scopes
for the pair, rather than merging with them. Requires
applications:authorize-resource-servers.
o2idctl applications authorize-resource-server <app-id> <resource-server-id> [--scope <scope> ...]
| Option | Required | Description |
|---|---|---|
--scope <scope> | No | One of the resource server's own defined scopes to grant. Repeat for multiple scopes. Omit for none |
applications deauthorize-resource-server
Removes an application's authorization for a resource server entirely.
Requires applications:authorize-resource-servers.
o2idctl applications deauthorize-resource-server <app-id> <resource-server-id>
Roles
Every roles command below requires the roles:read, roles:create,
roles:update, or roles:delete scope, depending on the operation. See
Managing Roles for the role/scope model and the
API Reference for the scope each endpoint requires.
roles create
Creates a role with a set of scopes.
o2idctl roles create --name <name> [--scope <scope> ...]
| Option | Required | Description |
|---|---|---|
--name <name> | Yes | Role name |
--scope <scope> | No | Scope granted by this role. Repeat for multiple scopes |
roles get
Fetches a single role by its internal ID.
o2idctl roles get <id>
roles list
Lists all roles.
o2idctl roles list
roles update
Replaces an existing role's name and/or scopes.
o2idctl roles update <id> --name <name> [--scope <scope> ...]
| Option | Required | Description |
|---|---|---|
--name <name> | Yes | Replacement role name |
--scope <scope> | No | Replacement scope. Repeat for multiple scopes |
roles delete
Permanently deletes a role. Fails if the role is still assigned to any user.
o2idctl roles delete <id>
AI Agents
Every agents command below requires the agents:read, agents:create,
agents:update, or agents:delete scope, depending on the operation. See
Managing AI Agents for what an AI agent is and the
API Reference for the scope each endpoint requires.
agents create
Registers a new AI agent identity with a set of allowed scopes.
o2idctl agents create --name <name> [--scope <scope> ...]
| Option | Required | Description |
|---|---|---|
--name <name> | Yes | AI agent name |
--scope <scope> | No | RBAC scope this AI agent's tokens may carry. Repeat for multiple scopes. Omit for none (deny-by-default) |
agents get
Fetches a single AI agent by its internal ID.
o2idctl agents get <id>
agents list
Lists all registered AI agents.
o2idctl agents list
agents update
Updates an AI agent's name, allowed scopes, and/or registered public key. A field you omit is left unchanged.
o2idctl agents update <id> [--name <name>] [--scope <scope> ...] [--public-key <path>]
| Option | Required | Description |
|---|---|---|
--name <name> | No | Replacement AI agent name |
--scope <scope> | No | Replacement RBAC scope. Repeat for multiple scopes. Replaces the full list — a partial list isn't merged with the existing one |
--public-key <path> | No | Path to a JSON Web Key (RSA only) file. Registers the key this AI agent uses to authenticate itself via private_key_jwt, without a human present. There's currently no way to clear a registered key back to "none" |
agents delete
Permanently deletes an AI agent. This cannot be undone.
o2idctl agents delete <id>
Resource Servers
Every resource-servers command below (aside from the scopes
sub-group) requires the resourceservers:read, resourceservers:create,
resourceservers:update, or resourceservers:delete scope, depending on
the operation. See Managing Resource Servers
for what a resource server is and how an application gets authorized for
one, and the API Reference for the scope each endpoint requires.
resource-servers create
Registers a new resource server (API). Its own scopes/permissions are
managed separately — see resource-servers scopes below.
o2idctl resource-servers create --name <name> --identifier <identifier>
| Option | Required | Description |
|---|---|---|
--name <name> | Yes | Resource server name |
--identifier <identifier> | Yes | The value callers pass as resource/audience to target this resource server |
resource-servers get
Fetches a single resource server by its internal ID.
o2idctl resource-servers get <id>
resource-servers list
Lists all registered resource servers.
o2idctl resource-servers list
resource-servers update
Updates a resource server's name and/or identifier. A field you omit is left unchanged.
o2idctl resource-servers update <id> [--name <name>] [--identifier <identifier>]
| Option | Required | Description |
|---|---|---|
--name <name> | No | Replacement resource server name |
--identifier <identifier> | No | Replacement identifier |
resource-servers delete
Permanently deletes a resource server. This cannot be undone, and any application authorizations naming it become unreachable, since resolving the identifier is the first step in every check that consults them.
o2idctl resource-servers delete <id>
resource-servers scopes create
Defines a new scope/permission on a resource server. The value must be unique among that resource server's own scopes.
o2idctl resource-servers scopes create --resource-id <resource-id> --value <value> \
[--display-name <name>] [--description <text>]
| Option | Required | Description |
|---|---|---|
--resource-id <resource-id> | Yes | The resource server this scope belongs to |
--value <value> | Yes | The scope itself, granted and checked exactly as written, e.g. read:messages |
--display-name <name> | No | Human-readable name. Purely descriptive |
--description <text> | No | Human-readable description. Purely descriptive |
o2idctl resource-servers scopes create --resource-id <resource-id> \
--value read:messages --display-name "Read Messages" --description "Allows reading messages"
resource-servers scopes list
Lists the scopes a resource server defines.
o2idctl resource-servers scopes list --resource-id <resource-id>
resource-servers scopes get
Fetches a single scope by its own ID — no --resource-id needed, since a
scope's ID is already globally unique.
o2idctl resource-servers scopes get <scope-id>
resource-servers scopes update
Updates a scope's value, display name, and/or description, addressed by
its own ID alone. A field you omit is left unchanged. Renaming --value
doesn't retroactively update any application authorization already
granted under the old value — the same way renaming any OAuth scope
string is a breaking change in any system.
o2idctl resource-servers scopes update <scope-id> [--value <value>] [--display-name <name>] [--description <text>]
| Option | Required | Description |
|---|---|---|
--value <value> | No | Replacement scope value. Must still be unique among its resource server's other scopes |
--display-name <name> | No | Replacement display name |
--description <text> | No | Replacement description |
resource-servers scopes delete
Permanently deletes a scope, addressed by its own ID alone. This cannot be undone.
o2idctl resource-servers scopes delete <scope-id>