CLI reference

The machine 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/machine).
• MACHINE_CLI_TOKEN pre-injected — the project-scoped token the CLI authenticates with. (MACHINE_TOKEN is also present, but it's the sandbox service key, not a CLI token.)
• MACHINE_API_URL points at the platform you're running against.

Quickstart inside a session

machine whoami                       # confirms what project + account this token has
machine projects info                # the project you're running inside
machine secrets ls                   # encrypted env vars + manifest [env] spec
machine sessions ls                  # every session on this project (incl. you)
machine cr ls                        # open change requests
machine 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://machine.com/install | bash
machine login                        # opens browser, you click Authorize

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

Command surface

Auth

Hosts

A host is one Machine API endpoint. The built-ins cloud (Machine Cloud), selfhost (your machine self-host stack), local-dev (a local pnpm dev server), and machine-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: machine projects ls --host local.

Self-host

machine self-host start creates and starts a production-style local Machine stack using Docker Compose. On first interactive setup it only asks for the product integrations you may need: Vercel for app 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. MACHINE_PROJECT_ID env var.
3. .machine/link.json in cwd (or any ancestor — git-style).
4. Inside a session sandbox: the sandbox's own MACHINE_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 .machine/link.json (so a repo always hits its home Machine 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, MACHINE_SESSION_ID is your session; machine sessions info $MACHINE_SESSION_ID is the live view of yourself.

Triggers

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

Change requests (cr)

Machine-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 (MACHINE_BRANCH_NAME)
git push origin HEAD

# 3. Open the CR — head and session are auto-detected
machine 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
machine cr ls

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

The agent does not merge its own CR — that's the user's call, in the dashboard or via machine 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 machine help for the full list.

Token scope

Two token types, both with the machine_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):

MACHINE_CLI_TOKEN=…          # project-scoped PAT — the CLI authenticates with this
MACHINE_TOKEN=…              # sandbox service key (daemon control surface) — NOT a CLI token
MACHINE_API_URL=https://machineapi.myapps.ai
MACHINE_PROJECT_ID=<uuid>
MACHINE_SESSION_ID=<uuid>

The CLI reads MACHINE_CLI_TOKEN automatically (falling back to MACHINE_EXECUTOR_TOKEN, the same value) and uses MACHINE_API_URL as the host base. No config file needed. Don't reach for MACHINE_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

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

Inside a session: trigger another session

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

Run a trigger by hand for debugging

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

Pull current secrets into a local .env for development

machine 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

machine env push --from .env
machine 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

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

machine cr ls                            # confirm

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

Environment variables the CLI reads

The MACHINE_* 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 machine self-host start to run your own local Machine Cloud stack, then switch between Cloud and local APIs with machine hosts use.
• Not a git replacement. machine 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 Machine vs OpenCode config.