Configuration

The CLI resolves an endpoint, credential, workspace, and output format. The credential can be a stored OAuth login or an API key. Each resolves independently, so a saved default can still be overridden for a single command.

Profiles

A profile selects one set of defaults, in the style of the AWS CLI. It normally uses its same-named stored identity, but a workspace profile can share another profile's identity through auth_profile. Select one with -P, --profile, or SIM_PROFILE:

sim workflows list --profile dev
SIM_PROFILE=dev sim workflows list

The profile is named default when you do not pick one.

sim profiles     # list them; * marks the active one

Add a profile for another workspace without creating or copying an API key:

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

Setting defaults

sim configure --set-endpoint http://localhost:3000 --profile dev
sim configure --set-workspace 5c81f3a6-0e27-4b94-8d15-a7f60c39b2e8 --profile dev
sim configure --set-output json

Run sim configure with no flags to print the profile's stored settings.

API keys are not settable here. Use sim login, or SIM_API_KEY for CI.

Where settings come from

Each setting resolves independently, and the first match wins:

sim whoami prints the winning source for each setting:

sim whoami

The files

Non-secret settings live in ~/.sim/config. It is safe to commit to a dotfiles repo:

[default]
endpoint = https://www.sim.ai
workspace = 2f6d0b1c-8a34-4d92-b7e5-31c8a0f45d67
output = table

[profile dev]
endpoint = http://localhost:3000
workspace = 5c81f3a6-0e27-4b94-8d15-a7f60c39b2e8

[profile acme]
auth_profile = default
workspace = 7e2d9c14-6b83-4a55-8f01-c4d3e9a76b28

Keys live in ~/.sim/credentials, written 0600:

[default]
api_key = sim_…

[dev]
api_key = sim_…

Section naming follows the AWS convention: [profile dev] in config, [dev] in credentials. The default profile is [default] in both.

auth_profile references one direct profile and shares its endpoint and stored login, whether OAuth or an API key. Workspace and output remain local. References cannot be chained, and a shared profile cannot also set its own endpoint or stored login.

Environment variables

Update notices

The CLI checks for a newer release at most once per day on eligible interactive invocations. Notices go to stderr and show an upgrade command for the package manager that installed Sim.

Checks are skipped in CI, when stderr is redirected, under npm exec or npx, from a repository checkout, and for prerelease versions. Set SIM_NO_UPDATE_CHECK=1 to disable them.

The check uses registry.npmjs.org unless npm_config_registry names another HTTP(S) registry. It sends no Sim API key, workspace, or command. Query-string credentials in a configured registry URL are preserved; URLs containing username/password userinfo are rejected. Empty registry values use npm, while malformed non-empty values disable the check. Redirects are not followed.

The daily cache is ~/.sim/update-check.json, or under SIM_CONFIG_DIR. SIM_CONFIG_FILE and SIM_CREDENTIALS_FILE do not relocate it. If the cache cannot be written, eligible invocations may check again. Concurrent commands can also each check. Requests have a one-second deadline.

Node's fetch uses HTTP(S)_PROXY when opted in with NODE_USE_ENV_PROXY=1 (Node 22.21+ or 24.0+) or --use-env-proxy (Node 22.21+ or 24.5+).

For CI, set SIM_API_KEY and SIM_WORKSPACE; no saved login or config file is required.

Choosing a workspace

Workspace-scoped commands need a workspace:

sim tables list --workspace 9b4c7e02-1d58-4f36-a0c9-6e2b85df413a
sim configure --set-workspace 2f6d0b1c-8a34-4d92-b7e5-31c8a0f45d67
export SIM_WORKSPACE=2f6d0b1c-8a34-4d92-b7e5-31c8a0f45d67

For a reusable selection, create a workspace profile backed by the current stored login:

sim workspaces list
sim profile add acme --workspace 7e2d9c14-6b83-4a55-8f01-c4d3e9a76b28
sim --profile acme tables list

When --workspace is omitted in a terminal, profile add presents an interactive picker, capped at 1,000 entries. It refuses environment-only keys and endpoint overrides because those values would disappear in another shell.

sim billing status, sim billing logs, and sim audit-logs list accept --all-workspaces to drop the filter instead. It cannot be combined with --workspace.

Repairing a bad setting

An invalid output value fails with the list of accepted formats. A higher-priority source still wins, so you can repair a profile without editing the file:

sim --output table configure --set-output json