> ## Documentation Index > Fetch the complete documentation index at: https://arkor-92aeef0e-eng-353.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # arkor login / logout / whoami > Sign in to Arkor's managed backend, sign out, and inspect the current identity. # `arkor login`, `arkor logout`, `arkor whoami` Three short commands that read or write `~/.arkor/credentials.json`. None of them touches `.arkor/state.json`. For anonymous workspaces, project routing is auto-created by the runtime on the first `trainer.start()` (or first inference call). For OAuth workspaces, `.arkor/state.json` has to exist before the run: today, neither `arkor login` nor `arkor init` creates it, so the practical path is to create it manually with `{ orgSlug, projectSlug, projectId }`. The runtime points you at this fallback when it errors out on a missing state file. ## `arkor login` ```bash theme={null} pnpm exec arkor login ``` Sign in to the managed backend. With no flags the CLI asks interactively whether to sign in via Arkor Cloud's OAuth or as an anonymous session. The interactive selector defaults to **Anonymous**, so accepting the default (or piping into a non-TTY) lands on the anonymous path; OAuth runs only when you explicitly select it or pass `--oauth`. ### Synopsis ``` arkor login [options] ``` ### Options | Flag | Description | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--oauth` | Skip the picker and run the Arkor Cloud OAuth (Authorization Code + PKCE) flow directly. Mutually exclusive with `--anonymous`. Errors out with `--oauth needs a browser callback that CI runners can't complete. Use --anonymous in CI.` when `process.env.CI` is set, because PKCE needs a browser callback and the loopback would hang forever in CI. | | `--anonymous` | Skip the picker and request a throwaway anonymous token. Mutually exclusive with `--oauth`. This is also what `arkor dev` does at launch when no credentials exist on disk: it always bootstraps anonymous first. | | `--no-browser` | Disable the automatic `open(url)` call. The authorization URL is printed either way (`Browser: ` line); this flag only stops the CLI from launching a browser for you. Useful in headless environments (SSH, Docker). It only affects the OAuth path. | ### What happens 1. The CLI calls `/v1/auth/cli/config` on the cloud-api to read the deployment's OAuth settings. 2. If `--anonymous` is passed, the CLI requests an anonymous token from `/v1/auth/anonymous` and writes it to `~/.arkor/credentials.json` with `mode: "anon"`. 3. If `--oauth` is passed, it skips straight to the OAuth flow. 4. If no flag is passed, it shows an interactive picker (`OAuth (browser)` / `Anonymous`) with **Anonymous** preselected. Accepting the default, including in non-interactive contexts where the prompt is non-blocking, runs the anonymous path; choosing OAuth runs the OAuth flow. 5. The OAuth flow generates a PKCE pair, starts a loopback HTTP server on one of the cloud-api-provided callback ports, opens (or prints) the authorize URL, and waits for the callback. State is verified before exchanging the code for tokens; a mismatch aborts to prevent CSRF. The resulting OAuth tokens are written to `~/.arkor/credentials.json` with `mode: "auth0"`. The loopback server is closed in a `finally` block so it does not stick around if login fails. ### Anonymous mode in one paragraph Anonymous credentials let you try Arkor without an account: training runs, jobs, and any work you do are tied to the local machine via the anonymous token. The anonymous path always mints a brand-new token (and a new `anonymousId`) and overwrites `~/.arkor/credentials.json`, so re-running `arkor login --anonymous` does not refresh the existing identity. Switching to OAuth (`arkor login --oauth`, or selecting `OAuth (browser)` in the picker) overwrites the credentials file the same way and does not migrate prior anonymous workspaces or jobs into the account. Merging anonymous work into an OAuth account once you sign in is on the roadmap; until that lands, run `arkor login --oauth` **before** you start the runs you want associated with the account. Anonymous accounts are intentionally **single-device**: the cloud-api stores a `latest_jti` per anonymous user and `userAuth` rejects every authenticated request whose JWT carries a different jti. The jti only changes when the token rotates, so the practical timing has two regimes. **Today** the CLI does not auto-refresh anonymous tokens (that wiring lives in `@arkor/cloud-api-client`'s `getToken()` and is on the [SDK roadmap](/roadmap)), so no rotation ever happens client-side and a copy of `~/.arkor/credentials.json` on a second machine usually keeps working — until the issuing user explicitly mints a new identity (`arkor login --anonymous` overwrites the file with a fresh jti) or an admin rotates server-side, at which point every other copy starts failing on its next call. **Once auto-refresh ships**, any refresh rotates `latest_jti` immediately, so the older-jti copy on any other device (or an older backup of the same file on this machine) starts failing on its next call without warning. Either way, the losing client receives an HTTP 401 / 409 with `code: "anonymous_token_single_device"`, which `cli/main.ts` surfaces as actionable guidance; deletion of the underlying anonymous row surfaces as `code: "anonymous_account_not_found"` the same way. The recovery hint is deployment-aware: on OAuth-supporting deployments the CLI points at `arkor login --oauth` so you can sign up for an account that supports multiple devices, while on anon-only deployments (where OAuth is not configured) it points at `arkor login --anonymous` instead — `--oauth` would fail there, and minting a fresh anonymous identity is the only recovery available. Note that **neither path migrates existing anonymous work** into the new identity; the previous workspace stays reachable only from the credentials file that issued it. ### Anonymous issuance output Both anonymous paths surface the new `anonymousId` and an explanation that the same id is how Arkor Cloud recognises this client across sessions, though the line shape differs by entry point. `arkor login` (`--anonymous` flag or picker → **Anonymous**) prints `Anonymous id: ` as the spinner stop and then a separate info line saying that keeping the credentials file (`credentialsPath()`, typically `~/.arkor/credentials.json` on Linux and macOS) is what preserves the identity. `arkor dev`'s auto-bootstrap skips the spinner and emits a single info line that already embeds the id and the same explanation. The picker → **Anonymous** path additionally surfaces a one-line warn alongside the success message — ``Anonymous sessions aren't guaranteed to persist — sign in with `arkor login --oauth` to tie future work to your Arkor Cloud account.`` — so the upgrade hint is visible at issuance time. The explicit `--anonymous` shortcut suppresses that warn because it skips the `/v1/auth/cli/config` fetch and so cannot tell whether `arkor login --oauth` would succeed on this deployment; pointing at it on a rare anon-only deployment would steer users at a command that fails. Every anonymous issuance path also surfaces the single-device limitation as a separate info line. The exact wording is gated on `oauthAvailable` (same contract as the persistence nudge). On OAuth-supporting deployments callers see the upgrade-flavoured ``Note: anonymous accounts work on this machine only. Run `arkor login --oauth` to sign up for multi-device access.``, while on anon-only deployments (and on `arkor login --anonymous` where the cfg fetch is skipped intentionally) callers see only the bare `Note: anonymous accounts work on this machine only.`, so users on those deployments aren't pointed at a command that would fail. `arkor whoami` on an anonymous identity also emits the bare variant on stderr, and only when both stdout and stderr are TTYs. A redirected stream (lost `stdout.isTTY`) or a CI runner that treats stderr-on-success as a warning marker (lost `stderr.isTTY`) sees no extra prose. The note is purely a UX hint; it doesn't gate any behaviour. The stdout shape (the user JSON object printed by `JSON.stringify(user, null, 2)`, optionally followed by a single human-readable `Orgs: , …` line when the user belongs to any orgs) is unchanged from the pre-note behaviour. Don't pipe the full output through a strict JSON parser like `jq`; the `Orgs:` line is a summary tail, not part of the JSON document. ## `arkor logout` ```bash theme={null} pnpm exec arkor logout ``` Deletes `~/.arkor/credentials.json`. Prompts for confirmation by default. ### Synopsis ``` arkor logout [options] ``` ### Options | Flag | Description | | ----------- | ----------------------------- | | `-y, --yes` | Skip the confirmation prompt. | ### Behavior * If the credentials file does not exist, the CLI logs `No credentials on file.` and exits. * If the user declines the prompt, the CLI logs `Aborted.` and exits without deleting. * `arkor logout` does not touch `.arkor/state.json` or the `.arkor/build/` artifact. To start fully fresh, remove `.arkor/` manually as well. ## `arkor whoami` ```bash theme={null} pnpm exec arkor whoami ``` Prints the current identity from `/v1/me` on the cloud-api, plus the org slugs you can reach. ### Synopsis ``` arkor whoami ``` No flags. ### Output When signed in, the command prints the JSON `user` object pretty-printed, then a single `Orgs: , , …` line if the response includes any. When `~/.arkor/credentials.json` is missing, it prints `Not signed in. Run \`arkor login\` or \`arkor login --anonymous\`.\` and exits. ### Exit codes * `0`: signed in, identity printed. * `0`: not signed in; the message is informational only. * `1`: the cloud-api returned `426 Upgrade Required`. The CLI prints the upgrade hint (and the upgrade command for your detected package manager) and sets `process.exitCode = 1` so the deprecation-warning flush in `arkor`'s shutdown hook still runs before the process exits. * `1`: the cloud-api returned a structured anonymous-auth dead-end (`code: "anonymous_token_single_device"` or `code: "anonymous_account_not_found"`). `cli/main.ts` formats the deployment-aware recovery hint to stderr; see [Token expiry](#token-expiry) for the exact wording. * `1`: any other non-2xx (transient 5xx, an unmapped 4xx, etc.). The previous "exit `0` with a `Failed to fetch /v1/me (). Token may be expired.` line on stdout" behaviour was removed in this release: `arkor whoami` now raises a `CloudApiError`, and `bin.ts` renders it concisely as `err.message` (e.g. `cloud-api 503`) on stderr before exiting non-zero. Stack traces are reserved for unknown `Error` shapes (likely SDK bugs); routine HTTP failures stay one-line so they don't drown a wrapper's logs. ## Where the credentials live Both modes write to the same file at `~/.arkor/credentials.json` and are tagged with a `mode` field of either `"auth0"` or `"anon"` so the rest of the CLI (and the Studio server) knows which path to use. See [Project structure](/concepts/project-structure) for the full layout. ## Token expiry For OAuth sessions, the credentials file records both the access token and the issued refresh token, plus the `expiresAt` timestamp returned by the token exchange. The refresh token is stored today, but the CLI does **not** yet auto-refresh expired access tokens; that path is [on the roadmap](/roadmap#auth0-token-auto-refresh). In practice that means: * An expired or revoked token shows up as a non-2xx response from the cloud-api. `arkor whoami` no longer prints a generic "Token may be expired" hint; instead it raises a `CloudApiError` carrying the upstream `code` (when present), and the top-level handler in `cli/main.ts` formats two known auth-state codes as actionable guidance. Before formatting, `main()` does a best-effort fetch of `/v1/auth/cli/config` so the recovery hint matches the deployment shape: * `code: "anonymous_token_single_device"` → * on OAuth-supporting deployments: `Anonymous credentials were rejected as single-device. Anonymous accounts only work on one machine. Sign up for an account that supports multiple devices: arkor login --oauth` (exit `1`). * on anon-only deployments: `Anonymous credentials were rejected as single-device. Anonymous accounts only work on one machine. This deployment does not advertise OAuth, so the only recovery is to mint a new anonymous identity (your previous workspace data cannot be recovered): arkor login --anonymous` (exit `1`). * `code: "anonymous_account_not_found"` → analogous OAuth-vs-anon-only split, ending in `arkor login --oauth` or `arkor login --anonymous`. Errors without a known `code` (and any non-`CloudApiError` exceptions) are rethrown out of `main()`. `bin.ts` wraps the top-level `await main(...)` in a try/catch that distinguishes by error shape: a `CloudApiError` is rendered as just `err.message` (e.g. the upstream `error` body, or `cloud-api ` when the body was empty), keeping routine HTTP failures one-line and easy to diagnose; any other `Error` is logged with `err.stack ?? err.message` so genuine SDK bugs still surface a frame. Either way `process.exitCode = 1` is set rather than calling `process.exit(1)` so the deprecation-warning flush + telemetry shutdown in `main()`'s `finally` block still run before the process exits. (The explicit catch is also there to avoid Node's default unhandled-rejection handler, which would dump the bundled minified frame for top-level rejections, and to keep the stderr flush deterministic across the supported Node range.) * The fix for an OAuth session is to re-run `arkor login --oauth`, which goes through the full PKCE flow again and overwrites `~/.arkor/credentials.json` with fresh tokens. Anonymous tokens have a server-side 90-day TTL, but the CLI does not yet auto-refresh them; that wiring lives in `@arkor/cloud-api-client`'s `getToken()` and is on the SDK roadmap. If an anonymous session starts failing today, run `arkor login --anonymous` to mint a new one (this issues a new `anonymousId`, so it is effectively a different workspace). ## Common errors | Message | Where | What it means | Fix | | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Pick one of --oauth / --anonymous, not both.` | `arkor login` | Both mode flags were passed. | Pass at most one. | | `--oauth needs a browser callback that CI runners can't complete. Use --anonymous in CI.` | `arkor login --oauth` (with `process.env.CI` set) | PKCE depends on a loopback redirect from a browser, which CI cannot satisfy. | Use `--anonymous` in CI. For local headless flows that still have a reachable browser (e.g. `... --no-browser \| tee logs`), unset `CI` for the run. | | `State mismatch — aborting to prevent CSRF` | `arkor login --oauth` | The `state` returned to the loopback callback does not match the one the CLI generated (almost always because the browser hit a stale tab from a previous login attempt). | Re-run `arkor login --oauth` and complete the flow in the freshly opened tab. | | `Auth0 did not return a refresh token. Make sure the Application has 'offline_access' scope enabled.` | `arkor login --oauth` | The OAuth token exchange succeeded but the response had no `refresh_token`, so the CLI cannot keep the session alive past the access token's lifetime. Usually a deployment-side misconfiguration. | Enable the `offline_access` scope on the OAuth (Auth0) application, then re-run `arkor login --oauth`. | | `No credentials on file.` | `arkor logout` | `~/.arkor/credentials.json` does not exist. Nothing to delete. | Run `arkor login` first if you wanted to sign in. | | `Not signed in. Run \`arkor login\` or \`arkor login --anonymous\`.\` | `arkor whoami` | Same condition as above, surfaced from a different command. | Same fix. | | `Anonymous credentials were rejected as single-device. …` (followed by either `arkor login --oauth` or `arkor login --anonymous` depending on deployment) | `arkor whoami` and any other authenticated command | The cloud-api rejected the request with `code: "anonymous_token_single_device"` (HTTP 401 from the userAuth jti check or HTTP 409 from the rotate-jti CAS). Either the credentials file was copied to a second device, or another local process refreshed past this token within the recovery window. | Follow the command in the message: `arkor login --oauth` to sign up for an OAuth account on supporting deployments, or `arkor login --anonymous` to mint a new anonymous identity on anon-only deployments. Either path is a *new* identity; existing anonymous work cannot be migrated. The CLI exits `1`. | | `Your anonymous credentials are no longer valid. …` (followed by either `arkor login --oauth` or `arkor login --anonymous`) | `arkor whoami` and any other authenticated command | The cloud-api rejected the request with `code: "anonymous_account_not_found"` (HTTP 401). The underlying `anonymous_users` row was deleted (admin / cascade / explicit revocation). | Same as above — follow the deployment-aware command in the message. The previous anonymous workspace cannot be recovered. The CLI exits `1`. | | `cloud-api ` (one line, no stack) | `arkor whoami` and any other authenticated command | A non-200 / non-426 cloud-api response without a structured auth-state `code` (transient 5xx, an unmapped 4xx, etc.). `cli/main.ts` rethrows the `CloudApiError`; `bin.ts` catches it at the top of the stack and renders just `err.message` (the upstream `error` body, or `cloud-api ` when the body was empty) before setting `process.exitCode = 1`. Stacks are reserved for unknown `Error` shapes (likely SDK bugs). | Inspect the message verbatim; if it looks like a transport/server failure, retry. For an expired OAuth access token, re-run `arkor login --oauth`. For an expired anonymous token, re-run `arkor login --anonymous` (mints a new `anonymousId`). | | `426 Upgrade Required` (with upgrade hint) | `arkor whoami` (and other cloud-api calls) | The deployment requires a newer SDK version. The CLI prints the upgrade command for your detected package manager and sets `process.exitCode = 1`. | Upgrade the `arkor` package and re-run. |