> ## 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.

# @karta.sh/cli

> The karta CLI on npm - browser sign-in, setup, local parity, git-push deploys, rollback, and logs.

`@karta.sh/cli` is the `karta` command-line tool. It wraps
[`@karta.sh/sdk`](/sdks/typescript/management) 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](/cli/overview); this page covers install, auth, and key scopes.

## Install & authenticate

```bash theme={null}
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](/platform/api-keys)) 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:

```bash theme={null}
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](/build/supported-harnesses) 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:

```bash theme={null}
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](/deploy/releases-and-rollback) for the full deploy
loop, CI wiring, and the underlying API.