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, 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_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:

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:

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

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)

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:

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.