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://sim.ai/cli/auth?request=…&scope=platform
Waiting for approval…

✓ Logged in. Key stored in /Users/you/.sim/credentials
  Personal key, defaulting to ws_abc123. 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 ws_other

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

Checking who you are

sim whoami

Prints the resolved endpoint, workspace, output format, and account, and which source each value came from.

Signing out

sim logout           # remove the stored key
sim logout --all     # remove the profile entirely, including its settings

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="ws_abc123"

sim workflows run wf_7Yb2 --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 wf_7Yb2 --output json
        env:
          SIM_API_KEY: ${{ secrets.SIM_API_KEY }}
          SIM_WORKSPACE: ${{ vars.SIM_WORKSPACE }}

Several accounts at once

Each profile holds one identity and one set of defaults:

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

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

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.