CLI

Install the kortix CLI, sign in, run the everyday loop, script it in CI or from a coding agent, and find any command.

kortix is the Kortix command line. It does from a terminal what the web app does: create and clone projects, run sessions, review change requests, and configure agents, connectors and secrets. Use it on your own machine, in CI, from a coding agent, and inside a session sandbox, where it is already installed and signed in.

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

Install

The install script supports macOS and Linux on x86_64 and arm64. On Windows, run it inside WSL. It does these steps:

1. Downloads the release binary for your system from GitHub Releases.
2. Checks it against the release’s SHA256SUMS. A missing or wrong checksum stops the install.
3. Puts the binary in ~/.kortix/kortix.
4. Links kortix and kortixt (the TUI) into /usr/local/bin. If that directory is not writable, it uses ~/.local/bin when it exists, else sudo.

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

Check the install with kortix version. To update or remove the CLI, see Maintain the CLI.

Sign in

kortix login

The CLI signs in to one Kortix instance at a time. An instance is a host. The order is always host › account › project › session: you sign in to a host, pick an account in it, pick a project in that account, and run sessions in the project.

kortix login does these steps:

1. Opens your browser. You approve the CLI there, and the token comes back on a local callback.
2. Selects your account. With one account it picks it. With several it asks. --account <slug> skips the question.
3. Sets a default project for the host. --no-project skips this step.

To create a token for --token, see API keys and tokens.

Hosts

Every host keeps its own login. You use these two built-in hosts:

kortix hosts ls also lists local-dev and kortix-internal-dev. Kortix uses them to develop Kortix. You do not need them.

The CLI changes a remote http:// URL to https://. A private address keeps http://: localhost, a LAN IP, a name that ends in .local, .lan, .internal or .home.arpa, and a name with no dot, such as a Docker Compose service.

The logins live in ~/.config/kortix/config.json, with file mode 0600. KORTIX_CONFIG_FILE sets another path.

Check who you are

Which project a command uses

A project command runs against the first project it finds in this order:

1. --project <id> on the command.
2. .kortix/link.json in the current directory. The CLI does not look in parent directories.
3. The KORTIX_PROJECT_ID environment variable.
4. The host’s default project.

kortix projects use also switches the active account to the project’s account. kortix projects link writes .kortix/link.json and works only in a directory that has a .kortix/ directory or a kortix.yaml. kortix projects clone and the first kortix ship write the link for you.

The link also records the host. A command in a linked directory goes to that host, whatever host is active.

A session ID works across projects. If the session is not in the resolved project, and you did not pass --host or --project, the CLI searches your other accounts and logged-in hosts. The 8-character short ID from kortix sessions ls works anywhere a session ID goes.

The everyday loop

The loop runs on the project’s git repository. kortix ship pushes your branch, each session works on its own branch, and you merge its change request. The Git page covers the repository, cloning, pushing from any git client, session branches and change requests.

kortix init my-agent && cd my-agent      # new project from the starter
kortix projects clone <project_id> my-agent

kortix ship

kortix sessions new --prompt "Add a skill that drafts the weekly status report"

kortix chat <session_id>              # line chat, or -p "…" for one prompt
kortix connect <session_id>           # the OpenCode TUI in your terminal
kortix tui                            # the whole product as a terminal app
kortix sessions wait-for <session_id> # block until the agent is done

kortix cr ls
kortix cr diff 1
kortix cr merge 1
git pull

Work with sessions from a terminal

The commands below are kortix sessions <subcommand>. chat and connect also exist at the top level: kortix chat, kortix connect. Sessions explains the behavior behind each one.

Start and list

Talk

Watch

Unblock

Files and ports

Lifecycle

Access

Run in CI and scripts

Give the job a token in the environment. The CLI then needs no kortix login:

KORTIX_TOKEN outranks any stored login, and the CLI never writes it to disk. Create a key that can reach only one project:

kortix tokens new ci-nightly --project <project_id> --expires 90d

The key prints once. Store it in your CI secret store. --expires takes an ISO-8601 date or a span such as 30d, 12h, 6w or 1y.

# .github/workflows/nightly-report.yml
name: Nightly report
on:
  schedule:
    - cron: "0 6 * * *"
jobs:
  report:
    runs-on: ubuntu-latest
    env:
      KORTIX_TOKEN: ${{ secrets.KORTIX_TOKEN }}
      KORTIX_PROJECT_ID: ${{ vars.KORTIX_PROJECT_ID }}
    steps:
      - run: curl -fsSL https://kortix.com/install | bash
      - run: |
          id=$(kortix sessions new --prompt "Write the nightly report" --wait --json | jq -r .session_id)
          kortix sessions wait-for "$id" --timeout 1800
          kortix sessions log "$id" --limit 1

Pipe --json output into jq. Update checks are off when CI is set or stdout is not a terminal. To start sessions on a schedule inside Kortix itself, use Triggers & reminders.

Use Kortix from your coding agent

A coding agent such as Claude Code, Codex, Cursor or pi needs only the binary, a login and the platform manual.

kortix doctor

kortix system-skills get kortix-system

kortix init --force

id=$(kortix sessions new --prompt "Fix the failing export test" --wait --json | jq -r .session_id)
kortix sessions wait-for "$id" --timeout 900
case $? in
  0) kortix sessions log "$id" ;;
  3) kortix sessions pending "$id" ;;
esac

An MCP client can use Kortix without the CLI. See Kortix MCP server.

Inside a session sandbox

Every sandbox has the CLI installed and signed in. The platform sets KORTIX_TOKEN, KORTIX_API_URL and KORTIX_PROJECT_ID, so the agent runs commands with no login and no link. The token is a session token: kortix token shows its session, its agent and its grants. It acts only on the session’s own project.

Commands an agent uses:

What an agent may do is set by its kortix_permissions in kortix.yaml. When the API refuses a command, the CLI prints the token kind, the agent and its grant. See Agents & permissions. These commands are refused for an agent session’s token, whatever the grant:

• kortix projects cli-tokens new and rm
• kortix gateway keys (ls, new, rm)
• kortix sandboxes provider <name> and --clear

kortix update is refused in a sandbox. The platform manages the binary: restart the session to get the current CLI.

A .kortix/link.json for another project needs a stored login for that project’s host. Run kortix login in the sandbox first.

Check and validate

The schema fields are on kortix.yaml reference.

Command map

Every group prints its subcommands and flags with kortix <group> --help. The linked page explains the feature.

Sign in, sessions and the CLI

Projects and git

Configure

Administer

Self-host

Conventions

• kortix, kortix help and kortix --help print the same screen: your host, account and project, then every command group.
• --host <name> sends one command to another host. --project <id> sends it to another project.
• --json, on a command that supports it, prints JSON. On any command it turns off the host and update notices, also on stderr.
• A mistyped command exits 2 and, when a command name is within two edits, prints it as a suggestion. It never scaffolds a project directory. Only kortix init does that.

Maintain the CLI

The bare kortix command checks for a new release at most every 6 hours and offers to install it. Other commands show a one-line notice from the cached check. Turn the check off with KORTIX_NO_UPDATE_CHECK=1. Keep the notice but skip the question with KORTIX_NO_UPDATE_PROMPT=1.

kortix uninstall asks before it removes anything:

kortix feedback takes --kind bug|idea|friction (default idea). Inside a session it tags the report with the session and project IDs.