CLI 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 Commands

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

Login

roster login https://roster.example.com/mcp --name prod
roster login https://roster.example.com/mcp --scope-preset read --scope mcp:custom:read
roster login https://roster.example.com/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, or manage. 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
read	resolve plus mcp:labels:read mcp:delegations:read
manage	all supported MCP read and write scopes

MCP Commands

roster tools
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 draft 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_...

MCP Tool Mapping

CLI command	MCP tool	Required scope
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

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": "https://roster.example.com/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.