Commands

The Roster CLI is a thin MCP client. Branded commands serialize flags to the snake_case input keys exposed by MCP tools. Use roster call when you need a raw tool invocation that does not yet have a branded command.

Global Flags

Flag	Purpose
`--config-dir <path>`	Override `ROSTER_HOME` / `~/.roster`.
`--profile <profile>`	Select an OAuth profile alias, MCP URL, or profile key.
`--mcp-url <url>`	MCP endpoint URL.
`--api-key <token>`	Bearer API key. Not persisted.
`--json`	Emit a snake_case JSON envelope.
`--timeout <ms>`	MCP request timeout. Defaults to `30000`.
`--non-interactive`	Fail instead of starting interactive auth flows.
`--debug`	Print extra failure detail.

Auth

See CLI Authentication for OAuth profile storage, API-key behavior, auth precedence, and scope guidance.

roster login <your-roster-public-url>/mcp --name prod
roster login <your-roster-public-url>/mcp --scope-preset read --scope mcp:custom:read
roster login <your-roster-public-url>/mcp --no-open --callback-port 48217

Option	Purpose
`--name <alias>`	Save a human-friendly alias for the OAuth profile.
`--scope-preset <preset>`	Request one of `resolve`, `read`, `manage`, or `admin`. Defaults to `resolve`.
`--scope <scope...>`	Add extra OAuth scopes to the selected preset.
`--no-open`	Print the authorization URL instead of opening the browser.
`--callback-port <port>`	Use a specific loopback OAuth callback port.

roster login starts a loopback OAuth callback listener, opens the browser unless --no-open is set, uses PKCE, exchanges the authorization code, stores the OAuth profile, and selects it as the current profile.

Status

roster auth status
roster --profile prod auth status

auth status shows which auth source the CLI would use for the current command. Its JSON output includes auth_mode, api_key_configured, mcp_url, selected_profile_key, and profile_alias.

Profiles

roster auth profiles

auth profiles lists saved OAuth profiles, aliases, granted scopes, selected profile state, refresh-token presence, and update timestamps.

Select A Default Profile

roster auth use prod

After this, commands can omit --profile prod:

roster projects list --limit 3
roster resolve "Who should approve the Helios renewal?"

The selector can be an alias, an MCP URL, or a profile key.

Logout

roster auth logout
roster auth logout prod
roster auth logout prod --remove

Without --remove, auth logout removes OAuth tokens but keeps the saved profile. Use --remove to delete the whole profile and any aliases that point to it.

Aliases

roster auth alias set production prod
roster auth alias rm production

Aliases must start with a letter or number and may contain letters, numbers, dots, underscores, or dashes. They cannot be URLs.

Scope Presets

Preset	Scope set
`resolve`	`openid profile email offline_access mcp:resolve mcp:resolve-requests:read mcp:projects:read mcp:participants:read mcp:status:read`
`read`	`resolve` plus `mcp:labels:read mcp:delegations:read`
`manage`	all non-admin Roster MCP read and write scopes
`admin`	`manage` plus MCP scopes for team members, AI agents, service accounts, API keys, audit events, model runs, provider connectors, and platform settings

Commands

roster tools
roster status
roster call list_projects limit=10 query=helios

roster resolve "Who should approve the Helios vendor renewal?"
roster resolve --explain "Who should approve the Helios vendor renewal?"
roster resolve --mode test --project-id proj_... "Who should approve the test renewal?"

roster projects list --query helios --limit 10
roster projects get proj_...
roster projects create "Helios Renewal" --description "Vendor renewal workspace"
roster projects update proj_... --status live
roster projects delete proj_...

roster participants list --project-id proj_... --label Finance --metadata approval_limit_eur:gte:125000
roster participants get part_...
roster participants create proj_... "Finance Approvers" --label-id lbl_... --metadata approval_limit_eur=125000
roster participants update part_... --new-label Procurement
roster participants delete part_...

roster participants members list part_...
roster participants members add part_... drec_...
roster participants members remove part_... drec_...

roster directory-records search "Ethan Wright" --type user

roster labels list --query finance
roster labels get lbl_...
roster labels create Finance --color "#3B82F6"
roster labels update lbl_... --name "Finance Review"
roster labels delete lbl_...

roster delegations list --status active --project-id proj_...
roster delegations get del_...
roster delegations create --scope participant --participant-id part_... --delegate-user-id drec_...
roster delegations update del_... --scope all_participants --delegate-user-id drec_...
roster delegations revoke del_...

roster resolve-requests list --project-id proj_... --resolution-status success
roster resolve-requests get rrq_...

roster team-members list --query ada
roster team-members get usr_...
roster team-members create --name "Ada Admin" --email ada@example.com --role admin --password-stdin
roster team-members update usr_... --role project_owner --email-verified
roster team-members disable usr_...
roster team-members enable usr_...
roster team-members delete usr_...

roster ai-agents list --query resolver
roster ai-agents get idn_...
roster ai-agents create "Resolver Agent" --role member --email resolver@example.com
roster ai-agents update idn_... --display-name "Resolver Agent v2"
roster ai-agents disable idn_...
roster ai-agents enable idn_...
roster ai-agents delete idn_...

roster service-accounts list --query sync
roster service-accounts get idn_...
roster service-accounts create "Directory Sync" --role admin
roster service-accounts update idn_... --email sync@example.com
roster service-accounts disable idn_...
roster service-accounts enable idn_...
roster service-accounts delete idn_...

roster api-keys list
roster api-keys get atok_...
roster api-keys create "Automation" --user-id idn_... --scope mcp:projects:read mcp:participants:read
roster api-keys revoke atok_...

roster audit-events list --actor-type user --event-type platform_settings --page-size 50
roster audit-events get aud_...

roster model-runs list
roster model-runs get mrun_...

roster provider-connectors list
roster provider-connectors get pcn_...
roster provider-connectors create --input-file connector.json
roster provider-connectors update pcn_... --input-stdin
roster provider-connectors delete pcn_...

roster platform-settings get
roster platform-settings update --input-file platform-settings.json

Team members, AI agents, service accounts, API keys, provider connectors, and platform settings are admin-only. Audit events and model runs are read-only and also depend on the active product license features. Provider connector create/update payloads use the REST connector JSON shape. Platform settings updates use the REST wrapper shape: { "settings": ... }. Team member passwords must be read from --password-stdin or --password-env <env>; there is no --password flag.

Tool Mapping

CLI command	MCP tool	Required scope
`roster status`	`get_status`	`mcp:status:read`
`roster resolve`	`resolve`	`mcp:resolve`
`roster tools`	`tools/list`	any valid MCP auth
`roster call <tool>`	selected tool	selected tool scope
`roster resolve-requests list`	`list_resolve_requests`	`mcp:resolve-requests:read`
`roster resolve-requests get`	`get_resolve_request`	`mcp:resolve-requests:read`
`roster projects list`	`list_projects`	`mcp:projects:read`
`roster projects get`	`get_project`	`mcp:projects:read`
`roster projects create`	`create_project`	`mcp:projects:write`
`roster projects update`	`update_project`	`mcp:projects:write`
`roster projects delete`	`delete_project`	`mcp:projects:write`
`roster participants list`	`list_participants`	`mcp:participants:read`
`roster participants get`	`get_participant`	`mcp:participants:read`
`roster participants create`	`create_participant`	`mcp:participants:write`
`roster participants update`	`update_participant`	`mcp:participants:write`
`roster participants delete`	`delete_participant`	`mcp:participants:write`
`roster participants members list`	`list_participant_members`	`mcp:participants:read`
`roster participants members add`	`add_participant_member`	`mcp:participants:write`
`roster participants members remove`	`remove_participant_member`	`mcp:participants:write`
`roster directory-records search`	`search_directory_records`	`mcp:participants:read`
`roster labels list`	`list_labels`	`mcp:labels:read`
`roster labels get`	`get_label`	`mcp:labels:read`
`roster labels create`	`create_label`	`mcp:labels:write`
`roster labels update`	`update_label`	`mcp:labels:write`
`roster labels delete`	`delete_label`	`mcp:labels:write`
`roster delegations list`	`list_delegations`	`mcp:delegations:read`
`roster delegations get`	`get_delegation`	`mcp:delegations:read`
`roster delegations create`	`create_delegation`	`mcp:delegations:write`
`roster delegations update`	`update_delegation`	`mcp:delegations:write`
`roster delegations revoke`	`revoke_delegation`	`mcp:delegations:write`
`roster team-members list`	`list_team_members`	`mcp:team-members:read`
`roster team-members get`	`get_team_member`	`mcp:team-members:read`
`roster team-members create`	`create_team_member`	`mcp:team-members:write`
`roster team-members update`	`update_team_member`	`mcp:team-members:write`
`roster team-members delete`	`delete_team_member`	`mcp:team-members:write`
`roster team-members enable`	`enable_team_member`	`mcp:team-members:write`
`roster team-members disable`	`disable_team_member`	`mcp:team-members:write`
`roster ai-agents list`	`list_ai_agents`	`mcp:ai-agents:read`
`roster ai-agents get`	`get_ai_agent`	`mcp:ai-agents:read`
`roster ai-agents create`	`create_ai_agent`	`mcp:ai-agents:write`
`roster ai-agents update`	`update_ai_agent`	`mcp:ai-agents:write`
`roster ai-agents delete`	`delete_ai_agent`	`mcp:ai-agents:write`
`roster ai-agents enable`	`enable_ai_agent`	`mcp:ai-agents:write`
`roster ai-agents disable`	`disable_ai_agent`	`mcp:ai-agents:write`
`roster service-accounts list`	`list_service_accounts`	`mcp:service-accounts:read`
`roster service-accounts get`	`get_service_account`	`mcp:service-accounts:read`
`roster service-accounts create`	`create_service_account`	`mcp:service-accounts:write`
`roster service-accounts update`	`update_service_account`	`mcp:service-accounts:write`
`roster service-accounts delete`	`delete_service_account`	`mcp:service-accounts:write`
`roster service-accounts enable`	`enable_service_account`	`mcp:service-accounts:write`
`roster service-accounts disable`	`disable_service_account`	`mcp:service-accounts:write`
`roster api-keys list`	`list_api_keys`	`mcp:api-keys:read`
`roster api-keys get`	`get_api_key`	`mcp:api-keys:read`
`roster api-keys create`	`create_api_key`	`mcp:api-keys:write`
`roster api-keys revoke`	`revoke_api_key`	`mcp:api-keys:write`
`roster audit-events list`	`list_audit_events`	`mcp:audit-events:read`
`roster audit-events get`	`get_audit_event`	`mcp:audit-events:read`
`roster model-runs list`	`list_model_runs`	`mcp:model-runs:read`
`roster model-runs get`	`get_model_run`	`mcp:model-runs:read`
`roster provider-connectors list`	`list_provider_connectors`	`mcp:provider-connectors:read`
`roster provider-connectors get`	`get_provider_connector`	`mcp:provider-connectors:read`
`roster provider-connectors create`	`create_provider_connector`	`mcp:provider-connectors:write`
`roster provider-connectors update`	`update_provider_connector`	`mcp:provider-connectors:write`
`roster provider-connectors delete`	`delete_provider_connector`	`mcp:provider-connectors:write`
`roster platform-settings get`	`get_platform_settings`	`mcp:platform-settings:read`
`roster platform-settings update`	`update_platform_settings`	`mcp:platform-settings:write`

Resolve Output

roster resolve renders the nested MCP result.answer, selected participants, users, and caveats in human mode. Add --explain to include extra lookup details, including the labels, participants, and users considered during resolution. --explain is a CLI rendering option only; it is not sent to the MCP resolve tool.

JSON Contract

Human output is the default and renders common Roster resources as concise terminal summaries. Add --json for automation:

{
  "ok": true,
  "command": "projects list",
  "tool": "list_projects",
  "mcp_url": "<your-roster-public-url>/mcp",
  "request": {
    "limit": 10
  },
  "structured_content": {
    "projects": []
  }
}

Errors use the same snake_case envelope:

{
  "ok": false,
  "command": "projects list",
  "error": {
    "error_code": "missing_auth",
    "message": "No OAuth profile is available. Run roster login or pass --api-key/ROSTER_API_KEY."
  }
}

MCP JSON-RPC errors use mcp_<code> error codes, for example mcp_32001 for a request timeout. HTTP transport errors keep http_<status> codes and include status only for real HTTP status values.

Commander parse errors, such as unknown options or invalid enum choices, are also wrapped when --json is set:

{
  "ok": false,
  "command": "--json --bad",
  "error": {
    "error_code": "commander_unknown_option",
    "message": "unknown option '--bad'"
  }
}

Mutation metadata values are sent as strings because the MCP create/update participant schemas store metadata entries as key=value text. Metadata filters on list commands still support typed values and operators.

Commands

Global Flags

Auth

Login

Status

Profiles

Select A Default Profile

Logout

Aliases

Scope Presets

Commands

Tool Mapping

Resolve Output

JSON Contract