The karta CLI

The karta CLI is the handoff and operations tool around your agent project: sign in, scaffold a starter if needed, exercise the Karta session surface locally, deploy with git or folder upload, and observe what’s running.

npm install -g @karta.sh/cli
karta --version
karta doctor        # diagnose PATH shadowing, runtime bootstrap, login state

The golden path:

karta login                  # opens your browser to approve
karta create support-bot --harness claude-code  # scaffold a starter agent
cd support-bot
karta setup --enable         # configure delivery + flip on the deploy gate
karta dev                    # optional: local Karta session API
karta deploy                 # push (git) or upload (folder)
karta open

The Quickstart walks it step by step.

Auth

Command	Purpose
`karta login`	Sign in via your browser: the CLI prints a one-time code, you approve it in the dashboard, and the CLI receives a named, revocable credential - visible on your API keys page. Also installs the git credential helper so `git push karta` never prompts.
`karta login --with-token`	Read an API key from piped stdin instead: `echo $KARTA_API_KEY \| karta login --with-token` (CI, air-gapped machines).
`karta auth status`	Show who you are, per profile.
`karta auth token`	Print the active token, for piping.
`karta auth logout`	Remove the stored credential (the key stays revocable on the dashboard).
`karta whoami`	Show the currently authenticated principal.

Credentials live under named profiles in ~/.karta/config.toml; select one with --profile <name>. In CI, set the KARTA_API_KEY environment variable - it overrides the stored config everywhere, no browser needed.

Build & run locally

Command	Purpose
`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). Skip this when you already have an agent from your harness workflow. Configure delivery and the deploy gate afterward with `karta setup`. Local only.
`karta setup [path] [--name <n>] [--enable\|--disable] [--method git\|github\|folder]`	Configure an existing agent (name, deploy gate, delivery method) and write a self-documenting `karta.toml`. Scans for agent projects. Local only - never deploys.
`karta dev [path] [-m <msg>] [--user <id>] [--port <port>] [--verbose]`	Exercise your agent locally behind the Karta session API: a chat REPL with hot reload and approval prompts, plus a printed local URL the chat widget or your own frontend can target. `[path]` (or the current directory) selects the agent; in a multi-agent repo it picks the sole one or asks. `-m` sends one message and exits; `--user` simulates a verified end user; `--port` keeps the local URL stable for a frontend; `--verbose` streams the agent runtime’s output and parity details.
`karta dev --release vN [--env remote [--include-secrets]]`	Reproduce production locally: `--release` runs the exact built tree prod serves, `--env remote` binds your prod env vars instead of `.env`. Add `--include-secrets` with `env:secrets:read` to fetch secret values too.
`karta doctor`	Diagnose the local setup: PATH shadowing, runtime bootstrap, login state.

karta dev needs uv installed; it bootstraps the pinned agent runtime automatically on first run. Set KARTA_RUNTIME to point at a local runtime checkout instead.

Deploy

Deploy is karta deploy: it ships the current agent project, inferring the transport - a git repo pushes to its hosted source repo, a plain folder uploads as a tarball. On first run it provisions the hosted agent and wires the karta git remote; git push karta main is the transparent equivalent for a git repo. A push builds every enabled agent in the repo.

Command	Purpose
`karta deploy [slug] [--mode git\|folder] [--dir <path>]`	Deploy the agent. Transport inferred: a git repo pushes, a plain folder uploads. Self-provisions the hosted agent and wires the `karta` remote on first run.
`karta status`	Every agent in the current repo 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 back to a previous release. Instant; the URL is unaffected; slug is inferred from this folder when omitted.

Environment

Declare what config exists in karta.toml [env], bind it locally with .env, and bind it in production with these verbs - the same files run in both environments.

Command	Purpose
`karta env list`	List the agent’s prod env bindings. Secret values are never shown.
`karta env set NAME=value [--secret]`	Bind a value in prod. `--secret` excludes it from `pull` and masks it everywhere.
`karta env unset NAME`	Remove a prod binding.
`karta env pull [--force] [--include-secrets]`	Hydrate `.env` from prod values (audited). Secrets are excluded unless you pass `--include-secrets` with `env:secrets:read`.
`karta env diff`	Report drift between `.env`, prod bindings, and the `[env]` declarations - the same checks `karta dev` warns on and the push-time build fails on.

Observe

Command	Purpose
`karta open [target]`	Open the hosted chat page, `console`, or handoff targets: `billing`, `security`, `api-keys`, `model-keys`, `webhooks`, `connected-accounts`. Infers the agent from the local `karta.toml`; pass `--agent <slug>` or use `KARTA_PROJECT` in CI.
`karta sessions`	List the deployed agent’s sessions: activity, message counts, models, tokens.
`karta sessions show\|view <id>`	Render a session transcript. Transcript content is gated on your organization’s transcript-access setting (an owner can enable it under Settings).
`karta session <id>`	Direct alias for viewing one deployed session transcript.
`karta ps`	Sessions active right now.
`karta send "<message>" [--session-id <id>]` (alias `run`)	One-shot message to the deployed agent - the prod smoke test. Tool approvals are auto-denied so it never hangs. Pass `--session-id` to continue an existing session (multi-turn from the terminal); add `--json` for a single `{agent, session_id, reply}` payload.
`karta schedules list\|create [--run-now]\|pause\|resume\|run\|delete\|rm`	Manage recurring runs. `--run-now` queues a test run immediately after creation.
`karta agent list`	List your active agents.
`karta agent show [slug]`	Agent header plus recent releases (the agent in this folder if no slug).
`karta agent sessions [slug]\|sessions show\|view <id> [slug]\|session <id> [slug]`	List or view transcripts without leaving the `agent` namespace.
`karta logs [slug] [--tail] [--since <iso>]`	Stream agent logs (SSE) or poll; slug is inferred from this folder when omitted.
`karta keys list\|create\|rename\|revoke`	Manage API keys.
`karta usage`	Usage totals and budget for the current period.

Admin and automation

These commands are for operators, platform teams, and scripts that manage a Karta organization beyond a single local deploy.

Command	Purpose
`karta audit-log [--from <date>] [--to <date>] [--csv]`	Export audit events for review.
`karta analytics agents\|users\|instances\|sessions\|models\|cost`	Inspect usage and cost by the entity you operate.
`karta model-keys list\|create\|revoke`	Manage BYOK provider credentials.
`karta members list\|invite\|set-role\|remove`	Manage organization members.
`karta embed-keys list\|create\|rotate\|enable\|disable\|revoke`	Manage publishable widget keys and allowed origins.
`karta caps budget [set]\|set\|instance\|instance-set\|end-user\|end-user-set\|seat\|seat-set`	Manage monthly budget and spend caps.
`karta appearance get\|set`	Read or update hosted agent appearance.
`karta schedules list\|create\|pause\|resume\|run\|delete\|rm`	Manage recurring agent runs.
`karta directories instances\|end-users\|users\|sessions`	Read agent-scoped directory rows.
`karta webhooks list\|create\|update\|enable\|delete\|rm`	Manage webhook endpoints and subscribed events.
`karta api <method> <path>`	Call the public API with the active CLI credential.

Scripting

Every command that prints a result also takes --json for machine-readable output - karta agent list --json, karta env diff --json, and so on. karta open --json prints the URL instead of opening a browser. karta send --json buffers the reply and returns one {agent, session_id, reply} payload. karta deploy --mode folder --json returns a structured upload result. The remaining stream-shaped commands (dev, logs, completion, and git-mode deploy) do not support the flag and say so.

Staying current

Command	Purpose
`karta update`	Self-update (standalone installs; npm installs update via `npm install -g @karta.sh/cli@latest`).
`karta completion <bash\|zsh>`	Print a shell completion script, e.g. `karta completion zsh > ~/.zfunc/_karta`.

Earlier versions shipped a separate Python karta (pip) with serve, agent, and session verbs. Those are retired - the runtime package installs no karta script at all, and karta doctor flags PATH shadowing from any stale dev install. Local Karta session parity is karta dev; agent management is the commands above.

Get started

Concepts

Agent project

The CLI

Deploy

Platform

Security

Enterprise

Tutorials

The karta CLI

Auth

Build & run locally

Deploy

Environment

Observe

Admin and automation

Scripting

Staying current

​Auth

​Build & run locally

​Deploy

​Environment

​Observe

​Admin and automation

​Scripting

​Staying current

Auth

Build & run locally

Deploy

Environment

Observe

Admin and automation

Scripting

Staying current