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 workspace's Kortix control plane rat

SKILL.md

GitHub

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 workspace-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 — 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, then the paths of its reference files

get prints the body and then lists the skill's reference files. Pull the one you need with file instead of the whole tree with --full:

kortix skills file kortix-system <path>   # ONE reference file, a path that get listed
kortix skills get kortix-system --full    # everything

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. Every command prints its own flags and subcommands: kortix <command> --help. kortix skills get kortix-cli 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> --listed  # deploy an App's folder; --listed only for an App people open
kortix tools ls                                 # the tools this project's sessions get, 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 loop "<what to check, what to do, end date>" --in 3h --every 4h  # after you send or start anything: come back and check (kortix-system <scheduling>)
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 — run kortix <command> --help, read kortix skills get kortix-system, 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.

Durable session model controls

session.setModel() remains a local preference for later sends from that SDK handle. session.getModel() reads the durable pin ({ model: string | null }). session.changeModel(model) saves the pin without sending a prompt. Pi reconfigures without restarting; the running turn finishes before the next turn uses the new model.

Agent pins, permissions and precedence. An agent's configured model is a default, not a lock: an authorized caller may replace it with a durable session pin. Changing that pin requires session-owner or workspace-manager lifecycle permission; a scoped agent token also needs workspace.session.stop. Workspace visibility alone grants no override permission. The requested model must pass account/model availability and provider-key access checks; changing a pin does not bypass those checks.

The durable pin takes precedence over the default agent/project model when pi initializes or reconfigures. For a turn, an explicit prompt model wins; otherwise an explicitly selected agent's configured model wins, then the current session selection applies. A per-prompt override does not rewrite the durable pin. switchModel queues its continuation with the requested model explicitly, so that continuation uses the switch model even if the agent has a model default. The running turn keeps its model; the new selection applies to a later turn.

await session.switchModel({
  model: 'kortix/glm-5.3-flash',
  prompt: 'Continue verification with the new model.',
  idempotency_key: 'verification-model-1',
});

The switch saves the pin and queues the continuation in one database transaction. Reuse the same key and payload after a transport failure. A different payload with the same key is refused. Self-switches are limited to three per hour. A queued continuation waits for the current turn. The response contains prompt_id and deduped; inspect push_failed before reporting live application.

CLI: kortix sessions model get [session-id], set [session-id] <model>, and switch [session-id] <model> --prompt "Continue verification" --idempotency-key verification-model-1. The new verbs default to KORTIX_SESSION_ID. The existing sessions model <session-id> <model> remains supported. Never send a peer message to yourself to continue a model switch.