CLI Reference

The mashin CLI is how you interact with machines from the terminal. It handles everything from creating machines to deploying them, managing secrets, working with the registry, and running action services.

Installation

# macOS
brew install mashin-live/tap/mashin

# Or download directly
curl -fsSL https://get.mashin.live | sh

Verify the installation:

mashin --version

Shell completions

Generate completions for your shell:

mashin completions bash >> ~/.bashrc
mashin completions zsh >> ~/.zshrc
mashin completions fish >> ~/.config/fish/completions/mashin.fish

Command reference

Core commands

These are the commands you will use most often.

Command	Description
mashin new <name>	Create a new machine
mashin init	Create a new machine project
mashin run <machine>	Execute a machine
mashin test <machine>	Run machine tests
mashin compile	Compile machines
mashin validate <file>	Validate a .mashin file
mashin fmt <file>	Format a .mashin file
mashin info <machine>	Show machine info
mashin surface <machine>	Show a machine’s resolved runtime surface
mashin list	List machines in the current project
mashin runs	Show execution history
mashin chat	Start interactive chat mode
mashin docs	Generate or view documentation
mashin setup	Interactive first-run setup
mashin config	View or set configuration
mashin models	Show model tier mappings
mashin report	Generate a signed bug report
mashin lsp	Start the language server (stdio)
mashin mcp	Start MCP server
mashin deploy <file.mashin>	Deploy a machine to the cloud (--local for a local process)
mashin tunnel <machine>	Expose a local machine via tunnel

Machine lifecycle

Commands for managing running machines.

Command	Description
mashin status	Show the machines that are on
mashin pause <machine>	Pause a running machine
mashin resume <machine>	Resume a paused machine
mashin stop <machine>	Stop a machine
mashin kill <machine>	Force-terminate a machine
mashin restart <machine>	Restart a machine
mashin logs <machine>	Tail machine logs
mashin inspect <run_id>	Inspect a recorded run (see Debugging)
mashin rollback <machine>	Roll back to a previous version
mashin archive <machine>	Archive a machine definition

Debugging

Every run leaves a complete, hash-chained record in the behavioral ledger. These commands read it back. The primary debugging surface is the run view in the app; these are the reference commands for the same record.

Command	Description
mashin runs	List recent runs (id, machine, outcome, cost)
mashin inspect <run_id>	Show a run’s failure envelope, governance decisions, and chain integrity
mashin inspect <machine>	Inspect the most recent run of a machine by name
mashin inspect <run_id> --vars	Add the reconstructed variable environment for each step
mashin replay <run_id>	Faithfully replay a recorded run, effects served from the ledger
mashin replay <run_id> --reevaluate	Replay against the current policy, to see what would change

mashin inspect answers the usual debugging questions in one place: which step ran, what it produced, why it failed or was denied, and whether the hash chain is intact. Add --vars to see the full variable environment at each step, reconstructed from the record. Add --json for a machine-readable dump.

# Why did the last run of email_triage fail, and what were its variables?
mashin inspect email_triage --vars

# Replay a specific run exactly as it happened (no live effects, no cost)
mashin replay run_abc123

# Replay it against today's policy to see whether governance would now decide differently
mashin replay run_abc123 --reevaluate

mashin replay never calls the outside world on a faithful replay: every effect is served from what the original run recorded, so a replay costs nothing and cannot have side effects. --reevaluate re-runs the governance decisions against the current policy and reports where they diverge; --against provider:model replays the reasoning steps against a different model. Add --json to either for a machine-readable report.

Registry

Publishing, searching, and installing machines from the kura registry.

Command	Description
mashin login	Authenticate with the registry
mashin logout	Sign out
mashin search <query>	Search the registry
mashin install <krate>	Install a package
mashin publish	Publish to the registry
mashin pack	Create a .krate package
mashin save	Save to local registry
mashin verify <krate>	Verify krate integrity

Krate management

Working with krates (machine packages).

Command	Description
mashin krate new	Scaffold a new krate
mashin krate validate	Validate mashin.toml manifest
mashin krate parse	Parse all .mashin files
mashin krate compile	Compile all machines
mashin krate test	Run embedded tests
mashin krate lint	Quality gate check
mashin krate hash	Compute content hash

Secrets

Managing API keys and credentials.

Command	Description
mashin secrets set <name> <value>	Store a secret
mashin secrets get <name>	Retrieve a secret
mashin secrets list	List stored secrets
mashin secrets delete <name>	Delete a secret

Actions

Managing external action services.

Command	Description
mashin action init <language>	Scaffold a new action service
mashin action start <path>	Start a script as an action service
mashin action stop <name>	Stop a running action service
mashin action list	List running action services
mashin action register <url>	Register an external action service
mashin action test <url>	Test an action service endpoint

Skills

Working with skills (interop with Claude Code and other tools).

Command	Description
mashin skill export <machine>	Export a machine as a Claude Code skill
mashin skill import <path>	Import a skill as a governed machine
mashin skill list	List available skills
mashin skill search <query>	Search skills by intent

Computer management

Managing computers (local and remote compute environments).

Command	Description
mashin computer start	Start a computer
mashin computer stop	Stop a computer
mashin computer status	Show computer health
mashin computer list	List all computers
mashin computer connect <name>	Set the active computer
mashin computer add <name> <url>	Add a remote computer
mashin computer info	Show computer info
mashin identity	Show computer identity
mashin pair	Show pairing QR code
mashin link	Link computer to account

mashin run in depth

The run command is the primary way to execute machines.

mashin run <machine> [options]

Options

Flag	Description
--input / -i <json>	JSON object as input. Supports @file references (see below)
--input-file / -f <path>	Path to a JSON file to use as input
--project-dir / -d <path>	Path to the project directory (default: current directory)
--to <mode>	Interpretation mode: explain, cost, simulate, evaluate, verify, improve
--verbose / -v	Show detailed output
--trace / -t	Print the governance trace (step names, types, durations, hash chain)
--json / -j	Output as structured JSON (for scripting)
--format <fmt>	Output format: human (default), json, yaml, jsonl, text
--transform <path>	Extract a value at a dot-path before formatting

@file input references

Prefix a file path with @ to read its contents as input:

mashin run hello --input @params.json
mashin run hello -i @input.json

This is equivalent to --input-file params.json but more concise.

Output formatting

By default, mashin run prints human-readable output. For scripting, use --format and --transform:

# Get just the result as JSON
mashin run hello --format json --transform result

# Extract a specific field as plain text
mashin run hello --format text --transform result.summary

# YAML output
mashin run hello --format yaml

# Compact single-line JSON (for piping)
mashin run hello --format jsonl

# Assign to a shell variable
SUMMARY=$(mashin run hello --format text --transform result.summary)

Input methods

Three ways to pass input:

# 1. Inline JSON
mashin run hello --input '{"name": "World"}'

# 2. @file reference
mashin run hello --input @params.json

# 3. Stdin (piped)
cat params.json | mashin run hello

Authentication

Browser login (recommended)

mashin login

Opens your browser for OAuth authentication with PKCE. Credentials are saved to ~/.mashin/credentials.json and auto-refresh.

Headless / remote login

For servers, Docker containers, or machines without a browser:

mashin login --no-browser

Prints the authorization URL. Open it on another device, complete login, and the callback is received automatically.

API key login

For CI/CD pipelines and scripts:

# Interactive prompt
mashin login --api-key

# Direct token
mashin login --token msk_your_api_key

API keys are generated at mashin.live/settings/api-keys.

Check auth status

mashin identity

Common workflows

Create and run a machine

mashin new email_classifier
mashin run email_classifier --input '{"subject": "Invoice", "body": "Payment due"}'

Test without API keys

mashin test email_classifier

Tests use assuming values, so they run fast and free.

View the governance trace

mashin run email_classifier --input '{"subject": "hello"}' --trace

See what a machine can actually do

mashin surface prints the resolved runtime surface: what the machine declares, what this computer resolves that declaration to, what its trust level admits, what every machine it calls contributes, and where the composition reaches a platform entry point.

mashin surface email_classifier
mashin surface email_classifier --json
mashin surface email_classifier --declared        # only the grant, the view an install shows
mashin surface email_classifier --depth 3
mashin surface email_classifier --trust untrusted # project it at another trust level

The two fingerprints it prints are the ones a real run records on its receipt, so a dump and a receipt can be compared directly.

Format and validate before publishing

mashin fmt .
mashin validate .
mashin publish

Scaffold and register an action service

mashin action init python my_action
# Edit the generated service
mashin action start my_action/server.py
mashin action test http://localhost:8080
mashin action register http://localhost:8080

Work with multiple computers

# List available computers
mashin computer list

# Switch to a different computer
mashin computer connect production

# Or set via environment variable
MASHIN_COMPUTER_ID=production mashin run hello

Environment variables

Variable	Purpose
MASHIN_API_URL	Override the default API endpoint
MASHIN_COMPUTER_ID	Set the active computer
MASHIN_OUTPUT	Default output format: json, yaml, jsonl, text
MASHIN_LOG_LEVEL	Set log verbosity (debug, info, warn, error)

Next steps

• Editor Setup - VS Code and Zed integration
• Language Server - LSP features
• SDKs - Build action services in any language