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. The built-ins cloud (Kortix Cloud), selfhost (your kortix self-host stack), local-dev (a local pnpm dev server), and kortix-internal-dev are always available, and you can add more 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.

Accounts

One Kortix login can belong to many accounts (personal, a company account, …). Exactly one is active at a time; every account-scoped command (projects ls, ship, …) operates on it unless overridden.

Self-host

kortix self-host start creates and starts a production-style local Kortix stack using Docker Compose. On first interactive setup it always collects a Daytona API key (the sandbox runtime — required, or agent sessions can't start) and managed GitHub access (a PAT or GitHub App — required to create projects), plus the optional integrations you may not need yet: Freestyle for app deployments and Pipedream for app connectors. Local ports, Supabase, generated secrets, and Docker defaults are handled automatically. start prints a warning if the sandbox provider or git provider still isn't configured.

Projects

A directory link (.kortix/link.json) always wins over the default; the default (kortix projects use) is what commands use anywhere else on your machine.

How a command finds "the project"

In strict order:

1. --project <id> flag.
2. KORTIX_PROJECT_ID env var (this is also how a session sandbox's own project is picked up — one check, not a separate sandbox step).
3. .kortix/link.json in the exact cwd — no ancestor/parent-directory search.
4. The global default project set by kortix projects use.

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

How a command finds "the host"

1. --host <name> flag.
2. Inside a session sandbox: the platform-injected KORTIX_CLI_TOKEN / KORTIX_EXECUTOR_TOKEN resolves the host directly — this wins over .kortix/link.json's host field.
3. host field in .kortix/link.json (so a repo on your laptop hits its home Kortix instance).
4. 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

Connectors

Integrations agents call as tools (Pipedream apps, MCP servers, OpenAPI/GraphQL/HTTP endpoints) — mirrors the dashboard's Customize → Connectors. Connectors are project-wide visible; the access gate is which agents may call one ([[agents]].connectors in kortix.yaml, see Grants). add / rm / policy set edit the local kortix.yaml (the source of truth) — run kortix ship to apply, then sync to reconcile — unless you pass --apply, which skips ship/CR and applies on the cloud project immediately.

add options: --name <label> (default: slug), --provider <pipedream\|mcp\|openapi\|graphql\|http>, --app <slug> (Pipedream), --url <url> (MCP), --transport <http\|sse> (MCP), --endpoint <url> (GraphQL), --base-url <url> (HTTP), --spec <url\|path> (OpenAPI/GraphQL/HTTP), --auth-type <none\|bearer\|basic\|custom>, --credential shared.

Channels

Manages the per-project Slack connection. Tokens are stored encrypted in the project's secrets manager; at session spawn they land in the sandbox as env vars, so the in-sandbox slack CLI can post back to your workspace.

Sandboxes

Manages the project's sandbox images — the same surface as the dashboard's Customize → Sandbox images. A template is a definition (image OR Dockerfile + resources); a build produces the actual snapshot the platform boots sessions from. Templates can also come from [[sandbox.templates]] in kortix.yaml.

Options for add/update: --image <ref> (mutually exclusive with --dockerfile), --dockerfile <path> (repo-relative), --name <label> (default: slug), --cpu <n>, --memory <n> (GiB), --disk <n> (GiB).

Apps (experimental)

Manages deployable apps — the same surface as the dashboard's Apps page. Apps are declared in [[apps]] in the manifest and deployed to a provider. Hidden from kortix help and refuses to run unless KORTIX_APPS_EXPERIMENTAL=true is set locally, in addition to the platform-side apps feature being enabled for the project.

Options for add/update: --name <label>, --framework <f> (e.g. next, vite, static), --repo <url> (git source), --branch <b>, --root-path <p> (subdir to deploy), --tar <url> (tarball source, alternative to --repo), --build-command <cmd>, --out-dir <dir>, --domains <d,d> (comma-separated), --disable (set enabled=false). Global: --project <id>, --host <name>.

Marketplace

Browse and install items (skills, etc.) from the Kortix marketplace into a linked cloud project.

Common options: --query <text> (same as search [query]), --type <type> (e.g. skill), --source <source> (e.g. kortix), --project <id>, --json.

Executor

The agent's primary interface to every configured connector — a thin client that never holds a third-party credential; every call goes to the Kortix Executor Gateway, which checks sharing, resolves the secret server-side, runs the call, and audits it. Auth comes from KORTIX_EXECUTOR_TOKEN + KORTIX_API_URL, injected at sandbox spawn. Machine-facing: emits JSON only.

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.

Files

Browse the project's git repo — the same read-only view the dashboard shows (Files tab + version history). Operates on the default branch unless --ref selects another branch, tag, or commit sha.

Options: --ref <ref> (branch/tag/commit, default: the project's default branch), --path <p> (scope to a subtree or file), --limit <n>, --json (supported by every subcommand).

Triggers

Round-trip through the manifest's triggers: (v2 kortix.yaml) or [[triggers]] (legacy kortix.toml); the dashboard sees the same state. add / rm / enable / disable edit the local manifest — run kortix ship to apply. pause / resume are a separate server-side activation switch (cloud state, not the manifest) — use them to stop one of two deployments of the same repo from double-firing; manual fire still works while paused.

add options: --type <cron\|webhook> (default cron), --prompt <text> (required — initial prompt for the spawned session), --agent <name> (default: the opencode default), --cron <expr> (6-field cron, e.g. "0 0 9 * * 1-5"), --timezone <tz> (default UTC), --secret-env <NAME> (HMAC secret env var, webhook type), --name <label> (default: slug), --disabled (create it disabled).

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

Agents

Per-agent settings on the linked project. Today: which model each agent runs on — the dynamic gateway default, applied instantly with no kortix.yaml commit. A session that asks for the synthetic auto model resolves to this pick, falling back to the project → account → platform default. (The declarative default lives in kortix.yaml as [[agents]].model.)

Access

Manage who can use the linked project — mirrors the dashboard's project sharing/access panel. Roles: manager, editor, member.

Options: --role <manager\|editor\|member>, --expires <iso> (optional auto-revoke timestamp for a grant).

Roles

Account-level custom IAM roles + policy assignments — the CLI face of the dashboard's Roles tab and a project's "Custom roles" card. Built-in roles (owner/admin/member, manager/editor/user) are read-only references; custom roles are yours to create, edit, and bind. export / import round-trip roles + bindings as TOML or JSON — "IAM as code".

A <role> may be its key (e.g. support_agent) or its role id. Options: --name, --desc, --scope <account\|project>, --actions <list>, --to <type>:<id>, --project <id>, --expires <iso>, --account <id>.

Grants

Assign project resources to people — the inheritance pyramid. Secrets and connectors live on agents; assigning an agent to a member (or group) grants them everything that agent declares. Mirrors the dashboard's "Members → Resource access" panel. assign only ever creates agent grants now; ls still lists any legacy skill/secret rows for visibility.

Options: --to <who> (member email or user-id; group id with --group), --expires <iso>.

Install / update / uninstall

Project scaffold

kortix init creates a new, standalone directory — like create-next-app, it never scaffolds into an existing folder or the current directory, and it refuses to run against a non-empty one. Scaffolding is explicit-only: init is the single command that creates a project. An unrecognized subcommand (kortix use, kortix inti, …) exits with an error and a did-you-mean suggestion — it never creates a directory. (Older CLI versions treated any unknown first argument as a project name to scaffold; that form is gone.)

kortix init options: --name <project> (alias for the positional name), --primary <agent> (opencode|claude|codex|cursor), --agents <list> (comma-separated extras to wire up alongside --primary), --template <minimal\|general-knowledge-worker> (default minimal; general-knowledge-worker includes the optional skill pack), --marketplace <list> (comma-separated marketplace skills, or none; interactive mode opens a preselected picker), --no-git (skip git init), -y/--yes (skip prompts — requires a project name).

Dev

Run OpenCode locally against this project's .kortix/opencode config — the same config the cloud sandbox uses — so you can test agents, skills, tools, and runtime config without spinning up a sandbox. Works from anywhere inside the project; no cd or OPENCODE_CONFIG_DIR needed. Scope: this exercises the OpenCode half of your config only — connectors/executor, triggers, and channels are injected by the platform at session start, so test those against a live session instead.

Ship

Stage everything, commit, and push your current branch to the project's git repo — in one command. Run it once to create the project, then run it again any time to sync. Alias: kortix deploy — despite the name, it's a git push, not app deployment.

Every run: (1) verify kortix.yaml parses + validates (skip with --no-verify); (2) git add -A + commit (skipped if nothing changed); (3) offer to set any [env] secret not yet set (skip with --no-env); (4) push the branch you're on to the same-named branch on the project's repo; (5) connect any declared connector that still needs auth (skip with --no-connect).

The first ship creates the cloud project + a git repo and links the folder (.kortix/link.json); every ship after that just commits + pushes. Origin is inferred, never asked: an existing GitHub origin links directly (GitHub-backed — prints a one-click App-install link if needed, or pass --github-token); another existing remote is registered + pushed; no origin creates a managed Kortix git repo.

Manifest validation

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 STRIPE_API_KEY=sk_live_… WEBHOOK_SLACK_SECRET=whsec_…
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.