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 effect 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 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 launch <machine>	Launch a machine (long-running)
mashin tunnel <machine>	Expose a local machine via tunnel

Machine lifecycle

Commands for managing running machines.

Command	Description
mashin status	Show launched machines
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 governance trace
mashin rollback <machine>	Roll back to a previous version
mashin archive <machine>	Archive a machine definition

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

Effects

Managing external effect services.

Command	Description
mashin effect init <language>	Scaffold a new effect service
mashin effect start <path>	Start a script as an effect service
mashin effect stop <name>	Stop a running effect service
mashin effect list	List running effect services
mashin effect register <url>	Register an external effect service
mashin effect test <url>	Test an effect 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

Cell management

Managing cells (local and remote compute environments).

Command	Description
mashin cell start	Start a cell
mashin cell stop	Stop a cell
mashin cell status	Show cell health
mashin cell list	List all cells
mashin cell connect <name>	Set the active cell
mashin cell switch <id>	Switch to a different cell
mashin cell add <name> <url>	Add a remote cell
mashin cell info	Show cell info
mashin identity	Show cell identity
mashin pair	Show pairing QR code
mashin link	Link cell 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

Format and validate before publishing

mashin fmt .
mashin validate .
mashin publish

Scaffold and register an effect service

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

Work with multiple cells

# List available cells
mashin cell list

# Switch to a different cell
mashin cell switch production

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

Environment variables

Variable	Purpose
MASHIN_API_URL	Override the default API endpoint
MASHIN_CELL_ID	Set the active cell
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 effect services in any language