# CLI

The machine command line, its auth model, the dev loop, and every command.

Canonical page: https://themachine.myapps.ai/docs/cli

The Machine command line interface (CLI) controls Machine from a terminal. On your own computer the command is `machine`. This page shows the everyday dev loop, then lists every stable command and flag.

> **machine on your computer, kortix in a sandbox**
> The same CLI ships two ways. You install it on your computer as `machine`. Every session sandbox already has it on `PATH` as `kortix`, signed in for you, and agents call it by that name. The commands and flags are identical. This page writes `machine`; inside a sandbox, type `kortix` instead.
>
> Names the CLI reads and writes keep their original spelling under both commands: `kortix.yaml`, `.kortix/link.json`, `~/.config/kortix/config.json`, and `KORTIX_*` environment variables.

## Install

On macOS or Linux:

```sh
curl -fsSL https://themachine.myapps.ai/install | bash
```

On Windows, in PowerShell:

```powershell
irm https://themachine.myapps.ai/install.ps1 | iex
```

The installer downloads the build for your OS and CPU, checks its SHA-256 checksum against the release manifest, and puts `machine` on your `PATH`. Builds exist for macOS and Linux on x64 and arm64, and for Windows on x64. Windows on Arm runs the x64 build.

| OS | Installs to | Put on `PATH` by |
| --- | --- | --- |
| macOS, Linux | `~/.machine/machine` | A link in `/usr/local/bin` when that folder is writable, otherwise in `~/.local/bin`. The installer adds `~/.local/bin` to your shell profile when it is missing. |
| Windows | `%LOCALAPPDATA%\Machine\bin\machine.exe` | Your user `PATH`. Open a new terminal to pick it up. |

Installer settings:

| Variable | Effect |
| --- | --- |
| `MACHINE_HOME` | macOS and Linux only. Install directory. Default: `~/.machine`. |
| `MACHINE_NO_MODIFY_PATH` | Set it to leave `PATH`, `/usr/local/bin`, and your shell profile alone. Run the binary by its full path. |
| `MACHINE_INSTALL_BASE` | Download from another Machine deployment. Default: `https://themachine.myapps.ai`. |

To set one, put it in front of `bash`: `curl -fsSL https://themachine.myapps.ai/install | MACHINE_NO_MODIFY_PATH=1 bash`.

| Command | Effect |
| --- | --- |
| `machine update` | Re-run the install script for your OS and replace the binary with the latest release. |
| `machine uninstall [-y\|--yes] [--keep-auth] [--keep-home]` | Remove `~/.machine`, the `machine` link in `/usr/local/bin` or `~/.local/bin`, `~/.kortix`, and the stored sign-in. `--keep-auth` keeps the sign-in. `--keep-home` keeps `~/.kortix`. |
| `machine version` | Print the CLI version. |

`machine uninstall` only looks for the default `~/.machine` folder. If you installed with a custom `MACHINE_HOME`, delete that folder yourself.

On Windows, `machine uninstall` removes the stored sign-in but not the program itself. Delete the `%LOCALAPPDATA%\Machine\bin` folder and remove it from your user `PATH` to finish.

## Auth model

The CLI stores authentication per host, not globally. A host is one Machine API endpoint. Four hosts exist by default: `cloud` (Machine, at `https://machineapi.myapps.ai`), `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. `machine hosts login` walks the first three steps in order: it signs you in, picks the account, then sets a default project.

`machine login` opens the Machine website in your browser. One click authorizes the CLI, and the website hands the CLI a personal access token. You can also sign in with an API key you created yourself: `machine login --token mach_pat_...`. The CLI accepts keys that start with `mach_pat_` or `kortix_pat_`. A user token 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](#token-scope).

## The dev loop

This loop assumes the CLI is installed and you ran `machine login`. See [Quickstart](/docs/quickstart) for setup.

### Link a repo

Start a new project, or link an existing repo folder to one.

To scaffold a new project:

```sh
machine init my-app
cd my-app
```

`machine init` creates a project directory with the general-purpose starter. Its
`kortix.yaml` declares `kortix_version: 2` and runs OpenCode.

To link an existing cloned repo to a project you already created:

```sh
machine projects link <project-id>
```

This command writes `.kortix/link.json` in the current directory. The CLI reads this file to find your project on every command run from this folder. If you plan to run `machine ship` first, skip this step. It links a new project for you when none exists.

### Ship your code

```sh
machine ship
```

`machine ship` lints your `kortix.yaml`, commits local changes, pushes your branch, and prompts for any missing secret or connection. Run it each time you want your local changes on the cloud project. The first run also creates the cloud project and repo if you have not linked one yet.

### Run and attach to sessions

Start a session with a prompt:

```sh
machine sessions new --prompt "Build the login page" --wait
```

Each session runs in its own sandbox, on its own branch. `--wait` blocks until the session is ready.

Attach to a session from your terminal:

```sh
machine connect
```

With no session id, `machine connect` (alias: `attach`) opens a session picker
for the bound project — running sessions attach immediately, stopped ones boot
first, and `+ New session` starts a fresh sandbox — then lands you in the full
OpenCode TUI attached to that session. Pass an id to skip the picker:
`machine connect <session-id>`.

The CLI manages the `opencode` binary for you: on first connect it downloads
the exact version the session's server runs and caches it under
`~/.kortix/opencode/<version>/`, so the TUI and server never skew. Set
`KORTIX_OPENCODE_BIN` to force your own binary.

For a lighter-weight line-based chat instead of the full TUI, run:

```sh
machine sessions chat
```

This opens an interactive chat with your most recent session. Add an id to target a specific session: `machine sessions chat <id>`.

To open a raw shell in the sandbox, with no agent involved, run:

```sh
machine sessions shell
```

List your running sessions at any time:

```sh
machine sessions ls
```

### Review with change requests

An agent opens a change request (CR) when its session has commits ready to merge. List, inspect, and merge them from the CLI.

```sh
machine cr ls
machine cr diff 1
machine cr merge 1
```

`machine cr ls` lists change requests for the linked project. `machine cr diff <cr>` shows the unified patch. `machine cr merge <cr>` merges it into the project's default branch. Accept a CR number or its full id.

## Reference

### Auth commands

| Command | Effect |
| --- | --- |
| `machine login [--host <name>] [--api <url>] [--token <pat>] [--account <slug>] [--no-project]` | Sign in to the active host, or the named one. Opens a browser by default; `--token` signs in headless with a `mach_pat_` or `kortix_pat_` key. `--no-project` skips the default-project pick. |
| `machine logout [--host <name>]` | Remove the token for the active host, or the named one. |
| `machine whoami [--host <name>] [--json] [--token-only]` | Print the signed-in user and active account. |
| `machine token [--host <name>]` | Shortcut for `machine whoami --token-only`. |

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

### Hosts

| Command | Effect |
| --- | --- |
| `machine hosts ls [--json]` | List every host and its auth status. |
| `machine hosts login [<name>] [--token <pat>] [--api <url>] [--account <slug>] [--no-project]` | Sign in to a host. An unknown name registers the host first. |
| `machine hosts logout [<name>]` | Remove the token for a host. |
| `machine hosts use <name>` | Switch the active host. |
| `machine hosts add <name> --url <url> [--dashboard-url <url>] [--login]` | Register a new host. `--login` signs in right after. |
| `machine hosts rm <name> [--force]` | Remove a host. |
| `machine hosts info [<name>] [--json]` | Show details for one host. |
| `machine hosts current [--json]` | Print the active host name. |

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

| Command | Effect |
| --- | --- |
| `machine accounts ls [--json]` | List the accounts you belong to on the active host. |
| `machine accounts use [<slug-or-id>]` | Switch the active account. |
| `machine accounts current [--json]` | Print the active account. |
| `machine accounts info [<slug-or-id>] [--json]` | Show one account. |

### 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 `machine projects use`.

| Command | Effect |
| --- | --- |
| `machine projects ls [--all] [--json]` | List projects on the active account. `--all` spans every account you belong to. |
| `machine projects info [<id>] [--json]` | Show one project. Default: the linked or default project. |
| `machine projects use [<id>]` | Set the global default project. Switches the active account if the project lives elsewhere. |
| `machine projects unset` | Clear the global default project. |
| `machine projects link [<id>]` | Bind the current directory to a project. Writes `.kortix/link.json`. |
| `machine projects unlink` | Remove `.kortix/link.json`. |
| `machine projects open [<id>]` | Open a project's dashboard page in your browser. |
| `machine projects clone [<id>] [dir]` | Clone a project's repo through the authenticated Machine git proxy. |
| `machine projects rm [<id>] [--purge] [-y\|--yes]` | Archive a project. `--purge` also deletes its managed git repo. |

### Project scaffold

`machine init [project-name] [options]` creates a new project directory. The
starter writes a v2 `kortix.yaml` and the canonical `.kortix/opencode`
system-skill source. The command can wire local coding-tool discovery without
changing the cloud OpenCode runtime. The command does not write
`.kortix/link.json`. `machine ship` or `machine projects link` create that file.

| Flag | Meaning |
| --- | --- |
| `--name <project>` | Project name. |
| `--primary <agent>` | Primary agent. |
| `--agents <csv>` | Local coding-agent integrations to wire up. |
| `--force` | Configure the current directory in place instead of scaffolding a new one. |
| `--overwrite` | Overwrite existing files. |
| `--no-git` | Skip git init. |
| `-y, --yes` | Don't prompt. |

The local coding-tool selection does not change the cloud OpenCode runtime.

`machine init` does not include a marketplace picker. Adding a marketplace skill is an agent import: run `machine marketplace install <id-or-name>`, or start a session and ask the agent to bring one in.

### Ship

`machine 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: `machine 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 Machine GitHub App. Any other existing `origin` is registered as-is. No `origin` creates a managed Machine git repo.

| Option | Effect |
| --- | --- |
| `--name <project>` | Display name for a new project. |
| `--account <id\|slug>` | Account to create the project under (first ship only). |
| `--origin <managed\|git-url>` | Override the inferred origin choice. |
| `--github-token <pat>` | Link a GitHub origin with this token instead of the GitHub App. |
| `-m, --message <text>` | Commit message. |
| `--no-commit` / `--no-verify` / `--no-env` / `--no-connect` | Skip that step. |
| `-y, --yes` | Don't prompt. |
| `-n, --dry-run` | Print what would happen; change nothing. |
| `--project <id>` / `--host <name>` | Target a non-default project or host. |

### Sessions

Each session runs in one sandbox on its own branch.

| Command | Effect |
| --- | --- |
| `machine sessions ls` | List every session on the project. |
| `machine sessions status [--all] [--json]` | Every session and what its agent is doing right now. Aliases: `overview`, `ps`. |
| `machine sessions info <id> [--json]` | Detail view: status, branch, agent, sandbox URL. |
| `machine sessions new [--prompt "<text>"] [--agent <name>] [--model <id>] [--wait] [--connect] [--json]` | Start a session. `--connect` attaches the OpenCode TUI once it is ready (implies `--wait`); on an interactive terminal without it, the CLI asks whether to connect after creation. `--model <id>` overrides the project's default model. `--wait` blocks until it is running (up to ~5 minutes). Use `--secret <id>` or `--no-secrets` to narrow Secret access. These Secret flags require a backend token. Use `--connector <alias>=<authorization-id>` or `--no-connectors` to set Connector access. Use `--require-connector <alias>` to require an authorization before provisioning. Scope flags are repeatable. Use `--context <key>=<value>` for non-secret runtime context. |
| `machine sessions chat [<id>] [--prompt "<text>"] [--new] [--agent <name>] [--json]` | Talk to a session's agent. Interactive by default. Alias: `talk`. Top-level `machine chat` also works. |
| `machine sessions connect [<id>] [-- <opencode args>]` | Attach the OpenCode TUI to the session's OpenCode server. Also available top-level: `machine connect` / `machine attach`. With no id, opens a session picker (running, stopped-with-restart, or new). The CLI auto-downloads the version-matched `opencode` binary (cache: `~/.kortix/opencode/<version>/`; override: `KORTIX_OPENCODE_BIN`). |
| `machine sessions shell [<id>] [--new]` | Open a raw interactive terminal in the sandbox, with no agent. Aliases: `terminal`, `ssh`. |
| `machine sessions log [<id>] [--limit <n>] [--json]` | Print recent messages, read-only. Aliases: `messages`, `history`. |
| `machine sessions pending <id> [--json]` | List open tool-permission or question prompts. Alias: `prompts`. |
| `machine sessions approve <id> [<req-id>] [--always] [--reject] [--message "<text>"]` | Answer a permission prompt. |
| `machine sessions answer <id> [<req-id>] [--option <v>]... [--text "<text>"] [--reject]` | Answer a question prompt. |
| `machine sessions digest [--since <7d>] [--json]` | Compact multi-session review. Aliases: `review`, `summary`. |
| `machine sessions scope <id> [scope options] [--json]` | Read or replace Secret and Connector access. Alias: `access`. Use `--secret <id>`, `--no-secrets`, or `--inherit-secrets` for Secrets. Use `--connector <alias>=<authorization-id>` or `--no-connectors` for Connector bindings. Use `--require-connector <alias>` or `--no-required-connectors` for required Connectors. Provided categories replace their current values. Omitted categories remain unchanged. Changes apply to the next prompt. Removed Secret values remain in existing context if the session already read them. |
| `machine sessions preview <id> [port] [--port <n>] [--json]` | Print a clickable preview URL for a sandbox port. Default port: `3000`. |
| `machine sessions restart <id>` | Restart the session's sandbox. |
| `machine sessions rename <id> <name>` | Set a session's name. Pass `""` to clear it. |
| `machine sessions rm <id>` | Stop and delete a session. |
| `machine sessions open <id>` | Open a session's dashboard page in your browser. |

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](/docs/work/change-requests).

| Command | Effect |
| --- | --- |
| `machine cr ls [--status open\|merged\|closed\|all] [--project <id>]` | List CRs. Default: `--status open`. |
| `machine cr show <cr> [--project <id>]` | Show one CR, including its merge preview. Alias: `info`. |
| `machine cr diff <cr> [--no-color] [--json]` | Print a CR's unified diff. |
| `machine cr open --title "<text>" [--description "<text>"] [--head <ref>] [--session <id>] [--base <ref>]` | Open a CR. Aliases: `new`, `create`. Inside a sandbox, `--head` and `--session` default automatically. `--base` defaults to the project's default branch. |
| `machine cr merge <cr> [--message "<text>"]` | Merge an open CR. Fast-forward when possible, three-way merge otherwise. |
| `machine cr close <cr>` | Close an open CR without merging. |
| `machine cr reopen <cr>` | Reopen a closed CR. Merged CRs are terminal. |

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

### Secrets

Encrypted values stored on the project. Only a secret with **Sandbox** delivery (the default) is injected as a plain environment variable into session sandboxes. **Machine service** and **Network boundary** secrets never enter the sandbox. Change the mode with `machine secrets delivery`. See [Secrets](/docs/project/secrets).

| Command | Effect |
| --- | --- |
| `machine secrets ls` | List secrets by identifier and manifest `env` spec. Marks required-but-missing values. |
| `machine secrets set NAME=VALUE ... [--identifier <id>]` | Upsert one or more secrets. `NAME=-` reads the value from stdin. |
| `machine secrets request NAME ... [--scope runtime\|connector] [--expires <min>]` | Mint a link for a human to enter a value directly — you never see the raw value. |
| `machine secrets unset NAME ...` | Remove secrets. |
| `machine secrets delivery IDENTIFIER runtime\|broker\|egress\|denied [policy options]` | Set the delivery mode: `runtime` is Sandbox, `broker` is Machine service, `egress` is Network boundary, `denied` is Disabled. |
| `machine secrets call IDENTIFIER URL` | Send one policy-bound HTTPS request through the broker. |
| `machine secrets sync` | Re-push project secrets to running sandboxes. |

### Env

| Command | Effect |
| --- | --- |
| `machine env pull [--out <path>] [--force]` | Write a `.env` skeleton — names only. Values never leave the cloud. |
| `machine env push --from <path>` | Upload every `NAME=VALUE` from a dotenv file as a secret. |

### Agents

Per-agent model settings on the linked project.

| Command | Effect |
| --- | --- |
| `machine agents models [--json]` | Show every agent's pinned model and the fallback default. |
| `machine agents model <agent> <model-id>` | Pin an agent to a plain model id, for example `machine agents model kortix glm-5.2`. Applies to new sessions. |
| `machine agents model <agent> --clear` | Clear the pin — the agent follows the default again. |

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

| Command | Effect |
| --- | --- |
| `machine channels status [--json]` | Show the current connection. |
| `machine channels connect [--wait] [--timeout <sec>]` | Connect in one step: prints an install link. `--wait` polls until the install lands. |
| `machine channels connect --manual [--bot-token <token>] [--signing-secret <secret>]` | Bring-your-own-app mode: save a bot token and signing secret directly. |
| `machine channels disconnect` | Remove the project's channel secrets. |
| `machine channels manifest` | Print the app manifest JSON for the bring-your-own-app path. |

`--platform slack|teams` selects the platform; default `slack`. See [Connectors](/docs/connect/connectors).

### Connectors

Connectors an agent calls as tools. `add`, `rm`, and `policy set` edit the local `kortix.yaml`; run `machine ship` to apply. `add` and `rm` also take `--apply`, which skips the local file and changes the cloud project immediately (Machine commits the edit to `kortix.yaml` on the default branch and syncs).

| Command | Effect |
| --- | --- |
| `machine connectors ls [--json]` | List connectors and their status. |
| `machine connectors show <slug> [--json]` | Show one connector's tools. |
| `machine connectors add <slug> --provider <p> [options] [--apply]` | Add a connector. |
| `machine connectors rm <slug> [--apply]` | Remove a connector. |
| `machine connectors rename <slug> <name>` | Set a connector's display name. |
| `machine connectors sync` | Reconcile the catalog from the shipped `kortix.yaml`. |
| `machine connectors credential <slug> [value]` | Set a connector's credential. |
| `machine connectors secret <slug> <identifier> [--clear]` | Use a project secret as the connector's server-side credential. `--clear` removes the binding. |
| `machine connectors connect <slug> [--expires <min>]` | Mint a shareable one-click connect link for a human. The connection finalizes on its own once they finish. |
| `machine connectors apps [<query>] [--json]` | Browse the connector app catalog. |
| `machine connectors policy ls [--json]` | Show project-wide execution policy. |
| `machine connectors policy set --default <risk\|allow_all>` | Set the default execution mode. |
| `machine connectors policy <slug> ls\|set <match> <allow\|ask\|block>\|rm <match>\|clear` | Manage one connector's tool-call rules. |

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

| Command | Effect |
| --- | --- |
| `machine sandboxes ls [--json]` | List templates and live provider state. |
| `machine sandboxes builds [--json]` | Recent build log. |
| `machine sandboxes health [--json]` | Primary template readiness. |
| `machine sandboxes add <slug> (--image <i>\|--dockerfile <p>) [options]` | Create a custom template and start a build. |
| `machine sandboxes update <slug> [options]` | Update a template. |
| `machine sandboxes build <slug>` | Trigger a rebuild. |
| `machine sandboxes rebuild <slug>` | Force-rebuild: delete the existing snapshot first. |
| `machine sandboxes rm <slug>` | Delete a template. |
| `machine sandboxes fix` | Start a session seeded with the last failed build log, to repair it. |

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

### Marketplace

Browse marketplace items and install one. Installing is an agent import: `install` starts a session on the project, and its agent clones the item, merges what fits, and opens a change request for you to review.

| Command | Effect |
| --- | --- |
| `machine marketplace search [query]` | Search marketplace items. |
| `machine marketplace list` | List marketplace items. |
| `machine marketplace show <id-or-name>` | Show one marketplace item. |
| `machine marketplace install <id-or-name> [--project <id>]` | Start a session that imports the item into the linked project, or the one `--project` names. |

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

### System skills

The Machine system skills are the platform's own documentation. They cover
sessions, sandboxes, OpenCode, the connector, memory, and
channels. The API serves them live, so they match the deployed host version.
The binary and a token are enough for an agent to retrieve this context.

| Command | Effect |
| --- | --- |
| `machine system-skills list` | List the Machine system skills. Default subcommand. |
| `machine system-skills get <name> [--full]` | Print one skill's current `SKILL.md`. `--full` adds its referenced files. |
| `machine system-skills path [name]` | Print a skill's on-disk directory in this project. |

Options: `--host <name>`, `--json`.

`machine skills` is a permanent alias for the same command.

This list is always the system skills, never a mix. Optional skills live in the marketplace: `machine marketplace list --type skill`.

### Connector

The in-sandbox agent's interface to every connector. Agents run these as `kortix connectors …` inside the sandbox. Every call is checked, resolved, and audited server-side; the CLI never holds a third-party credential. Auth: `KORTIX_CLI_TOKEN`. Output is JSON.

| Command | Effect |
| --- | --- |
| `kortix connectors discover "<intent>"` | Search tools by natural-language intent. |
| `kortix connectors show <connector>.<action>` | Show an action's input schema. |
| `kortix connectors call <connector>.<action> '<json-args>'` | Run a tool. A governed call returns its authenticated `approval_url` immediately. The server resumes the session after one approve or deny decision. |
| `kortix connectors add <slug> --provider pipedream --app <app> --apply` | Add a connector to the project immediately, then connect it. Without `--apply`, it only edits the sandbox's copy of `kortix.yaml`, which takes effect once that change is merged. |
| `kortix connectors rm <slug> --apply` | Remove a connector from the project immediately. Without `--apply`, it only edits the sandbox's copy of `kortix.yaml`. |
| `kortix connectors connect <slug> [--expires <min>]` | Mint a connect link for a human. |
| `kortix connectors mcp` | Run the optional stdio MCP compatibility server. |

### Files

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

| Command | Effect |
| --- | --- |
| `machine files ls [<path>]` | List files under a path. |
| `machine files cat <path>` | Print a file's contents. |
| `machine files search <query> [--content]` | Search filenames, or file contents with `--content`. |
| `machine files history <path>` | Commit history for one file. |
| `machine files branches` | List branches. |
| `machine files commits [--path <p>]` | List commits on `--ref`. |
| `machine files show <sha>` | Show one commit and its changed files. |
| `machine files diff <sha> [--path <p>]` | Print a commit's unified patch. |

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

### Triggers

A trigger starts a session from a schedule, a webhook, or a monitor (experimental). `add`, `rm`, `enable`, `disable` edit the local manifest — run `machine ship` to apply. `pause`/`resume` flip a separate, server-side switch. See [Triggers](/docs/connect/triggers).

| Command | Effect |
| --- | --- |
| `machine triggers ls [--json]` | List triggers and their runtime state. |
| `machine triggers add <slug> [options]` | Append a trigger to the manifest. |
| `machine triggers rm <slug>` | Remove a trigger. |
| `machine triggers info <slug> [--json]` | Show one trigger. |
| `machine triggers fire <slug>` | Fire a trigger manually. |
| `machine triggers enable <slug>` / `disable <slug>` | Turn one trigger on or off. |
| `machine triggers pause` / `resume` | Deactivate or reactivate every trigger on the project, server-side. |

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

Monitor options (`--type monitor`, experimental): `--run <cmd>` (required, a repo-relative command the platform keeps running; each line it prints fires the trigger), `--mode <poll\|stream>` (required), `--interval <dur>` (poll mode only, minimum 30s, for example `5m`), `--expect-event-within <dur>` (minimum 5m; if no event arrives in that window, the trigger fires a lifecycle event instead).

### Access

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

| Command | Effect |
| --- | --- |
| `machine access ls [--json]` | List members and their project roles. |
| `machine access invite <email> --role <r>` | Invite someone to the project. |
| `machine access grant <user-id> --role <r>` | Set a member's project role. |
| `machine access revoke <user-id>` | Remove a member's project access. |
| `machine access pending [--json]` | List pending invitations. |
| `machine access cancel <invite-id>` | Cancel a pending invitation. |

### Audit

The audit commands read the centralized reconstruction log. Account and project
lists are newest first. A session timeline is ordered by its monotonic
`session_sequence`. `--all` follows every continuation cursor.

| Command | Effect |
| --- | --- |
| `machine audit ls [filters] [--all] [--json]` | List account events. |
| `machine audit project <project-id> [filters] [--all] [--json]` | List one project's events. |
| `machine audit session <session-id> --project <project-id> [--all] [--json]` | Reconstruct one session in order. |
| `machine audit export [filters] --format csv\|jsonl --out <file>` | Resume every export page into one file. |

Filters: `--actor`, `--actor-type`, `--project`, `--session`, `--source`,
`--phase`, `--outcome`, `--action`, `--resource-type`, `--request-id`,
`--correlation-id`, `--query`, `--since`, `--until`, `--cursor`, and `--limit`.
Account lists and exports require `audit.read` and the account's `auditAccess`
entitlement. Project-wide lists require `project.members.manage` because they can
include private-session metadata. Session reconstruction requires
`project.session.read` and visibility of that session.

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

| Command | Effect |
| --- | --- |
| `machine roles ls [--json]` | List roles, built-in and custom. |
| `machine roles show <role> [--json]` | Show one role's permissions and usage. |
| `machine roles actions [--json]` | List the permission catalog. |
| `machine roles create <key> --name <n> [options]` | Create a custom role. |
| `machine roles set-actions <role> --actions a,b` | Replace a custom role's permissions. |
| `machine roles rm <role>` | Delete a custom role. |
| `machine roles assignments [--project <id>] [--json]` | List policy bindings. |
| `machine roles assign <role> --to <type>:<id>` | Bind a role to a member, group, or token. |
| `machine roles unassign <policy-id>` | Remove a binding. |
| `machine roles export [--project <id>] [--out <file>] [--format toml\|json]` | Dump roles and bindings to a file. |
| `machine roles import <file>` | Apply a roles and bindings file. |

### Grants

Assigns project resources to people. Assigning an agent to a member or group gives them the secrets and connectors that agent declares in `kortix.yaml`.

Agents themselves need no grant for connectors or Sandbox secrets: every agent in the project reaches every connected connector and every Sandbox secret. An agent's own declaration controls its `kortix_cli` actions and which Network boundary and Machine service secrets it receives. See [Secrets](/docs/project/secrets) and [Agents](/docs/project/agents).

| Command | Effect |
| --- | --- |
| `machine grants ls [--json]` | List grants, and which agents can be granted. |
| `machine grants assign <agent-name> --to <who> [--group]` | Assign an agent to a member, or a group with `--group`. |
| `machine grants revoke <grant-id>` | Remove a grant. |

### Manifest validation

| Command | Effect |
| --- | --- |
| `machine validate [--file <path>] [--json] [--scopes]` | Validate the manifest against the canonical schema. Resolves `kortix.yaml` first, then `kortix.toml`. Exit codes: `0` valid, `1` errors, `2` file missing. |
| `machine schema [--version 1\|2] [--url]` | Print the manifest's JSON Schema. `--url` prints the schema URL instead. |

See [Manifest reference](/docs/project/manifest).

### Self-host

`machine self-host <subcommand>` runs your own Machine stack with Docker Compose on a server you control. Subcommands: `init`, `start`, `update`, `version`, `stop`, `restart`, `status`, `ps`, `doctor`, `logs`, `open`, `configure`, `uninstall`, and `env ls`/`env set`/`env rotate`. Run `machine self-host --help` for the full list.

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

A user token is scoped to every project on your accounts. API keys you create on the website start with `mach_pat_`. The token `machine login` saves for you, and every token minted before `mach_pat_` existed, start with `kortix_pat_`. Both work everywhere. 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](/docs/work/runtime).

### Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Success. |
| `1` | Operation failed. Diagnostics print to stderr. |
| `2` | Bad flag, unknown subcommand, or missing required argument. |