suya auth

suya auth manages how the CLI authenticates against the Subaya API. For the conceptual overview of both credential modes, see Authentication & API keys.

suya auth login

Sign in interactively with the OAuth browser flow.

suya auth login
suya auth login --no-browser

Flag	Description
--no-browser	Don’t launch a browser. Print a short code to approve from any device (the device flow, below).

By default the CLI opens a browser using a loopback redirect and stores the resulting token locally. That is the fastest path when the browser is on the same machine as the CLI — the redirect target is 127.0.0.1, so it has to be.

If the browser can’t be opened, or the redirect never comes back (the usual sign that your browser is somewhere else — SSH, a container, a remote dev box), the CLI switches to the device flow automatically. You don’t need to restart anything.

For agents and CI, prefer setting SUBAYA_API_KEY instead of logging in — no browser is involved at all.

Logging in without a browser (device flow)

Use this when the machine running suya has no browser of its own: over SSH, inside a container, on a remote build box.

suya auth login --no-browser

The CLI prints a code and two links, then waits:

  Open this link on any device:  https://subaya-dev.com/auth/device?user_code=KHTM-BQWD
  Or go to https://subaya-dev.com/auth/device and enter:  KHTM-BQWD

Waiting for approval... (Ctrl-C to cancel)

Open that page on whatever device has a browser — your laptop, your phone — sign in if you aren’t already, check that the code on screen matches the one in your terminal, and approve. The page names the machine that asked, so you can tell your own login from one you didn’t start. The CLI notices within a few seconds, saves the token, and prints the account it signed in as.

Nothing is ever typed back into the terminal, so this works from a script or an agent as well as from a shell.

Notes:

• The code is good for 10 minutes and can be used once. If it expires, run the command again for a fresh one.
• Approving grants the CLI access as you, in your currently active org. To log in against a different org, switch orgs in the console first, then run suya auth login again.
• If you didn’t start the login, click Deny — no token is issued.

suya auth logout

Log out and revoke the locally stored token.

suya auth logout

suya auth status

Show your local auth status. This does not call the server — it reports what credentials the CLI has on disk.

suya auth status

suya auth whoami

Call the server (/api/auth/cli/whoami) and print the identity your current credential resolves to. It works for both credential kinds: a token from suya auth login, and a SUBAYA_API_KEY. Use it to confirm a key is wired up correctly before handing it to CI.

export SUBAYA_API_KEY="sk_live_..."
suya auth whoami

If the credential is rejected, whoami says why rather than just failing:

Reason	What it means
unknown_key	The API key isn’t recognised — revoked, expired, or never existed. Mint a new one in the console under Settings → API keys.
wrong_environment	The key is well-formed but belongs to the other environment (see below). The message includes where to mint the right one.
unknown_token	Your login token expired or was revoked. Run suya auth login again.
no_credential	No credential was presented at all. Set SUBAYA_API_KEY or run suya auth login.

Keys are per environment

API keys carry their environment in the prefix, and a key is only valid against the host it was minted for:

• sk_live_… — the production API (https://subaya-dev.com), what --host defaults to.
• sk_test_… — reserved for non-production environments.

A sk_test_ key sent to the production host is rejected with wrong_environment, not with a generic “invalid key” — so if you see that, the fix is to mint a key of the right kind, not to hunt for a revoked one. Mint keys in the console under Settings → API keys, on the environment you intend to call.

See also

• Quickstart — sign in and run your first simulation.
• CLI overview — global flags and the full command surface.