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:

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 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 apps/<slug> --slug <slug>     # deploy an App's folder; block until its URL is ready
kortix tools ls                                 # the tools a session gets (kortix.yaml tools:), and removed Kortix tools
kortix tools eject <name>                       # copy a Kortix tool to tools/<name>.ts to change it
kortix cr open --title "…"                       # propose landing your branch on main (the user merges)
kortix capture search "<words>"                # the Capture timeline of the person this session acts for (Capture on for the account)

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

Labels and metadata (classify sessions)

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:

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): every session downloads them, and above 512 MiB compressed a running session stops picking up agent config changes from the base branch. Put them in object storage instead. Never merge your own CR. Full CR lifecycle: kortix skills get kortix-system.