CLI Authentication

The Roster CLI supports two authentication modes:

• OAuth browser login for humans
• API-key bearer auth for automation, CI, and agents

The CLI is MCP-first. Both auth modes authenticate requests to the Roster MCP endpoint.

OAuth Profiles

Use browser login for human terminal sessions:

roster login <your-roster-public-url>/mcp --name prod
roster auth status
roster resolve "Who should approve the Helios renewal?"

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.

An OAuth profile stores:

• MCP endpoint URL
• OAuth client information
• granted scopes
• OAuth credentials
• optional profile alias

API keys are not stored in OAuth profiles.

Profile Storage

Profile storage defaults to:

~/.roster/config.json

Override it with either ROSTER_HOME or --config-dir:

ROSTER_HOME=/secure/roster-home roster auth profiles
roster --config-dir /secure/roster-home auth profiles

Selecting Profiles

Use --profile when you want a specific saved OAuth profile for one command:

roster --profile prod projects list --limit 3

Use roster auth use when you want to make a profile the default:

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

Profile selectors can be aliases, MCP URLs, or profile keys.

Auth Precedence

The CLI resolves the MCP endpoint and credentials separately.

MCP endpoint selection precedence is:

1. --mcp-url
2. ROSTER_MCP_URL
3. The MCP URL stored on the --profile profile or selected OAuth profile

Credential selection precedence is:

1. --api-key
2. ROSTER_API_KEY
3. OAuth credentials from the matching saved profile

If --api-key or ROSTER_API_KEY is present, the CLI uses bearer auth instead of OAuth profile credentials.

Use --profile to select a saved OAuth profile. When no explicit MCP URL is provided, that profile also supplies the MCP endpoint URL.

Scope Presets

roster login uses --scope-preset resolve by default.

Preset	Scopes
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

Add custom scopes with --scope:

roster login <your-roster-public-url>/mcp \
  --scope-preset read \
  --scope mcp:custom:read

Use read when you need list and get commands across read-only Roster MCP tools. Use manage only when the profile should create, update, or delete Roster project resources. Use admin for platform administration commands; the authenticated identity must still be an active platform admin, and scopes do not elevate the user’s platform role.

Profile Commands

Check the current auth source:

roster auth status
roster --profile prod auth status

List saved OAuth profiles:

roster auth profiles

Remove saved OAuth credentials from a profile:

roster auth logout
roster auth logout prod

Delete the whole profile and any aliases that point to it:

roster auth logout prod --remove

Manage 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.

API-Key Automation

Use API keys for CI, automation scripts, and agents that should not launch a browser:

ROSTER_API_KEY="<your-roster-api-key>" roster --mcp-url <your-roster-public-url>/mcp \
  resolve "Who should approve the Helios renewal?"

Or pass the key explicitly:

roster --mcp-url <your-roster-public-url>/mcp \
  --api-key "<your-roster-api-key>" \
  projects list --json

API keys are never persisted by the CLI.

Agent Usage

Agents should prefer API-key auth, --non-interactive, and --json:

ROSTER_API_KEY="<your-roster-api-key>" roster \
  --mcp-url <your-roster-public-url>/mcp \
  --non-interactive \
  --json \
  call list_projects limit=10

All JSON emitted by the CLI uses snake_case keys, including wrapper keys such as mcp_url, structured_content, error_code, and request_id.