Authentication

The CLI authenticates with a Sim API key. sim login mints and stores one; in CI you supply one through the environment instead.

Signing in

sim login

The terminal prints a pairing code and a URL:

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.

There is no loopback listener, so this works over SSH and inside containers.

Confirm the pairing code in the browser matches the one in your terminal before approving. That check is what binds the approval to your terminal.

Option	What it does
`--no-browser`	Print the URL instead of opening a browser
`--scope <scope>`	Key space to mint from: `platform` (default) or `copilot`
`-y, --yes`	Overwrite an existing profile without prompting

You choose the workspace on the approval page. sim login issues a personal key. The workspace you pick becomes the profile's default workspace; it does not restrict the key to that workspace. Target another workspace the key can reach with --workspace:

sim workflows list --workspace 9b4c7e02-1d58-4f36-a0c9-6e2b85df413a

sim login --workspace <id> preselects a workspace in the picker, and re-logging into an existing profile preselects the one already configured.

To save another workspace without minting or copying another personal key, add a workspace profile:

sim workspaces list
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 the active key 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, and which source each value came from, then reads the configured workspace to prove the key 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           # remove the stored key
sim logout --all     # remove the profile entirely, including its settings

A workspace profile that shares authentication cannot remove the shared key. 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.

sim logout removes the key from disk but does not revoke it. Revoke keys in Sim under Settings → API keys.

Authenticating CI

Set the key and workspace in the environment; the CLI never reads or writes a config file:

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

.github/workflows/nightly.yml

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 personal key 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

Where the key is stored

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

~/.sim/credentials

[default]
api_key = sim_…

[dev]
api_key = sim_…

Organization audit logs

sim audit-logs requires a personal API key — the kind sim login issues. A workspace-scoped key cannot read organization-level audit logs.