@karta.sh/cli

@karta.sh/cli is the karta command-line tool. It wraps @karta.sh/sdk for its API calls and covers the Karta handoff and operations loop: login, setup, local session-API parity, deploy, rollback, and logs. The full command reference lives at CLI overview; this page covers install, auth, and key scopes.

Install & authenticate

npm install -g @karta.sh/cli
karta login          # sign in: approve the one-time code in your browser
karta whoami         # the authenticated principal

karta login mints a named, revocable CLI credential (visible on your API keys page) and writes it to ~/.karta/config.toml (mode 0600). It also installs the git credential helper, so git push karta never prompts. Named profiles are supported; select a non-default one with --profile <name>. For CI or air-gapped machines:

export KARTA_API_KEY=kt_live_...           # overrides the stored config
# or store a piped key:
echo $KARTA_API_KEY | karta login --with-token

Commands

Command	Scope	Purpose
`karta login` / `karta auth status\|token\|logout`	-	Authenticate; inspect or remove the stored credential.
`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). Local only.
`karta setup [path] [--name <n>] [--enable\|--disable] [--method git\|github\|folder]`	-	Configure an existing agent project: write `karta.toml` (name, deploy gate, delivery method). Scans for agent projects. Local only - never deploys.
`karta dev [path] [-m <msg>] [--user <id>]`	-	Exercise the agent locally behind the Karta session API: REPL, hot reload. `[path]` selects the agent in a multi-agent repo.
`karta deploy [slug] [--mode git\|folder] [--dir <path>]`	`write`	Deploy the agent: a git repo pushes, a plain folder uploads. Self-provisions the hosted agent and wires the `karta` remote on first run.
`karta rollback <slug> --to vN`	`releases:write`	Flip to a previous release.
`karta logs <slug> [--tail] [--since <iso>]`	`read`	Stream logs (SSE) or poll.
`karta open [console]`	`read`	Open the hosted chat page, or the dashboard agent page.
`karta agent list\|show [slug]`	`read`	List agents, or show one plus its recent releases.
`karta schedules list\|create [--run-now]\|pause\|resume\|run\|delete`	`schedules:read` / `schedules:write`	Manage recurring runs. `--run-now` queues one test run after creation.
`karta status`	`read`	Local agents joined to their deploy status - the “what’s here” view.
`karta keys list` / `create <name>` / `rename <id> <name>` / `revoke <id>`	`read` or `keys:write` for list; `keys:write` for mutations	Manage API keys (plaintext shown once on create).
`karta usage`	`read`	Current-period totals and budget.
`karta whoami`	`read`	Show the authenticated principal.
`karta doctor`	-	Diagnose PATH shadowing, runtime bootstrap, login state.

Deploy and roll back

karta deploy ships the current agent project - a git repo pushes, a plain folder uploads - and self-provisions the hosted agent on first run:

karta deploy my-app           # first run: provision + wire `karta` remote, then ship
git push karta main           # the transparent equivalent, once the remote is wired

karta agent show my-app           # watch versions appear
karta rollback my-app --to v3     # instant pointer flip back
karta logs my-app --tail          # follow build/runtime logs

See Releases & rollback for the full deploy loop, CI wiring, and the underlying API.

Python SDK

TypeScript

Chat Widget

@karta.sh/cli

Install & authenticate

Commands

Deploy and roll back

​Install & authenticate

​Commands

​Deploy and roll back

Install & authenticate

Commands

Deploy and roll back