CLI

The kortix command line interface (CLI) controls Kortix from a terminal — your laptop or a session sandbox. This page shows the everyday dev loop, then lists every stable command and flag.

Install

curl -fsSL https://kortix.com/install | bash

The installer downloads a prebuilt binary for macOS and Linux. Windows is not supported.

Auth model

Kortix stores authentication per host, not globally. A host is one Kortix API endpoint. Four hosts exist by default: cloud (Kortix Cloud), selfhost (your self-hosted stack), local-dev, and kortix-internal-dev. You can add more.

The config file lives at ~/.config/kortix/config.json, mode 0600. Override its path with KORTIX_CONFIG_FILE.

The CLI follows one hierarchy: host → account → project → session. You sign in to a host, pick an account inside it, pick a project inside that account, and open sessions inside the project. kortix hosts login walks the first three steps in order: it signs you in, picks the account, then sets a default project.

Every token starts with kortix_pat_. A user token, from kortix login, sees every account and project you belong to. A project token is auto-minted for a session sandbox and scoped to one project. See Token scope.

The dev loop

This loop assumes the CLI is installed and you ran kortix login. See Quickstart for setup.

kortix init my-app
cd my-app

kortix projects link <project-id>

kortix ship

kortix sessions new --prompt "Build the login page" --wait

kortix sessions chat

kortix sessions connect

kortix sessions shell

kortix sessions ls

kortix cr ls
kortix cr diff 1
kortix cr merge 1

Reference

Auth commands

kortix hosts login / hosts logout / hosts whoami are the canonical forms. login / logout / whoami are shortcuts that act on the active host.

Hosts

A remote host URL that starts with http:// is normalized to https://. The CLI never sends a token over plain HTTP to a remote host. localhost is exempt.

Accounts

Projects

A command resolves "the project" in this order:

1. The --project flag.
2. The KORTIX_PROJECT_ID environment variable.
3. .kortix/link.json in the exact working directory.
4. The global default set by kortix projects use.

Project scaffold

kortix init [project-name] [options] creates a new, empty project directory. It writes kortix.yaml, .kortix/Dockerfile, and the OpenCode config directory. It does not write .kortix/link.json — kortix ship or kortix projects link create that later.

kortix init does not include a marketplace picker. Adding a marketplace skill is an agent import: start a session and ask the agent to bring one in.

Ship

kortix ship stages, commits, and pushes your current branch to the project's git repo. Run it once to create the project. Run it again any time to sync. Alias: kortix deploy.

Each run:

• Parses and validates kortix.yaml (skip with --no-verify).
• Commits any dirty working tree (skip with --no-commit).
• Prompts for any missing env secret (skip with --no-env).
• Pushes the current branch to the same-named remote branch.
• Connects any declared connector that still needs auth (skip with --no-connect).

An existing GitHub origin links through the Kortix GitHub App. Any other existing origin is registered as-is. No origin creates a managed Kortix git repo.

Sessions

Each session runs in one sandbox on its own branch.

Inside a sandbox, KORTIX_SESSION_ID is your own session's id.

Change requests

A change request (CR) merges one branch into another on any git host. It is the only way for an agent to land session work on the default branch. See Change requests.

<cr> accepts a per-project number (3) or the full id. Inside a sandbox, the CLI reads its token automatically — no login or link needed.

Secrets

Encrypted values stored on the project and injected as plain environment variables into every session sandbox at boot.

Env

Agents

Per-agent model settings on the linked project.

Channels

Manages the project's connection to a chat platform. Tokens are stored encrypted in the project's secrets and resolved server-side — they are never injected into the sandbox.

--platform slack|teams selects the platform; default slack. See Connectors.

Connectors

Connectors an agent calls as tools. add, rm, and policy set edit the local kortix.yaml; run kortix ship to apply, unless you pass --apply to change the cloud project immediately.

add options: --name <label>, --provider <pipedream\|mcp\|openapi\|postman\|graphql\|http>, --app <slug>, --url <url>, --transport <http\|sse>, --endpoint <url>, --base-url <url>, --spec <url\|path>, --auth-type <none\|bearer\|basic\|custom>, --credential shared.

Sandboxes

Manages the project's sandbox images. A template defines an image or Dockerfile plus resources; a build produces the snapshot sessions boot from.

add/update options: --name <label>, --cpu <n>, --memory <n> (GiB), --disk <n> (GiB).

Marketplace

Read-only discovery of marketplace items. Installing an item into a project is an agent import, done from inside a session — there is no install command.

Options: --query <text>, --type <type>, --source <source>, --host <name>, --json.

Skills

Executor

The in-sandbox agent's interface to every connector. Every call is checked, resolved, and audited server-side; the CLI never holds a third-party credential. Auth: KORTIX_EXECUTOR_TOKEN. Output is JSON.

Files

Read-only view of the project's git repo. Operates on the default branch unless --ref names another branch, tag, or commit.

Options on every subcommand: --ref <ref>, --path <p>, --limit <n>, --json.

Triggers

A trigger starts a session from a schedule or a webhook. add, rm, enable, disable edit the local manifest — run kortix ship to apply. pause/resume flip a separate, server-side switch. See Triggers.

add options: --type <cron\|webhook> (default cron), --prompt <text> (required), --agent <name>, --cron <expr>, --timezone <tz> (default UTC), --secret-env <NAME>, --name <label>, --disabled.

Access

Who can use the linked project. Roles: manager, editor, member.

Roles

Account-level custom IAM roles and policy bindings. Built-in roles are read-only references; custom roles are yours to create, edit, and bind.

Grants

Assigns project resources to people. Secrets and connectors live on agents; assigning an agent to a member grants everything that agent declares.

Manifest validation

See Manifest reference.

Self-host

kortix self-host runs one Docker-based stack, identical on a laptop, a VPS, or a cloud VM. See Self-hosting and Self-hosting architecture.

Common flags: --instance <name> (default default), --domain <domain>, --tunnel cloudflare, --version/--tag/--release <v>, --channel stable|latest (default stable), --auto-update on|off (default on; forced off by --local-images), --update-time <HH:MM> / --update-tz <tz> (auto-updater schedule), --local-images (run locally-built images; dev mode), --enterprise-license (unlock SSO/SCIM/RBAC/audit), --admin-email <email>, --no-restrict-account-creation (let any signed-in user create new accounts/orgs; default is admin-only), --restrict-account-creation (re-enable the admin-only default), --json, --yes.

Token scope

Every token starts with kortix_pat_. A user token is scoped to every project on your accounts. A project token is scoped to one project and auto-injected into that project's sandboxes. See the full token-family reference at Session runtime.

Exit codes