---
title: "Command reference"
description: "The arkor CLI: full command reference."
---

The `arkor` CLI is the command surface around an Arkor project. The [scaffolder](/docs/framework/quickstart#1-scaffold-a-project) installs `arkor` as a local devDependency, so the commands below are intended to be run from inside that project, where the `arkor` binary is available via your package manager. Snippets below ship as tab groups, so pick the package manager you use and the rest of the page follows.

## Commands

| Command | What it does |
| --- | --- |
| [`arkor init`](/docs/framework/cli/init) | Scaffold `src/arkor/index.ts` + `arkor.config.ts` in the current directory. |
| [`arkor dev`](/docs/framework/cli/dev) | Launch [Studio](/docs/framework/concepts/studio) on `http://localhost:4000` (configurable). |
| [`arkor build`](/docs/framework/cli/build-and-start) | Bundle `src/arkor/index.ts` to `.arkor/build/index.mjs`. |
| [`arkor start`](/docs/framework/cli/build-and-start) | Run the build artifact (auto-builds when missing). |
| [`arkor login`](/docs/framework/cli/auth) | Sign in. With no flags, prompts interactively (default selection: `Anonymous`). Pass `--oauth` for the loopback Arkor Cloud OAuth (PKCE) flow or `--anonymous` to skip the picker. |
| [`arkor logout`](/docs/framework/cli/auth) | Delete `~/.arkor/credentials.json` after confirmation; anonymous identities cannot be restored after deletion. |
| [`arkor whoami`](/docs/framework/cli/auth) | Print the current identity and reachable orgs. |

## Conventions across commands

- **`--help` / `-h`** is available on every command; `arkor <command> --help` prints the flag list and usage.
- **`arkor --version` / `-V`** prints the installed SDK version (the same `SDK_VERSION` the package exports).
- **Exit codes.** Successful commands exit 0. Most commands exit non-zero on failure (uncaught throws, build errors, etc.). `arkor whoami` is a deliberate exception: it prints the failure to stdout but still exits 0 for ordinary cloud-api errors (`Failed to fetch /v1/me (<status>)`), and only sets `process.exitCode = 1` when the cloud-api responds with 426 (SDK too old). Wrapper scripts that need to detect a `whoami` failure should grep stdout, not rely on the exit code.
- **Telemetry.** Every command runs through a small instrumentation wrapper so usage events can be sent to PostHog. See [Environment variables](#environment-variables) below for the full opt-out / debug knobs.
- **Deprecation notices.** When the cloud-api response carries `Deprecation: true`, the CLI prints a one-line warning at the end of the run with the suggested upgrade command. The `Warning` and `Sunset` headers (when present) format the message; they do not trigger the warning on their own.

## Environment variables

| Variable | Effect |
| --- | --- |
| `DO_NOT_TRACK=1` | Disable telemetry across every command. The persistent telemetry-id file is not created or read. |
| `ARKOR_TELEMETRY_DISABLED=1` | Same as `DO_NOT_TRACK`. Provided as an Arkor-specific alias for setups that already gate other tools on `DO_NOT_TRACK` and want a separate switch. |
| `ARKOR_TELEMETRY_DEBUG=1` | Enable verbose internal logging from the telemetry module (init failures, identity-file read/write errors, capture failures, shutdown errors). Telemetry **is still sent** when this flag is on; this is a diagnostic aid, not a dry-run switch. To stop sending events, use `DO_NOT_TRACK=1` or `ARKOR_TELEMETRY_DISABLED=1`. |
| `CI=1` (or any non-TTY stdout) | Force non-interactive mode. `arkor init` skips its prompts and uses the values you passed via flags (or built-in defaults under `--yes`); git init runs without asking when `--git` or `--yes` is set, and is skipped silently otherwise. See [`arkor init` § CI / non-interactive shells](/docs/framework/cli/init#ci--non-interactive-shells). |
| `CLAUDECODE=1` | Strict mode for AI agents that spawn the CLI without being able to answer interactive prompts. `arkor init` (and `create-arkor`) refuse to run unless every curated flag is present, printing a multi-line stderr block with the suggested re-invocation; pass `-y`/`--yes` to opt back into "accept all defaults". See [`arkor init` § Claude Code (`CLAUDECODE=1`) strict mode](/docs/framework/cli/init#claude-code-claudecode1-strict-mode). |

### On the roadmap

The CLI does read `ARKOR_CLOUD_API_URL` and uses it as the cloud-api endpoint when set (`packages/arkor/src/core/credentials.ts`'s `defaultArkorCloudApiUrl`), but pointing at a non-default endpoint (self-hosted or staging) is **not** yet a stable user-facing knob: the env var is internal-only and may change without notice, and there are no compatibility guarantees on alternate endpoints. First-class support for self-hosted / staging deployments is [on the roadmap](/docs/framework/roadmap#self-hosted-deployments).

## Programmatic invocation

The `arkor` package re-exports `runTrainer` so you can drive a training run from your own TypeScript code instead of going through `arkor start`:

```ts
import { runTrainer } from "arkor";

await runTrainer(); // resolves src/arkor/index.ts and calls trainer.start() + .wait()
```

The CLI command runners themselves (`runBuild`, `runStart`, `runDev`, etc.) are intentionally **not** part of the public surface and may change without notice. If you want to wire training into your own code, prefer `runTrainer` or call `trainer.start()` / `trainer.wait()` directly.

## Project versus user state

Two locations matter, and the CLI reads / writes both:

- **`.arkor/`** (per-project, gitignored): `state.json` (project routing) and `build/index.mjs` (the bundled trainer).
- **`~/.arkor/`** (per-user): `credentials.json` (auth) and `studio-token` (per-launch CSRF token, transient).

See [Project structure](/docs/framework/concepts/project-structure) for the file-by-file rundown.

## See also

- [Project structure](/docs/framework/concepts/project-structure) for the file-by-file layout
- [SDK overview](/docs/framework/sdk/overview) for the programmatic surface around the CLI
- [Roadmap § Self-hosted deployments](/docs/framework/roadmap#self-hosted-deployments) for the `ARKOR_CLOUD_API_URL` direction