> ## Documentation Index > Fetch the complete documentation index at: https://docs.karta.sh/llms.txt > Use this file to discover all available pages before exploring further. # The karta CLI > Karta CLI commands for setup, local parity, deploy, rollback, logs, and account operations. 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. ```bash theme={null} npm install -g @karta.sh/cli karta --version karta doctor # diagnose PATH shadowing, runtime bootstrap, login state ``` The golden path: ```bash theme={null} 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](/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](/platform/api-keys). 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 `. 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 ] [--template ] [--harness ] [--harness-version ]` | Scaffold a brand-new starter agent in a [supported harness](/build/supported-harnesses) 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 ] [--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 ] [--user ] [--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](/sdks/widget/quickstart) 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](https://docs.astral.sh/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 ]` | 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 ` or use `KARTA_PROJECT` in CI. | | `karta sessions` | List the deployed agent's sessions: activity, message counts, models, tokens. | | `karta sessions show\|view ` | Render a session transcript. Transcript content is gated on your organization's transcript-access setting (an owner can enable it under Settings). | | `karta session ` | Direct alias for viewing one deployed session transcript. | | `karta ps` | Sessions active right now. | | `karta send "" [--session-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 [slug]\|session [slug]` | List or view transcripts without leaving the `agent` namespace. | | `karta logs [slug] [--tail] [--since ]` | 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 ] [--to ] [--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 ` | 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 ` | 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](/cli/agents-and-sessions).