Command Reference

Setup And Linking

Command	Context	Purpose
`mate companion setup`	Companion root	Create or reconfigure a companion explicitly.
`mate companion link`	Working repository, TTY	Select or clone a companion, write the link, and install its requirements.
`mate companion list [--json]`	Linked context	List linked repositories.
`mate companion open`	Linked context	Add the working repository and companion to the preferred editor.
`mate companion tui`	Linked context, TTY	Open a shell in the resolved companion.

mate companion link does not accept flags. Its selection and any required installation confirmation are interactive. The default workflow is:

mate install
mate companion link
mate opencode

Installation And Health

Command	Purpose
`mate install [--yes]`	Install and verify core requirements or refresh the active companion requirements.
`mate doctor`	Show context, policy, selected capabilities, and tool status.
`mate config [--vscode]`	Open the global `~/.mate` configuration directory.
`mate report [--days N] [--input FILE\|-] [--json]`	Generate a built-in or structured report.
`mate studio`	Serve a local, read-only page over the workflow and every registered companion.

mate install --yes skips interactive confirmation and is required when the process has no TTY. It can run before a companion is linked; in that context it installs only Mate’s core requirements.

Without --input, mate report collects configured usage and savings data. To create a report from a skill or script, pass a versioned JSON ReportDocument with --input FILE, or use --input - to read JSON from stdin. The document contains version: 1, title, generatedAt, metadata, summary, and typed sections: metadata, metrics, key-value, table, statuses, or text. Section IDs must be unique and dynamic values are limited to JSON scalar values.

Use --json with either path for normalized JSON output. Otherwise Mate writes self-contained HTML to a temporary file and opens it in the default browser. The HTML includes a browser-native Print / Save as PDF control; selecting Save as PDF in the print dialog creates the PDF. No PDF runtime or server is required.

Studio

mate studio serves one local page showing the Mate and workflow with the selected companion’s real state on it: a Dashboard over its changes and specs, and a Workflow view presenting the prompts a change is driven by — one card per prompt, copied by clicking it. It runs from any directory, binds a port the operating system assigns on the loopback interface, opens the platform browser, and serves in the foreground until interrupted. Every endpoint is read-only. See mate studio.

Agent Launch

mate claude [-- agent-args...]
mate opencode [-- agent-args...]

Launch commands must run from a linked working repository. The companion’s allowed agents list must include the requested agent.

Mate synchronizes managed companion files before launch. If the companion’s configuration uses Git auto mode, it also fetches and merges the configured upstream first:

mate claude -- --no-git
mate opencode -- --no-git

The --no-git switch is Mate’s option only when it appears after the -- separator. All other arguments after the separator are forwarded to the agent.

Capabilities

Command	Purpose
`mate cap openspec <subcommand> [args...]`	Run OpenSpec through the active context.
`mate cap graphify <subcommand> [args...]`	Run Graphify through the active context.
`mate cap index`	Refresh enabled Graphify and TokenSave indexes.
`mate cap index --graphify`	Refresh only Graphify.
`mate cap index --tokensave`	Refresh only TokenSave.

The two index flags cannot be combined. When both Graphify and TokenSave are enabled, the default index flow refreshes TokenSave and then refreshes Graphify against the resulting state.

Artifacts And Updates

Command	Purpose
`mate artifact finish <change-name> [options]`	Finalize a change artifact workflow.
`mate update`	Upgrade an npm-managed Mate installation and reinstall requirements.
`mate update --check`	Check for an update without installing it.

Artifact finish options are --type openspec, --force, --no-push, and --json. Update also accepts --yes to skip its confirmation prompt.

Exit And Recovery Behavior

Unknown commands print the current usage text and exit non-zero. Missing or stale installation state is repaired automatically when every requirement is already available. If a requirement is missing, the companion is ambiguous, or the Mate engine requirement is unsatisfied, Mate prints the reason and points to mate install instead. Doctor, setup, link, update, help, and version remain available so the state can be repaired.