The installed CLI resolves an endpoint, credential, workspace, and output format independently. A saved default can be overridden for one command.
Commands Sim runs inside Chat receive their identity, endpoint, and workspace from Chat. Local login, logout, whoami, profiles, configure, update, and telemetry commands are unavailable there; local profiles and config files do not apply.
Profiles
A profile stores defaults and normally uses its same-named stored login. A workspace profile can share another profile's authentication through auth_profile.
Select a profile with -P, --profile, or SIM_PROFILE. A flag wins over the environment; omission selects default:
In table output, * marks the selected profile. JSON output includes an active boolean. An explicitly named profile must exist; login and configure --set-* can create one.
Setting defaults
Use configure to save settings for the selected profile:
Without setter flags, sim configure prints the profile's stored settings as text. Credentials are set through login, or supplied with SIM_API_KEY for CI.
The global --endpoint, --workspace, and --output flags affect one invocation. configure rejects them; use the corresponding --set-* flag to persist a setting.
Where settings come from
The first applicable source wins for each setting:
SIM_API_KEY overrides a stored OAuth login or API key. There is no command-line API-key option. Use sim whoami to see each resolved value and its source; --no-verify skips API requests.
The files
Non-secret settings live in ~/.sim/config and can be kept in a dotfiles repository:
API keys and OAuth tokens live in ~/.sim/credentials, written with 0600 permissions. Never commit that file:
Named config sections use [profile dev]; credentials use [dev]. The default section is [default] in both files. See Stored logins for OAuth fields and refresh behavior.
Shared authentication
auth_profile names one direct authentication profile. It shares that profile's endpoint and stored OAuth login or API key; workspace and output stay local. References cannot be chained. A shared profile cannot set its own endpoint or stored login.
Create a shared profile from a stored login:
profile add refuses environment-only credentials and endpoint overrides because those values would not persist in a new shell. Save the endpoint and sign in before creating the profile.
An OAuth login is bound to its issuing deployment. Log out before changing or removing that authentication profile's endpoint. Change a shared endpoint on the authentication profile, not its workspace profiles.
Choosing a workspace
Workspace-scoped commands need a target. Set it for one command, in the profile, or in the environment:
To select an accessible workspace interactively, omit --workspace from sim profile add <name>. The picker accepts at most 1,000 workspaces; above that, supply an ID. Non-interactive scripts must always supply it.
sim billing status, sim billing logs, and sim audit-logs list accept --all-workspaces to omit the workspace filter. Do not combine it with an explicit --workspace.
Environment variables
For CI, supply SIM_API_KEY and SIM_WORKSPACE; a saved login or config file is not required. SIM_CONFIG_DIR can point at a writable runner directory.
The request timeout does not change server execution limits. Run/operation waits have a separate --wait-timeout; see Scripting. Debug URLs can include request selectors, so review them before sharing diagnostics. See Usage data for the separate anonymous event fields.
Updates
Eligible interactive invocations check for a newer stable release using a daily cache. A notice goes to stderr and the command continues. Installation happens only when you run:
Manual updates also work in CI and when automatic checks are disabled. They require a global installation and verify that the selected package manager owns the running copy. Supported managers are Bun, npm, pnpm, and Yarn Classic. Select one explicitly for a custom installation:
Update project-local dependencies and temporary package-runner copies through their package manager. A manual update preserves the stable, staging, or dev release channel. The updater refuses older registry/mirror releases and installs the resolved exact version. Concurrent updates are refused; installation errors stop the command. Installer output goes to stderr.
Automatic notices
Checks are skipped in CI, when stderr is redirected, for prerelease versions, from a repository checkout, and for temporary/project-local installations including npm exec and npx. Set SIM_NO_UPDATE_CHECK=1 to disable them.
The cache lives at ~/.sim/update-check.json, or under SIM_CONFIG_DIR. SIM_CONFIG_FILE and SIM_CREDENTIALS_FILE do not move it. A failed cache write or concurrent invocations can cause additional checks.
Registry checks have a one-second deadline and fail quietly. Package-manager installation has a five-minute deadline and reports failures.
Registry and proxy behavior
Automatic checks use registry.npmjs.org unless npm_config_registry supplies another HTTP(S) registry. They send no Sim API key, workspace, or command. Configured query-string credentials are preserved; username/password URL userinfo is rejected. Empty registry values use the default, malformed non-empty values disable checking, and redirects are not followed.
Node's fetch reads HTTP(S)_PROXY when opted in with NODE_USE_ENV_PROXY=1 on Node 22.21+ or 24.0+. The --use-env-proxy flag requires Node 22.21+ or 24.5+. See Node's proxy options.
Repairing a bad setting
An invalid output format stops profile resolution. Temporarily override it through the environment, then save a valid default:
If the invalid value comes from SIM_OUTPUT, correct or unset that variable too. A higher-priority environment value still overrides the repaired profile.