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 STUDIO_PROFILE:

studio workflows list --profile dev
STUDIO_PROFILE=dev studio workflows list

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

studio profiles     # list them; * marks the active one

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

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

Setting defaults

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

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

API keys are not settable here. Use studio login, or STUDIO_API_KEY for CI.

Where settings come from

Each setting resolves independently, and the first match wins:

For hosted Studio, set the endpoint to https://agent-studio.seeyu.ai: studio login --endpoint and studio configure --set-endpoint save it to the profile, and STUDIO_ENDPOINT sets it for one shell or CI job.

studio whoami prints the winning source for each setting:

studio whoami

The files

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

[default]
endpoint = https://agent-studio.seeyu.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 ~/.studio/credentials, written 0600:

[default]
api_key = studio_…

[dev]
api_key = studio_…

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

Updates

The CLI checks for a newer stable release at most once per day on eligible interactive invocations. It prints an optional notice to stderr and continues your command. Installation only happens when you run studio update.

Run studio update to update immediately, including in CI and when automatic checks are disabled. It requires a global installation and verifies that the package manager targets the running copy before installing. Supported managers are npm, pnpm, Bun, and Yarn Classic. For custom installations, select the manager with studio update --package-manager bun. Project-local and temporary package-runner copies must be updated through their package manager.

Manual updates preserve the stable, staging, or dev release channel. Installation failures stop with an error; concurrent update attempts are refused. Installer output goes to stderr and does not mix with JSON output on stdout. The updater resolves the channel through the selected package manager before installing. Older registry or mirror releases are refused; a newer release is installed by its exact version so a moving tag cannot change the target.

Checks are skipped in CI, when stderr is redirected, under npm exec or npx, from a repository checkout, and for prerelease versions. Set STUDIO_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 Studio 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 ~/.studio/update-check.json, or under STUDIO_CONFIG_DIR. STUDIO_CONFIG_FILE and STUDIO_CREDENTIALS_FILE do not relocate it. If the cache cannot be written, eligible invocations may check again. Concurrent commands can also each check. Registry checks have a one-second deadline; package-manager installation has a five-minute deadline. Registry-check failures suppress the check, while installer failures are reported.

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 STUDIO_ENDPOINT (https://agent-studio.seeyu.ai for hosted Studio), STUDIO_API_KEY, and STUDIO_WORKSPACE; no saved login or config file is required.

Choosing a workspace

Workspace-scoped commands need a workspace:

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

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

studio workspaces list
studio profile add acme --workspace 7e2d9c14-6b83-4a55-8f01-c4d3e9a76b28
studio --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.

studio billing status, studio billing logs, and studio 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:

studio --output table configure --set-output json