CLI Reference - Documentation

Main Command

codemachine [options]

Launches the interactive TUI when run without subcommands.

Cannot run from home directory. Use --dir or cd into a project first.

Global Options

Flag	Description	Default
`-d, --dir <path>`	Target workspace directory	Current directory
`--spec <path>`	Path to planning specification file	`.codemachine/inputs/specifications.md`
`-V, --version`	Display version	-
`-h, --help`	Display help	-

Commands

version

codemachine version

Display CLI version.

run

codemachine run <script>

Run agent(s) with enhanced syntax.

Options

Flag	Description	Default
`-d, --dir <directory>`	Working directory	Current directory

The run command uses the default engine (first authenticated engine).

Script Syntax

# Runs the code-generator agent with the prompt "Build login feature"
codemachine run "code-generator 'Build login feature'"

# Runs system-analyst with spec.md as input, including the last 100 lines
codemachine run "system-analyst[input:spec.md,tail:100] 'analyze'"

# Runs arch-writer with two input files: file1.md and file2.md
codemachine run "arch-writer[input:file1.md;file2.md]"

# Runs frontend and backend agents simultaneously in parallel
codemachine run "frontend 'UI' & backend 'API'"

# Runs db first, then backend only after db completes successfully
codemachine run "db 'setup' && backend 'models'"

# Runs db first, then frontend and backend in parallel after db completes
codemachine run "db 'setup' && frontend & backend"

Agent Options

Agent options are specified in brackets after the agent name:

Option	Description	Example
`input:<file>`	Single input file	`agent[input:spec.md]`
`input:<file1>;<file2>`	Multiple input files	`agent[input:a.md;b.md]`
`tail:<n>`	Tail lines to include	`agent[tail:100]`

templates

codemachine templates

Interactive workflow template selection. Saves selection to .codemachine/template.json and regenerates agents folder.

codemachine templates list

List available template names (non-interactive).

auth

codemachine auth login

Authenticate with an AI engine (interactive provider selection).

codemachine auth logout

Sign out from an AI engine (interactive provider selection).

agents

codemachine agents

List all active and offline agents in tree view.

codemachine agents logs <id>

View logs for a specific agent by numeric ID.

codemachine agents export

Export agent registry to .codemachine/logs/registry-export.json.

import

codemachine import [source]

Import external workflow packages.

Options

Flag	Description
`-l, --list`	List installed imports
`-r, --remove`	Remove an import
`-v, --verbose`	Verbose output

Source Formats

Format	Example
Package name	`codemachine-pack-rust`
GitHub owner/repo	`moazbuilds/codemachine-pack-rust`
GitHub URL	`https://github.com/user/repo`
Git SSH	`git@github.com:user/repo.git`
Local path	`/path/to/folder` or `./relative`

Examples

codemachine import moazbuilds/pack-rust
codemachine import ./my-pack
codemachine import --list
codemachine import --remove pack-rust

export

codemachine export

Show the imports folder path.

mcp router

codemachine mcp router

Start MCP router server (stdio mode). This command is for internal agent use only.

Environment Variables

Variable	Description	Default
`LOG_LEVEL`	Log level: `debug`, `info`, `warn`, `error`	`info`

Engine Configuration

Variable	Description
`CODEMACHINE_CLAUDE_HOME`	Claude configuration directory
`CODEMACHINE_ANTHROPIC_BASE_URL`	Custom API base URL
`CODEMACHINE_ANTHROPIC_AUTH_TOKEN`	Anthropic auth token
`CODEMACHINE_ANTHROPIC_API_KEY`	Anthropic API key
`CODEMACHINE_CLAUDE_OAUTH_TOKEN`	Claude Code OAuth token

Variable	Description
`CODEMACHINE_OPENCODE_HOME`	OpenCode configuration directory

Variable	Description
`CODEMACHINE_MISTRAL_HOME`	Mistral configuration directory

Variable	Description
`CODEMACHINE_CURSOR_HOME`	Cursor configuration directory

Variable	Description
`CODEMACHINE_AUGGIE_HOME`	Auggie configuration directory

Variable	Description
`CODEMACHINE_CODEX_HOME`	Codex configuration directory

Variable	Description
`CODEMACHINE_CCR_HOME`	CCR configuration directory

Examples

DEBUG=1 codemachine

LOG_LEVEL=debug codemachine

CODEMACHINE_CWD=/path/to/project codemachine

CODEMACHINE_SPEC_PATH=./my-spec.md codemachine

CODEMACHINE_AGENT_TIMEOUT=30000 codemachine run "agent 'task'"

CODEMACHINE_NO_UPDATE_CHECK=1 codemachine

CODEMACHINE_ANTHROPIC_BASE_URL=https://proxy.example.com/v1 codemachine

Quick Reference

Command	Description
`codemachine`	Launch TUI
`codemachine version`	Show version
`codemachine run <script>`	Run agents
`codemachine templates`	Select template
`codemachine templates list`	List templates
`codemachine auth login`	Login
`codemachine auth logout`	Logout
`codemachine agents`	List agents
`codemachine agents logs <id>`	View agent logs
`codemachine agents export`	Export registry
`codemachine import <source>`	Install package
`codemachine import --list`	List imports
`codemachine import --remove <name>`	Remove import
`codemachine export`	Show imports path
`codemachine mcp router`	Start MCP server

​Main Command

​Global Options

​Commands

​version

​run

​Options

​Script Syntax

​Agent Options

​templates

​auth

​agents

​import

​Options

​Source Formats

​Examples

​export

​mcp router

​Environment Variables

​Engine Configuration

​Examples

​Quick Reference

Main Command

Global Options

Commands

version

run

Options

Script Syntax

Agent Options

templates

auth

agents

import

Options

Source Formats

Examples

export

mcp router

Environment Variables

Engine Configuration

Examples

Quick Reference