Configuration

The CLI has four settings: endpoint, API key, workspace, and output format. 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 only its endpoint and API key; workspace and output remain local. References cannot be chained, and a shared profile cannot also set its own endpoint or API key.

Environment variables

Update notices

On eligible invocations, the CLI uses a daily cache before asking registry.npmjs.org what is published under the latest tag. Prerelease installs are skipped entirely, so a -preview or -dev build is never told to upgrade. When a newer one exists, it prints a single line on stderr naming both versions and the command that upgrades:

Update available: sim 2.1.2 → 2.1.5. Run: npm install -g sim@latest

Apart from the configured registry URL, the request identifies only the CLI version — no Sim API key, workspace, or command — and it never follows a redirect away from the registry it asked.

One caveat worth stating plainly: if you point npm_config_registry at a private mirror, the check goes to that mirror instead of npm. Query-string credentials (an Artifactory or Nexus ?token=…, for example) are preserved and sent as part of the configured registry request — they have to be, or the mirror would reject it. As with other registry traffic, configured proxies or TLS inspection can observe what that network setup permits. A registry URL containing username/password userinfo, such as https://user:password@registry.example, is rejected and no update check is made.

An empty or whitespace-only npm_config_registry is treated as unset, so the public registry remains the default. Non-empty malformed and non-HTTP(S) values disable the update check rather than making an unexpected public request.

The notice is skipped entirely when:

• SIM_NO_UPDATE_CHECK is set to anything but 0 or false
• stderr is not a terminal, so redirected and piped output is never affected
• a CI environment variable is present (CI, GITHUB_ACTIONS, JENKINS_URL, TEAMCITY_VERSION, BUILDKITE)
• the CLI is running under npm exec or npx, which may use a project-local or ephemeral package where global-install advice is inappropriate
• the CLI is running from a checkout of the sim repository, whose version deliberately trails the published one
• the installed version is a prerelease

The daily pace comes from a timestamp in the config directory's update-check.json: ~/.sim/update-check.json by default, or under SIM_CONFIG_DIR when that is set. SIM_CONFIG_FILE and SIM_CREDENTIALS_FILE do not move the cache, so it may not sit beside a file relocated with either of those variables.

This throttle is best-effort across processes. Two commands that start together can both see a stale cache and check. Cache replacement is atomic, so either complete write can win without leaving a partially interleaved file. If the cache cannot be written — for example, because the config directory is read-only — every eligible invocation attempts a check because there is no timestamp to reuse.

The registry check has a one-second deadline. On expiry, the CLI terminates its short-lived request process so stalled DNS, connection, or response work cannot remain active and delay the command. SIM_NO_UPDATE_CHECK=1 still turns the check off.

The command the notice prints matches how Sim was installed — npm install -g, pnpm add -g, bun add -g, or yarn global add — so running it updates the executable already on your PATH rather than installing a second copy under a different package manager.

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 and nothing needs to touch the filesystem at all.

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