CLI reference

The kortix CLI drives everything the dashboard can, from a terminal — laptop, coding agent, or session sandbox. For common workflows, see Using the CLI.

Always available inside a session sandbox, no setup:

• Binary on PATH (/usr/local/bin/kortix).
• KORTIX_CLI_TOKEN pre-injected — the project-scoped token the CLI authenticates with. (KORTIX_TOKEN is also present, but it's the sandbox service key, not a CLI token.)
• KORTIX_API_URL points at the platform you're running against.

Quickstart inside a session

kortix whoami                       # confirms what project + account this token has
kortix projects info                # the project you're running inside
kortix secrets ls                   # encrypted env vars + manifest [env] spec
kortix sessions ls                  # every session on this project (incl. you)
kortix cr ls                        # open change requests
kortix cr open --title "..."        # propose merging your branch into main

The sandbox token is project-scoped: read+write anything on this project (secrets, sessions, triggers, change requests, apps), but it can't list other projects or touch account-level resources. See Token scope.

On your laptop

curl -fsSL https://kortix.com/install | bash
kortix login                        # opens browser, you click Authorize

The local CLI uses a user-scoped token at ~/.config/kortix/config.json (mode 0600), which sees every project on every account you're a member of.

Command surface

Auth

Hosts

A host is one Kortix API endpoint. cloud and local are always available, and you can add more self-hosted endpoints. One host is active at a time; the CLI prints the active host before operational commands so Cloud/local actions are harder to mix up.

--host <name> overrides the active host for one invocation: kortix projects ls --host local.

Self-host

kortix self-host start creates and starts a production-style local Kortix stack using Docker Compose. On first interactive setup it only asks for the product integrations you may need: Freestyle for managed git/deployments, a GitHub App or PAT for repo access, and Pipedream for app connectors. Local ports, Supabase, generated secrets, and Docker defaults are handled automatically.

Projects

How a command finds "the project"

In strict order:

1. --project <id> flag.
2. KORTIX_PROJECT_ID env var.
3. .kortix/link.json in cwd (or any ancestor — git-style).
4. Inside a session sandbox: the sandbox's own KORTIX_PROJECT_ID.

If none resolve, the command errors pointing to projects link.

How a command finds "the host"

1. --host <name> flag.
2. host field in .kortix/link.json (so a repo always hits its home Kortix instance).
3. The globally-active host.

Secrets

Encrypted env vars stored on the project, injected as plain env into every session sandbox at boot.

Env — dotenv ↔ secrets

Sessions

Each session is an isolated sandbox VM on its own ephemeral branch.

Inside a sandbox, KORTIX_SESSION_ID is your session; kortix sessions info $KORTIX_SESSION_ID is the live view of yourself.

Triggers

Round-trip through kortix.toml's [[triggers]]; the dashboard sees the same state.

Change requests (cr)

Kortix-native PR layer for session work landing on main — merges one branch (head_ref) into another (base_ref) on any git host, no per-host integration. The only sanctioned way for an agent to land session-branch work on main. See Change requests.

<cr> accepts the short per-project number (3, #3) or the full UUID cr_id. Numbers are unique per project, monotonically increasing.

Inside a sandbox — the typical agent flow

# 1. Commit on the session branch
git add .
git commit -m "Add release-notes skill"

# 2. Push the branch (KORTIX_BRANCH_NAME)
git push origin HEAD

# 3. Open the CR — head and session are auto-detected
kortix cr open \
  --title  "Add release-notes skill" \
  --description "Drafts release notes from merged commits. Tested against the last 5 tags."

# 4. Confirm it's listed
kortix cr ls

# 5. (Optional) show the diff one more time
kortix cr diff 3

The agent does not merge its own CR — that's the user's call, in the dashboard or via kortix cr merge <n>.

Install / update / uninstall

Project scaffold

Other commands: ship (alias deploy) pushes your local commits to the project's cloud repo, provisioning a managed repo on first run — despite the alias, it's a git push, not app deployment. channels connects Slack to a project. Run kortix help for the full list.

Token scope

Two token types, both with the kortix_pat_… prefix, distinguished by an internal project_id column on the token row.

Enforcement: every project route checks the token's project_id against the URL's :projectId. Mismatch → 403. Account routes (/v1/accounts/*) reject any project-scoped token outright.

Inside a sandbox

The session bootstrap injects (among other runtime vars):

KORTIX_CLI_TOKEN=…          # project-scoped PAT — the CLI authenticates with this
KORTIX_TOKEN=…              # sandbox service key (daemon control surface) — NOT a CLI token
KORTIX_API_URL=https://api.kortix.com
KORTIX_PROJECT_ID=<uuid>
KORTIX_SESSION_ID=<uuid>

The CLI reads KORTIX_CLI_TOKEN automatically (falling back to KORTIX_EXECUTOR_TOKEN, the same value) and uses KORTIX_API_URL as the host base. No config file needed. Don't reach for KORTIX_TOKEN — it's the daemon's service key, and the project-scoped API routes the CLI hits reject it.

Rotating

A sandbox's project token is minted at session create and lives for that sandbox. Restarting re-provisions and issues a fresh token; an existing sandbox keeps its token until it restarts.

Common workflows

Spin up a fresh session with custom env

kortix secrets set OPENAI_API_KEY=sk-… ANTHROPIC_API_KEY=sk-…
kortix sessions new --prompt "Audit the auth module and propose a fix"

Inside a session: trigger another session

kortix sessions new --prompt "Verify migration 0048 by running pnpm test + opening a CR if anything fails"

Run a trigger by hand for debugging

kortix triggers ls                      # confirm the slug + status
kortix triggers fire daily-digest       # one-shot manual fire
kortix sessions ls | head -3            # the new session that the trigger spawned

Pull current secrets into a local .env for development

kortix env pull                         # names only, values left blank
$EDITOR .env                            # fill in values locally
# (don't push — local-only file)

Bulk-upload local .env to the cloud project

kortix env push --from .env
kortix secrets ls                       # confirm

Land session work on main (the CR flow)

The agent opens the CR; the user reviews and merges. No other path to main from inside a session.

# inside a session sandbox, on branch session-<id>
git add .
git commit -m "Add release-notes skill"
git push origin HEAD

kortix cr open \
  --title       "Add release-notes skill" \
  --description "Drafts release notes from merged commits. Tested against the last 5 tags."

kortix cr ls                            # confirm

The user then runs kortix cr show 3, kortix cr diff 3, and kortix cr merge 3 (or kortix cr close 3).

Environment variables the CLI reads

The KORTIX_* prefix is reserved for platform-injected values. Don't declare project secrets with it — the secrets-manager API rejects them and the manifest validator warns.

Exit codes

What the CLI is not

• Not a separate runtime. Use kortix self-host start to run your own local Kortix Cloud stack, then switch between Cloud and local APIs with kortix hosts use.
• Not a git replacement. kortix cr composes with git rather than wrapping it.
• Not the runtime. OpenCode executes the agent in the sandbox; the CLI is the control plane. See Kortix vs OpenCode config.