Kortix Cli

---
name: kortix-cli
description: "Drive Kortix itself from the terminal with the `kortix` CLI — preinstalled and pre-authenticated in every session sandbox. Use whenever a task means acting on THIS project's Kortix control plane rather than just editing files: manage secrets, list/spawn/watch/talk-to sessions, open or inspect change requests to land work on main, fire or manage triggers, set a reminder to check back on this task later (`kortix remind \"…\" --in 24h --every 1h`, when the project's `reminders` feature flag is on), call connectors, connect Slack, or read project info. This is a discovery stub — the full, always-current reference is served live via `kortix skills get kortix-system` and its reference files."
---

# kortix-cli

The **`kortix`** CLI is the control plane for Kortix — the same surface a human
drives in the dashboard, fully scriptable from a terminal. It is **already
installed and pre-authenticated** in every session sandbox: the binary is on
`$PATH` (`/usr/local/bin/kortix`), a project-scoped token (`KORTIX_TOKEN`)
and `KORTIX_API_URL` are pre-injected, so `kortix …` just works with no setup.

## Start here

This file is a **discovery stub, not the usage guide.** The full, always-current
Kortix reference — every command, the manifest, change requests, the runtime — is
served **live by the CLI**, so it never goes stale between releases:

```bash
kortix skills                    # list the Kortix system skills served live
kortix skills get kortix-system  # THE reference + the paths of its 18 sub-docs
```

`get` prints the body and then **lists** the skill's reference files. Pull the
one you need instead of the whole tree — `kortix-system` is ~230 KB in full:

```bash
kortix skills file kortix-system references/kortix/kortix-cli.md   # the FULL CLI reference
kortix skills file kortix-system references/kortix/kortix-yaml.md  # the manifest
kortix skills get kortix-system --full                             # everything, ~230 KB
```

Load `kortix skills get kortix-system` before doing anything non-trivial with
Kortix — the CLI serves version-matched content, which this static stub can't.
The complete `kortix` command reference is
`references/kortix/kortix-cli.md` inside `kortix-system` — **not** `kortix skills
get kortix-cli`, which just returns this same stub.

## The moves you'll reach for

```bash
kortix whoami                                   # which project + account this token has
kortix secrets set <NAME>=-                     # store a value you already have (stdin); --scope connector
kortix secrets request <NAME>                   # mint a link for a human to enter a value you lack
kortix sessions status                          # every agent on the project + what it's doing now
kortix sessions new --json --wait --prompt "…"  # spawn a subagent, get a ready session id
kortix connectors call <connector> <action> '…' # run a configured connector action (server-side)
kortix apps deploy . --slug <slug>               # deploy and block until the stable URL is ready
kortix cr open --title "…"                       # propose landing your branch on main (the user merges)
```

## Coordinating sessions (spawn → wait → collect)

```bash
kortix sessions new --json --wait --with-file data.csv --prompt "…"   # files land in /workspace/incoming/ BEFORE the prompt
kortix sessions wait-for <id> --timeout 300     # block until the agent finishes (0=done, 3=blocked on an ask, 124=timeout) — never sleep-poll
kortix sessions pending <id>                    # see what a blocked agent is asking; answer with approve/answer
kortix sessions cp <id>:out/result.pdf .        # pull deliverables; also local→session and session→session, -r for dirs
```

## Labels and metadata (classify sessions)

```bash
kortix sessions new --json --wait --label worker --label "ticket:T-142" --meta ticket=T-142 --prompt "…"
kortix sessions update --label needs-review --meta result=pass   # no id = the session you run in ($KORTIX_SESSION_ID)
kortix sessions update <id> --unlabel needs-review --unmeta result
kortix sessions ls --label worker --json          # only sessions carrying EVERY given label
```

- Labels are free-form (1–64 characters, at most 20 per session) and filter
  the web sidebar, `sessions ls` and the API list. Metadata is a free-form
  object for your own keys; `--meta` sets strings, `--unmeta` removes a key.
- Label the workers you spawn so you (and the user) can find them later.

- A finished session's sandbox **stops automatically** to save compute.
  `stopped` means *parked*, not failed — `sessions cp`, `sessions chat`, and
  `sessions wait-for` wake it on demand.
- Session ids abbreviate: any unambiguous prefix (the 8-char ids `sessions ls`
  prints) works.
- Session sandboxes have Python via **uv** (`uv run` / `uvx` / `uv pip` —
  prefer these over bare `pip`), Node, browsers, and document tooling
  preinstalled — spawn the task, not an environment-setup plan.

Every read command takes `--json` (clean payload on stdout), so the CLI is a
100% scriptable surface. For anything beyond the above — flags, the token-scope
model, host switching, orchestration patterns — read
`kortix skills file kortix-system references/kortix/kortix-cli.md` (the full
command reference), or `kortix skills get <name>` for another system skill.

## Landing work on `main`

A session runs on its own branch; the **only** sanctioned path to `main` is a
change request, and you open it — the user reviews and merges:

```bash
kortix validate                                   # schema + repository size warnings
git add . && git commit -m "…" && git push origin HEAD
kortix cr open --title "…" --description "…"     # head + session auto-detected in a sandbox
```

Never commit big static assets (video, datasets, build output): a session's
agent config build fails when the repository is over 32 MiB compressed. Put
them in object storage instead. Never merge your own CR. Full CR lifecycle: `kortix skills get kortix-system`.