@karta.sh/cli

The unified karta CLI (RFC 0013): one tool from setup to open. Wraps the @karta.sh/sdk TypeScript SDK for its API calls; karta dev bootstraps the Python karta-runtime package (the harness-adapter engine, pinned per CLI release) via uv.

Install

npm install -g @karta.sh/cli

That is the only install channel today (brew/curl installers are Phase 2). From a checkout:

cd sdks/typescript && npm install && npm run build
cd ../typescript-cli && npm install && npm run build
node dist/cli.js --help      # or `npm link` to get `karta` on PATH

The golden path

karta login                  # device flow, browser approve
karta create support-bot --harness claude-code  # scaffold a starter agent
cd support-bot
karta setup --enable         # configure delivery + the deploy gate
karta dev                    # chat locally, hot reload
karta deploy                 # git repo -> push, folder -> upload
karta open

Commands

| Command | Description | | --- | --- | | karta login | Device flow: prints a one-time code, you approve it in the browser (signed-in dashboard session), and the CLI receives a named, revocable credential visible on the dashboard keys page. Also installs the git credential helper for git push karta. | | karta login --with-token | Read an API key from piped stdin instead (CI, air-gapped): echo $KARTA_API_KEY \| karta login --with-token. | | karta auth status | Show who you are, per profile (includes the KARTA_API_KEY env credential when set). | | karta auth token | Print the active token, for piping. | | karta auth logout [--profile <name>] | Remove the stored credential (the key stays revocable on the dashboard). | | karta whoami | Show the authenticated principal. | | karta create [path] [--name <n>] [--template <key>] [--harness <type>] [--harness-version <version>] | Scaffold a brand-new starter agent in a supported harness format (claude-code, opencode, deepagents, goose, or codex-cli): native template files plus a default karta.toml (deploy off). Omit --harness for Claude Code. Local only. | | karta setup [path] [--name <n>] [--enable\|--disable] [--method git\|github\|folder] [--login] | Configure an existing agent folder (name, deploy gate, delivery method) and write a self-documenting karta.toml. Destination-agnostic - writes local config only, never deploys. | | karta dev [path] [-m <msg>] [--user <id>] [--port <port>] | Run the agent locally behind the consumer session API: chat REPL, hot reload, approval prompts, and a printed local URL a widget can target. [path] (or cwd) selects the agent; in a multi-agent repo it picks the sole one or asks. Spawns karta-runtime dev-serve via uv (see Runtime below). | | karta dev --release vN [--env remote [--include-secrets]] | Parity axes: run the exact built tree prod serves, and/or bind prod env vars instead of .env (--include-secrets needs env:secrets:read; audited). | | karta deploy [slug] [--mode git\|folder] [--dir <path>] | Deploy. Transport inferred: a git repo pushes to its hosted source repo (the server fans out one build per enabled karta.toml), a plain folder uploads as a tarball. Self-provisions the source repo + wires the karta remote on first run; git push karta stays the transparent equivalent. | | karta status | Every agent in this repo (resolved from the git root, like git status) joined to its deploy status on the active profile - the "what's here" view. Works before the first deploy. | | karta rollback [slug] --to vN | Flip the agent's current release to a previous version (releases:write); slug is inferred from this folder when omitted. | | karta logs [slug] [--tail] [--since <iso>] | Stream agent logs via SSE (--tail) or poll with --since; slug is inferred from this folder when omitted. | | karta open [target] | Open the hosted chat page, console, or handoff targets: billing, security, api-keys, model-keys, webhooks, connected-accounts. Per-agent commands resolve the agent from karta.toml: explicit --agent/[path], the repo's sole agent, then the legacy KARTA_PROJECT alias. | | karta env list\|set NAME=value [--secret]\|unset NAME | Manage the agent's prod env bindings (declare-or-bind; secret values are never shown). | | karta env pull [--force] [--include-secrets] | Hydrate .env from prod values (audited; secrets excluded unless --include-secrets uses env:secrets:read). | | karta env diff | Report drift between .env, prod bindings, and the karta.toml [env] declarations. | | karta sessions [show\|view <id>] | List transcript sessions from the deployed agent host; show/view renders a transcript (requires the org's transcript-access setting). | | karta session <id> | Direct alias for viewing one deployed session transcript. | | karta ps | Sessions active right now: count, age, model, tokens. | | karta files ls <agent> <karta> | List a karta's durable workspace files (path and size) via the owner read channel (requires a workspace:read key + the agent's owners.api grant). | | karta files get <agent> <karta> <path> [-o <file>] | Fetch one workspace file; writes bytes to --out, or streams them to stdout. | | karta send "<message>" (alias run) | Send a one-shot message to the DEPLOYED agent and print its reply (prod smoke test; tool approvals auto-denied). | | karta agent list\|show [slug] | List all agents in your org, or show one + its recent releases (the agent in this folder if no slug). | | karta agent sessions [slug]\|sessions show\|view <id> [slug]\|session <id> [slug] | List transcript sessions for an agent, or view one transcript without leaving the agent namespace. | | karta agent releases [slug]\|activate <version> [slug] | List release history or activate an existing production release. | | karta agent serving\|dashboard-edits\|workspace-inspectable on\|off [slug] | Toggle serving, browser-console edits, and read-only workspace inspection. | | karta agent workspace-access show\|set <path>=<on\|off> [slug] | Show or set the workspace access grant matrix. Paths: owners.git, owners.api, users.widget, users.agent_definition. | | karta agent model [slug] --source inherit\|platform [--model <id>] | Clear the model override or pin the platform connector. | | karta agent model [slug] --connector-id <id> [--model <id>] | Pin a BYOK connector from karta model-keys list; omit --source. | | karta agent delete [slug] | Archive an agent. | | karta schedules list\|create [--run-now]\|pause\|resume\|run\|delete\|rm | Manage recurring runs for an agent. --run-now queues a test run immediately after creation. | | karta keys list\|create <name> [--scope ...]\|rename <id> <name>\|revoke <id> | Manage API keys (plaintext shown exactly once on create). | | karta usage | Current-period totals and budget. | | karta doctor | Diagnose PATH shadowing (a stale pip-installed karta), the uv/runtime bootstrap, and login state. Exits non-zero when unhealthy. | | karta update | Self-update on the standalone channel; npm installs get the npm install -g @karta.sh/cli@latest pointer. | | karta completion <bash\|zsh> | Print a shell completion script generated from the command tree. |

Additional command groups:

| Command | Description | | --- | --- | | karta audit-log | Export audit events as a table, JSON, or CSV. | | karta analytics agents\|users\|instances\|sessions\|models\|cost | Usage and cost rollups with bounded ranges and JSON output. | | karta api [METHOD] /path | Authenticated passthrough for documented public API reads and curated scoped writes. | | karta model-keys list\|create\|revoke | Manage encrypted BYOK provider credentials. | | karta members list\|invite\|set-role\|remove | Manage organization members and invitations. | | karta embed-keys list\|create\|rotate\|enable\|disable\|revoke | Manage publishable widget embed keys for an agent. | | karta caps budget [set]\|set\|instance\|instance-set\|end-user\|end-user-set\|seat\|seat-set | Inspect and update monthly budget, durable karta caps, verified-user caps, and per-seat caps. | | karta appearance get\|set | Read or merge an agent's appearance JSON. | | karta directories instances\|end-users\|users\|sessions | Read agent-scoped durable kartas, verified users, and sessions. | | karta webhooks list\|create\|update\|enable\|delete\|rm | Manage webhook endpoints and one-time signing secrets. |

Every command that prints a result payload also takes --json for machine-readable output (RFC 0013 §3). Stream-shaped commands (dev, logs, deploy (git mode), completion) reject the flag instead of silently ignoring it. karta open --json prints the URL object without opening a browser, and karta send --json buffers the reply into one {agent, session_id, reply} payload.

karta git-credential is a hidden subcommand: the credential-helper protocol endpoint that karta login wires into git config.

Configuration

karta login writes ~/.karta/config.toml with mode 0600:

default_profile = "default"

[profiles.default]
api_key = "kt_live_…"
base_url = "https://karta.sh"
git_base_url = "https://git.karta.sh"

• --profile <name> selects a non-default profile.
• --base-url / --git-base-url (on login) override the production hosts for staging / self-hosted deployments.
• KARTA_API_KEY overrides the stored credential everywhere (the CI path; KARTA_BASE_URL pairs with it).

Runtime (karta dev)

The harness adapters live in the Python karta-runtime package, single-sourced with production. On first karta dev, the CLI resolves the pinned version through uv (uvx --from karta-runtime==<pin>); the pin ships inside each CLI release. KARTA_RUNTIME is the escape hatch - point it at a checkout (runs uv run --project) or an executable. karta doctor diagnoses the bootstrap.

Auth and scopes

Every authenticated command sends Authorization: Bearer kt_live_…. The server validates the bearer by prefix lookup + constant-time bcrypt comparison (see Api::BaseController in the Rails app).

Required scopes:

• karta login - grants routine operation scopes for non-admin CLI workflows: analytics/usage, agent settings, releases, schedules, webhooks, embed keys, appearance, directories, caps, model connector/member listing, env list/set/unset, deploy, status, logs, and open. Member listing still requires the key to have been created by a current owner or admin.
• separately scoped keys - sensitive or tenant-admin commands such as audit-log, members invite|set-role|remove, model-keys create|revoke, keys create|rename|revoke, agent workspace-inspectable, agent workspace-access set, agent delete, and env pull --include-secrets.
• setup is local-only and needs no auth.

Tests

npm test     # vitest + msw, covers each command's happy path

The Rails-side controllers are tested under apps/karta-web/test/controllers/api/ (e.g. publishes_controller_test.rb, rollbacks_controller_test.rb).