Documentation Index
Fetch the complete documentation index at: https://docs.arkor.ai/llms.txt
Use this file to discover all available pages before exploring further.
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 Auth0 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
Sign in to the managed backend. The default flow is Auth0 Authorization Code + PKCE on a loopback callback, falling back to an anonymous session when the cloud-api reports that Auth0 is not configured.
Synopsis
Options
| Flag | Description |
|---|
--anonymous | Skip the Auth0 flow and request a throwaway anonymous token. This is also what arkor dev falls back to on a fresh machine when the cloud-api reports that Auth0 is not configured for the deployment; on Auth0-configured deployments arkor dev runs the PKCE flow instead. |
--no-browser | Disable the automatic open(url) call. The authorization URL is printed in both modes (Browser: <url> line); this flag only stops the CLI from launching a browser for you. Useful in headless environments (SSH, Docker). |
What happens
- The CLI calls
/v1/auth/cli/config on the cloud-api to read the deployment’s Auth0 settings.
- If Auth0 is not configured (or
--anonymous is passed), it requests an anonymous token from /v1/auth/anonymous and writes it to ~/.arkor/credentials.json with mode: "anon".
- If Auth0 is configured, it 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 Auth0 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. Switching to Auth0 later (arkor login) replaces the credentials file but does not migrate the work; if you want to keep what you trained anonymously, run arkor login before you start the run.
arkor logout
Deletes ~/.arkor/credentials.json. Prompts for confirmation by default.
Synopsis
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
Prints the current identity from /v1/me on the cloud-api, plus the org slugs you can reach.
Synopsis
No flags.
Output
When signed in, the command prints the JSON user object pretty-printed, then a single Orgs: <slug>, <slug>, … 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.- Other 4xx / 5xx are reported as
Failed to fetch /v1/me (<status>). Token may be expired. and exit 0.
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 for the full layout.
Token expiry
For Auth0 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.
In practice that means:
- An expired access token shows up as a
Failed to fetch /v1/me (401). Token may be expired. from arkor whoami, or analogous failures from anything that talks to the cloud-api.
- The fix is to re-run
arkor login, which goes through the full PKCE flow again and overwrites ~/.arkor/credentials.json with fresh tokens.
Anonymous tokens have no client-side expiry tracking; the cloud-api decides when they stop working. If an anonymous session starts failing, 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 |
|---|
State mismatch — aborting to prevent CSRF | arkor login (Auth0) | 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 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 (Auth0) | The Auth0 token endpoint succeeded but the response had no refresh_token. Usually a deployment misconfiguration on the Auth0 side. | Enable the offline_access scope on the Auth0 Application, or report the deployment to your Arkor admin. |
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. |
Failed to fetch /v1/me (<status>). Token may be expired. | arkor whoami | The cloud-api rejected the request with a non-200, non-426 status. Most often expired access tokens. | Run arkor login again. The exit code stays 0 so wrapper scripts can inspect the message. |
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. |
