Authentication

studio login signs you in through your browser. It prefers OAuth, which stores a short-lived login that renews itself, and selects API-key pairing for remote terminals or servers without OAuth support. In CI you supply an existing API key through the environment instead.

Signing in

studio login --endpoint https://agent-studio.seeyu.ai

For hosted Studio, pass --endpoint https://agent-studio.seeyu.ai on your first login. The login saves it to the profile, so later commands and logins use it without the flag.

Choose a method explicitly when the credential type matters:

studio login --method oauth
studio login --method api-key

--method oauth requires a server with OAuth support and authentication enabled; it never falls back to an API key. Explicit OAuth selection also overrides SSH/headless detection; your browser still needs to reach the CLI's local callback. --method api-key uses pairing-code approval to create a new permanent API key. To supply an existing key, set STUDIO_API_KEY instead.

API-key pairing requires a server that supports platform API keys. Upgrade older deployments that only issue copilot keys before starting login; those keys cannot authenticate the platform CLI.

OAuth login opens your browser on Studio's sign-in page, then on a consent page that names the Studio CLI and what it will be able to do. Approve, and the browser hands control back to the terminal:

Signing in to https://agent-studio.seeyu.ai as profile default

https://agent-studio.seeyu.ai/api/auth/oauth2/authorize?client_id=studio-cli&…

Waiting for you to approve in the browser…

✓ Logged in. Login stored in /Users/you/.studio/credentials
  Renews itself; revoke it any time in Settings → General → Authorized apps, or with: studio logout
  No default workspace. Set one with: studio configure --set-workspace <id>

This is the OAuth 2.0 authorization-code flow with PKCE and a loopback redirect, aligned with current OAuth security guidance. The browser only ever carries a one-time code; the tokens are exchanged over the terminal's own connection and written to ~/.studio/credentials with 0600 permissions. Access tokens last an hour and are renewed automatically from a refresh token. The complete login has a fixed 30-day lifetime; after it expires, run studio logout, then sign in again.

Over SSH or in a container

OAuth login needs your browser to reach a listener on the machine running studio. When it cannot — an SSH session, a dev container, a remote box — use the API-key pairing flow. The CLI selects it automatically in an SSH session when no method or callback port is specified:

studio login --method api-key --no-browser --endpoint https://agent-studio.seeyu.ai

The terminal prints a pairing code and a URL you can open on any device:

Signing in to https://agent-studio.seeyu.ai as profile default

Pairing code: K7M2-P9XT
Confirm this code matches what the browser shows before approving.

https://agent-studio.seeyu.ai/cli/auth?request=…&scope=platform
Waiting for approval…

✓ Logged in. Key stored in /Users/you/.studio/credentials
  Personal key, defaulting to 2f6d0b1c-8a34-4d92-b7e5-31c8a0f45d67. Override per command with --workspace.

The handoff issues a permanent personal API key rather than a renewing login, so revoke it under Settings → API keys when you are done with that machine. It also works when OAuth is unavailable or switched off, provided the server supports platform API-key pairing. When --method is omitted, the CLI checks OAuth availability and selects pairing if unavailable; that discovery does not verify pairing compatibility. An explicit --method oauth fails in that case.

--read-only and --callback-port belong to OAuth login and have no meaning here, so combining either with the handoff stops the login rather than storing a credential you did not ask for. If your SSH session forwards a port from the remote loopback interface to the browser's machine, use --method oauth --callback-port <port> with that port. An ordinary container port publication cannot reach a listener bound to the container's own loopback interface; use --method api-key there.

Picking a workspace

A normal login can act across every workspace you belong to; --read-only limits it to read operations. The profile's workspace setting only decides the default target. Set it after signing in, or pass --workspace per command:

studio workspaces list
studio configure --set-workspace 2f6d0b1c-8a34-4d92-b7e5-31c8a0f45d67
studio workflows list --workspace 9b4c7e02-1d58-4f36-a0c9-6e2b85df413a

With the pairing-code handoff you choose the default workspace on the approval page instead.

To target another workspace without a second login, add a workspace profile:

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

The new profile stores auth_profile = default and its own workspace. Omit --workspace in an interactive terminal to choose from the workspaces your login can access; scripts must provide the workspace ID explicitly. The picker is capped at 1,000 entries and asks for an explicit ID above that.

Checking who you are

studio whoami                # resolved settings, plus a live check that they work
studio whoami --no-verify    # resolved settings only, no request

Prints the resolved endpoint, workspace, and output format, which source each value came from, and whether the profile holds an OAuth login or an API key, then reads the configured workspace to prove the credential is accepted and can reach it.

It exits 0 when the check passes, 1 when the credentials are wrong, and 2 when the check could not be made at all — no workspace to check against, or an endpoint that did not answer. The split matters in CI: only 1 is fixed by logging in again.

Signing out

studio logout           # sign out of Studio and remove the stored login
studio logout --all     # remove the profile entirely, including its settings

For an OAuth login, studio logout revokes that login's complete token family before removing it from disk, including access tokens issued before earlier rotations. Other machines that ran their own studio login remain signed in. To cut off every independent login for the client, revoke the grant under Settings → General → Authorized apps.

A workspace profile that shares authentication cannot remove the shared login. Remove only that local profile with studio logout --all --profile <name>, or log out of the authentication profile named by the error message. Removing an authentication profile entirely is refused until its workspace profiles are removed, so it cannot leave dangling references.

Authenticating CI

Set the endpoint, an API key, and a workspace in the environment; no saved login is required, and the environment key overrides any stored login:

export STUDIO_ENDPOINT="https://agent-studio.seeyu.ai"
export STUDIO_API_KEY="studio_…"
export STUDIO_WORKSPACE="2f6d0b1c-8a34-4d92-b7e5-31c8a0f45d67"

studio workflows run 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 --input '{"source":"nightly"}' --output json

Create the key in Studio under Settings → API keys. Store it as a secret in your CI provider — never commit it.

STUDIO_CONFIG_DIR relocates both files if you need them somewhere other than ~/.studio, such as a runner with no writable home directory.

GitHub Actions

jobs:
  digest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g studio
      - run: studio workflows run 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 --output json
        env:
          STUDIO_ENDPOINT: https://agent-studio.seeyu.ai
          STUDIO_API_KEY: ${{ secrets.STUDIO_API_KEY }}
          STUDIO_WORKSPACE: ${{ vars.STUDIO_WORKSPACE }}

Several accounts and workspaces

Use separate logins for separate identities or deployments:

studio login --profile dev --endpoint http://localhost:3000
studio login --profile prod --endpoint https://agent-studio.seeyu.ai

studio workflows list --profile dev
studio workflows list --profile prod

Use workspace profiles when one login should target several workspaces:

studio profile add marketing --workspace c3a70e58-9f21-4d6b-b842-05e7f19c6a3d
studio profile add support --workspace e0d94b17-3c62-45af-9718-b6a2c8035f4e

studio workflows list --profile marketing
studio workflows list --profile support

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:

studio login --profile local --endpoint http://localhost:3000

Save it to avoid repeating the flag:

studio configure --set-endpoint http://localhost:3000 --profile local

OAuth sign-in is available by default when server authentication is enabled. DISABLE_AUTH=true disables OAuth. Servers without OAuth use the pairing-code handoff when they support platform API keys. See Sign in with Studio for server configuration and upgrade requirements.

Where the login is stored

Logins live in ~/.studio/credentials, written 0600, separate from the non-secret ~/.studio/config. Commit config to a dotfiles repo if you like; never credentials.

[default]
access_token = studio_oat_…
refresh_token = studio_ort_…
token_expires_at = 1788547200000
oauth_issuer = https://agent-studio.seeyu.ai/api/auth
oauth_login_id = …
oauth_scope = offline_access api:read api:write

[ci-box]
api_key = studio_…

A profile holds one login. A stored API key can be replaced after confirmation or with --yes; a live OAuth login must be revoked with studio logout before signing in again. Several studio commands running at once share one renewal, so a parallel shell loop cannot sign itself out.

Run studio login separately on each machine. Copying ~/.studio/credentials copies one single-use refresh-token family; simultaneous use from both copies is treated as token replay and revokes that login. If a refresh response is lost because the process or connection stops, the CLI does not retry the consumed token: run studio logout, then studio login again. This fail-closed behavior keeps a copied token from surviving an ambiguous refresh.

Organization audit logs

studio audit-logs requires a personal credential — an OAuth login, or the personal API key studio login --method api-key issues. A workspace-scoped key cannot read organization-level audit logs.