Authentication

Use sim login for a stored browser-approved login, or supply an existing API key for CI. These settings apply to the installed CLI. Commands Sim runs inside Chat use your session identity; local login and profile-management commands are unavailable. See Configuration for that boundary.

Signing in

sim login

The CLI prefers OAuth on a local machine. SSH sessions and headless Linux terminals select API-key pairing; a server without OAuth also selects pairing when no method is specified. An unreachable server is an error, not a reason to fall back.

Choose the method explicitly when the credential type matters:

sim login --method oauth
sim login --method api-key

Explicit OAuth never falls back and overrides remote-session detection. Pairing creates a new key; use SIM_API_KEY to supply one you already have. Older deployments that issue only copilot keys must be upgraded: those keys cannot authenticate the platform CLI. OAuth discovery does not verify pairing compatibility.

OAuth approval

The CLI opens Sim's sign-in page and then a consent page naming the Sim CLI and its requested access. Approve the request to return control to the terminal:

Signing in to https://www.sim.ai as profile default

https://www.sim.ai/api/auth/oauth2/authorize?client_id=sim-cli&…

Waiting for you to approve in the browser…

✓ Logged in. Login stored in /Users/you/.sim/credentials
  Renews itself; revoke it any time in Settings → General → Authorized apps, or with: sim logout
  No default workspace. Set one with: sim configure --set-workspace <id>

The login uses an authorization code, Proof Key for Code Exchange (PKCE), and a loopback redirect. The browser returns a one-time code; the terminal exchanges it for tokens over its own connection. Tokens are stored in ~/.sim/credentials with 0600 permissions.

Access tokens last one hour. The refresh-token family has a fixed 30-day lifetime; renewal does not extend it. After expiry, log out and sign in again.

A profile holds one stored credential. Replacing an API key requires confirmation or --yes. An existing OAuth login must be revoked with sim logout before another login; --yes does not bypass this.

Over SSH or in a container

OAuth needs the browser to reach a listener on the machine running sim. Use pairing when that connection is unavailable:

sim login --method api-key --no-browser

The terminal prints a code and an approval URL you can open on another device:

Signing in to https://www.sim.ai as profile default

Pairing code: K7M2-P9XT
Confirm this code matches what the browser shows before approving.

https://www.sim.ai/cli/auth?request=…&scope=platform
Waiting for approval…

✓ Logged in. Key stored in /Users/you/.sim/credentials
  Personal key, defaulting to 2f6d0b1c-8a34-4d92-b7e5-31c8a0f45d67. Override per command with --workspace.

--read-only and --callback-port are OAuth-only. Combining either with pairing stops login instead of silently ignoring the option.

For an SSH tunnel that forwards the remote loopback port to your browser's machine, choose OAuth and specify that same port:

sim login --method oauth --callback-port 8765 --no-browser

Supplying a callback port also overrides automatic SSH detection. An ordinary container port publication cannot reach a listener bound to the container's own loopback interface; use pairing there unless you provide a working loopback route.

Picking a workspace

A personal login can act in accessible workspaces, subject to current roles, policies, and resource access. --read-only narrows OAuth scope; a default workspace only selects a target and does not narrow credential scope.

After OAuth login, select a default or pass a workspace per command:

sim workspaces list
sim configure --set-workspace 2f6d0b1c-8a34-4d92-b7e5-31c8a0f45d67
sim workflows list --workspace 9b4c7e02-1d58-4f36-a0c9-6e2b85df413a

Pairing sets the default workspace chosen on the approval page.

To reuse a stored login with another default workspace:

sim profile add acme --workspace 7e2d9c14-6b83-4a55-8f01-c4d3e9a76b28
sim --profile acme whoami

The new profile references the active authentication profile through auth_profile and stores its own workspace. With the default login active, that reference is auth_profile = default.

Omit --workspace in an interactive terminal to choose an accessible workspace. The picker is capped at 1,000 entries; scripts and larger inventories require an explicit ID. See Configuration for profile resolution.

Checking who you are

sim whoami
sim whoami --no-verify

whoami reports the endpoint, credential type, workspace, output format, and where each setting came from. It checks authentication through API metadata when available, then reads the selected workspace to verify access. Older servers can fall back to the workspace check.

For exit 1, inspect the endpoint and workspace before signing in again. A valid login cannot fix a wrong workspace or missing permission. Use --no-verify for offline inspection.

Authenticating CI

Create a key under Settings → Sim API keys, then store it in your CI secret manager. Supply the key and workspace without running login:

export SIM_API_KEY="sim_…"
export SIM_WORKSPACE="2f6d0b1c-8a34-4d92-b7e5-31c8a0f45d67"

sim workflows run 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 --input '{"source":"nightly"}' --output json

The environment key overrides stored authentication. Use a workspace key only for supported workspace-scoped operations; organization audit logs and fork administration require a personal credential. Never commit credentials. SIM_CONFIG_DIR relocates local state when a runner has no writable home directory.

GitHub Actions

This job installs Node for the CLI and Bun to install the package. Add it to a workflow with your chosen trigger:

jobs:
  digest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - uses: oven-sh/setup-bun@v2
      - run: bun add -g sim
      - run: sim workflows run 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 --output json
        env:
          SIM_API_KEY: ${{ secrets.SIM_API_KEY }}
          SIM_WORKSPACE: ${{ vars.SIM_WORKSPACE }}

See Scripting for asynchronous runs and command-specific failure handling.

Several accounts and workspaces

Use separate authentication profiles for different identities or deployments:

sim login --profile dev --endpoint http://localhost:3000
sim login --profile prod

sim workflows list --profile dev
sim workflows list --profile prod

Use shared workspace profiles when the same stored identity targets several workspaces:

sim profile add marketing --workspace c3a70e58-9f21-4d6b-b842-05e7f19c6a3d
sim profile add support --workspace e0d94b17-3c62-45af-9718-b6a2c8035f4e

sim workflows list --profile marketing
sim workflows list --profile support

Shared profiles retain separate workspace/output settings but share an endpoint and stored login. References are direct, never chained. Log in against the authentication profile rather than a profile that shares it.

Self-hosted and non-production deployments

Use HTTPS for remote sign-in. Both OAuth and pairing refuse non-loopback HTTP endpoints. Loopback development addresses can use HTTP:

sim login --profile local --endpoint http://localhost:3000

Login saves the endpoint. You can also configure it before signing in:

sim configure --set-endpoint http://localhost:3000 --profile local

An OAuth login belongs to its issuing deployment. Log out before changing or removing that endpoint. API keys must also belong to the selected deployment.

OAuth is available by default when server authentication is enabled. DISABLE_AUTH=true disables OAuth. Servers without OAuth can use pairing if they support platform API keys. See Sign in with Sim for server setup and upgrade requirements.

Where the login is stored

Stored authentication lives in ~/.sim/credentials, written 0600. Non-secret defaults live separately in ~/.sim/config. Never copy credentials into a dotfiles repository:

[default]
access_token = sim_oat_…
refresh_token = sim_ort_…
token_expires_at = 1788547200000
oauth_issuer = https://www.sim.ai/api/auth
oauth_login_id = …
oauth_scope = offline_access api:read api:write

[ci-box]
api_key = sim_…

Concurrent local commands coordinate OAuth renewal through the credentials lock. A process rereads credentials after taking the lock and adopts an already-renewed token instead of reusing the old refresh token.

Run login separately on each machine. Copying the credentials file copies one single-use refresh-token family. Concurrent use of those copies can be treated as replay and revoke that login.

If a refresh response is lost after the server consumes the token, the CLI does not retry that token. Recover with logout and a new login:

sim logout --profile dev
sim login --profile dev

Signing out

sim logout
sim logout --all

The first command removes stored authentication; --all also removes the profile's settings.

For OAuth, logout revokes that login's complete token family before clearing it locally, including access tokens from earlier rotations. Independent logins on other machines remain signed in. To revoke the client's grant across independent logins, use Settings → General → Authorized apps.

A workspace profile cannot remove its shared login. Remove only that local profile with sim logout --all --profile <name>, or log out of its authentication profile. Deleting an authentication profile entirely is refused while workspace profiles still reference it.

Organization audit logs

sim audit-logs requires a personal credential: an OAuth login or personal API key. Pairing creates a personal key. A workspace key cannot read organization audit logs.

Related docs

• Configuration
• Scripting
• Profiles commands
• Troubleshooting