# Kortix CLI

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

- Skill: `kortix-ai/kortix-cli` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kortix-ai/kortix-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kortix-ai/kortix-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: kortix-ai (https://skillmd.com/u/kortix-ai)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/kortix-ai/kortix-cli

---


# 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_CLI_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 request <NAME>                   # mint a link for a human to enter a key (never handle raw keys)
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
```

- 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
git add . && git commit -m "…" && git push origin HEAD
kortix cr open --title "…" --description "…"     # head + session auto-detected in a sandbox
```

Never merge your own CR. Full CR lifecycle: `kortix skills get kortix-system`.