> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codemachine.co/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Complete reference for all CodeMachine CLI commands, flags, and environment variables.

## Main Command

```bash theme={null}
codemachine [options]
```

Launches the interactive TUI when run without subcommands.

<Warning>
  Cannot run from home directory. Use `--dir` or `cd` into a project first.
</Warning>

### 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

```bash theme={null}
codemachine version
```

Display CLI version.

***

### run

```bash theme={null}
codemachine run <script>
```

Run agent(s) with enhanced syntax.

#### Options

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

<Note>
  The `run` command uses the default engine (first authenticated engine).
</Note>

#### Script Syntax

<CodeGroup>
  ```bash Single agent theme={null}
  # Runs the code-generator agent with the prompt "Build login feature"
  codemachine run "code-generator 'Build login feature'"
  ```

  ```bash With input files theme={null}
  # Runs system-analyst with spec.md as input, including the last 100 lines
  codemachine run "system-analyst[input:spec.md,tail:100] 'analyze'"
  ```

  ```bash Multiple inputs theme={null}
  # Runs arch-writer with two input files: file1.md and file2.md
  codemachine run "arch-writer[input:file1.md;file2.md]"
  ```

  ```bash Parallel execution (&) theme={null}
  # Runs frontend and backend agents simultaneously in parallel
  codemachine run "frontend 'UI' & backend 'API'"
  ```

  ```bash Sequential execution (&&) theme={null}
  # Runs db first, then backend only after db completes successfully
  codemachine run "db 'setup' && backend 'models'"
  ```

  ```bash Mixed execution theme={null}
  # Runs db first, then frontend and backend in parallel after db completes
  codemachine run "db 'setup' && frontend & backend"
  ```
</CodeGroup>

#### 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

```bash theme={null}
codemachine templates
```

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

```bash theme={null}
codemachine templates list
```

List available template names (non-interactive).

***

### auth

```bash theme={null}
codemachine auth login
```

Authenticate with an AI engine (interactive provider selection).

```bash theme={null}
codemachine auth logout
```

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

***

### agents

```bash theme={null}
codemachine agents
```

List all active and offline agents in tree view.

```bash theme={null}
codemachine agents logs <id>
```

View logs for a specific agent by numeric ID.

```bash theme={null}
codemachine agents export
```

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

***

### import

```bash theme={null}
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

```bash theme={null}
codemachine import moazbuilds/pack-rust
codemachine import ./my-pack
codemachine import --list
codemachine import --remove pack-rust
```

***

### export

```bash theme={null}
codemachine export
```

Show the imports folder path.

***

### mcp router

```bash theme={null}
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

<Tabs>
  <Tab title="Claude (Anthropic)">
    | 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        |
  </Tab>

  <Tab title="OpenCode">
    | Variable                    | Description                      |
    | :-------------------------- | :------------------------------- |
    | `CODEMACHINE_OPENCODE_HOME` | OpenCode configuration directory |
  </Tab>

  <Tab title="Mistral">
    | Variable                   | Description                     |
    | :------------------------- | :------------------------------ |
    | `CODEMACHINE_MISTRAL_HOME` | Mistral configuration directory |
  </Tab>

  <Tab title="Cursor">
    | Variable                  | Description                    |
    | :------------------------ | :----------------------------- |
    | `CODEMACHINE_CURSOR_HOME` | Cursor configuration directory |
  </Tab>

  <Tab title="Auggie">
    | Variable                  | Description                    |
    | :------------------------ | :----------------------------- |
    | `CODEMACHINE_AUGGIE_HOME` | Auggie configuration directory |
  </Tab>

  <Tab title="Codex">
    | Variable                 | Description                   |
    | :----------------------- | :---------------------------- |
    | `CODEMACHINE_CODEX_HOME` | Codex configuration directory |
  </Tab>

  <Tab title="CCR">
    | Variable               | Description                 |
    | :--------------------- | :-------------------------- |
    | `CODEMACHINE_CCR_HOME` | CCR configuration directory |
  </Tab>
</Tabs>

***

## Examples

<CodeGroup>
  ```bash Debug mode theme={null}
  DEBUG=1 codemachine
  ```

  ```bash Verbose logging theme={null}
  LOG_LEVEL=debug codemachine
  ```

  ```bash Custom working directory theme={null}
  CODEMACHINE_CWD=/path/to/project codemachine
  ```

  ```bash Custom spec file theme={null}
  CODEMACHINE_SPEC_PATH=./my-spec.md codemachine
  ```

  ```bash Agent timeout (30s) theme={null}
  CODEMACHINE_AGENT_TIMEOUT=30000 codemachine run "agent 'task'"
  ```

  ```bash Disable updates theme={null}
  CODEMACHINE_NO_UPDATE_CHECK=1 codemachine
  ```

  ```bash Custom Anthropic endpoint theme={null}
  CODEMACHINE_ANTHROPIC_BASE_URL=https://proxy.example.com/v1 codemachine
  ```
</CodeGroup>

***

## 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  |