Authentication

sim login signs you in through your browser. It prefers OAuth, which stores a short-lived login that renews itself, and selects API-key pairing for remote terminals or servers without OAuth support. In CI you supply an existing API key through the environment instead.

Signing in

sim login

Choose a method explicitly when the credential type matters:

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

--method oauth requires a server with OAuth support and authentication enabled; it never falls back to an API key. Explicit OAuth selection also overrides SSH/headless detection; your browser still needs to reach the CLI's local callback. --method api-key uses pairing-code approval to create a new permanent API key. To supply an existing key, set SIM_API_KEY instead.

API-key pairing requires a server that supports platform API keys. Upgrade older deployments that only issue copilot keys before starting login; those keys cannot authenticate the platform CLI.

OAuth login opens your browser on Sim's sign-in page, then on a consent page that names the Sim CLI and what it will be able to do. Approve, and the browser hands control back 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>

This is the OAuth 2.0 authorization-code flow with PKCE and a loopback redirect, aligned with current OAuth security guidance. The browser only ever carries a one-time code; the tokens are exchanged over the terminal's own connection and written to ~/.sim/credentials with 0600 permissions. Access tokens last an hour and are renewed automatically from a refresh token. The complete login has a fixed 30-day lifetime; after it expires, run sim logout, then sign in again.

Over SSH or in a container

OAuth login needs your browser to reach a listener on the machine running sim. When it cannot — an SSH session, a dev container, a remote box — use the API-key pairing flow. The CLI selects it automatically in an SSH session when no method or callback port is specified:

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

The terminal prints a pairing code and a URL you can open on any 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.

The handoff issues a permanent personal API key rather than a renewing login, so revoke it under Settings → API keys when you are done with that machine. It also works when OAuth is unavailable or switched off, provided the server supports platform API-key pairing. When --method is omitted, the CLI checks OAuth availability and selects pairing if unavailable; that discovery does not verify pairing compatibility. An explicit --method oauth fails in that case.

--read-only and --callback-port belong to OAuth login and have no meaning here, so combining either with the handoff stops the login rather than storing a credential you did not ask for. If your SSH session forwards a port from the remote loopback interface to the browser's machine, use --method oauth --callback-port <port> with that port. An ordinary container port publication cannot reach a listener bound to the container's own loopback interface; use --method api-key there.

Picking a workspace

A normal login can act across every workspace you belong to; --read-only limits it to read operations. The profile's workspace setting only decides the default target. Set it after signing in, or pass --workspace per command:

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

With the pairing-code handoff you choose the default workspace on the approval page instead.

To target another workspace without a second login, add a workspace profile:

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

The new profile stores auth_profile = default and its own workspace. Omit --workspace in an interactive terminal to choose from the workspaces your login can access; scripts must provide the workspace ID explicitly. The picker is capped at 1,000 entries and asks for an explicit ID above that.

Checking who you are

sim whoami                # resolved settings, plus a live check that they work
sim whoami --no-verify    # resolved settings only, no request

Prints the resolved endpoint, workspace, and output format, which source each value came from, and whether the profile holds an OAuth login or an API key, then reads the configured workspace to prove the credential is accepted and can reach it.

It exits 0 when the check passes, 1 when the credentials are wrong, and 2 when the check could not be made at all — no workspace to check against, or an endpoint that did not answer. The split matters in CI: only 1 is fixed by logging in again.

Signing out

sim logout           # sign out of Sim and remove the stored login
sim logout --all     # remove the profile entirely, including its settings

For an OAuth login, sim logout revokes that login's complete token family before removing it from disk, including access tokens issued before earlier rotations. Other machines that ran their own sim login remain signed in. To cut off every independent login for the client, revoke the grant under Settings → General → Authorized apps.

A workspace profile that shares authentication cannot remove the shared login. Remove only that local profile with sim logout --all --profile <name>, or log out of the authentication profile named by the error message. Removing an authentication profile entirely is refused until its workspace profiles are removed, so it cannot leave dangling references.

Authenticating CI

Set an API key and workspace in the environment; no saved login is required, and the environment key overrides any stored 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

Create the key in Sim under Settings → API keys. Store it as a secret in your CI provider — never commit it.

SIM_CONFIG_DIR relocates both files if you need them somewhere other than ~/.sim, such as a runner with no writable home directory.

GitHub Actions

jobs:
  digest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -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 }}

Several accounts and workspaces

Use separate logins for separate 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 workspace profiles when one login should target 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

See Configuration for how profiles are stored and resolved.

Self-hosted and non-production deployments

Point the CLI at any deployment with --endpoint, then sign in against it:

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

Save it to avoid repeating the flag:

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

OAuth sign-in is available by default when server authentication is enabled. DISABLE_AUTH=true disables OAuth. Servers without OAuth use the pairing-code handoff when they support platform API keys. See Sign in with Sim for server configuration and upgrade requirements.

Where the login is stored

Logins live in ~/.sim/credentials, written 0600, separate from the non-secret ~/.sim/config. Commit config to a dotfiles repo if you like; never credentials.

[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_…

A profile holds one login. A stored API key can be replaced after confirmation or with --yes; a live OAuth login must be revoked with sim logout before signing in again. Several sim commands running at once share one renewal, so a parallel shell loop cannot sign itself out.

Run sim login separately on each machine. Copying ~/.sim/credentials copies one single-use refresh-token family; simultaneous use from both copies is treated as token replay and revokes that login. If a refresh response is lost because the process or connection stops, the CLI does not retry the consumed token: run sim logout, then sim login again. This fail-closed behavior keeps a copied token from surviving an ambiguous refresh.

Organization audit logs

sim audit-logs requires a personal credential — an OAuth login, or the personal API key sim login --method api-key issues. A workspace-scoped key cannot read organization-level audit logs.