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

# CLI Commands

> Command line interface reference

## Basic Commands

### puzldai

Launch interactive TUI (default when no arguments).

```bash theme={null}
puzldai
puzldai tui    # Same as above
```

### puzldai run

Run a task with the best available agent.

```bash theme={null}
puzldai run <task> [options]
```

| Option | Description |
| - | - |
| `-a, --agent <agent>` | Force specific agent (claude, gemini, codex, ollama) |
| `-m, --model <model>` | Override model (e.g., sonnet, opus, gemini-2.5-flash) |
| `-P, --pipeline <steps>` | Run as pipeline (e.g., "gemini:analyze,claude:code") |
| `-T, --template <name>` | Use a saved pipeline template |
| `-i, --interactive` | Prompt before each step in pipeline mode |

**Examples:**

```bash theme={null}
puzldai run "explain recursion"
puzldai run "build an API" -a claude
puzldai run "task" -m opus
puzldai run "build a logger" -P "gemini:analyze,claude:code,gemini:review"
puzldai run "task" -T code-review -i
```

### puzldai compare

Compare responses from multiple agents.

```bash theme={null}
puzldai compare <prompt> [options]
```

| Option | Description |
| - | - |
| `-a, --agents <agents>` | Comma-separated agents (default: claude,gemini) |
| `-s, --sequential` | Run agents sequentially instead of parallel |
| `-p, --pick` | Have an LLM pick the best response |

**Examples:**

```bash theme={null}
puzldai compare "best error handling practices"
puzldai compare "task" -a claude,gemini,codex
puzldai compare "task" -s -p
```

### puzldai autopilot

Generate and optionally execute an AI-planned workflow.

```bash theme={null}
puzldai autopilot <task> [options]
```

| Option | Description |
| - | - |
| `-x, --execute` | Execute the plan after generating |
| `-i, --interactive` | Prompt before each step (requires --execute) |
| `-p, --planner <agent>` | Agent to use for planning (default: ollama) |

**Examples:**

```bash theme={null}
puzldai autopilot "build a todo app"
puzldai autopilot "task" -x
puzldai autopilot "task" -x -i -p claude
```

### puzldai agent

Interactive agent mode.

```bash theme={null}
puzldai agent [options]
```

| Option | Description |
| - | - |
| `-a, --agent <agent>` | Force specific agent (default: auto) |
| `-m, --model <model>` | Override model for the agent |

**Examples:**

```bash theme={null}
puzldai agent
puzldai agent -a claude -m opus
```

### puzldai check

Check available agents and dependencies.

```bash theme={null}
puzldai check
```

***

## Collaboration Commands

### puzldai correct

Cross-agent correction: one produces, another reviews.

```bash theme={null}
puzldai correct <task> --producer <agent> --reviewer <agent> [options]
```

| Option | Description |
| - | - |
| `--producer <agent>` | Agent to produce initial output (required) |
| `--reviewer <agent>` | Agent to review and critique (required) |
| `-f, --fix` | Have producer fix issues after review |

**Examples:**

```bash theme={null}
puzldai correct "write a sorting algorithm" --producer claude --reviewer gemini
puzldai correct "task" --producer claude --reviewer gemini --fix
```

### puzldai debate

Multi-agent debate on a topic.

```bash theme={null}
puzldai debate <topic> -a <agents> [options]
```

| Option | Description |
| - | - |
| `-a, --agents <agents>` | Comma-separated agents to debate (required) |
| `-r, --rounds <n>` | Number of debate rounds (default: 2) |
| `-m, --moderator <agent>` | Agent to synthesize conclusion |

**Examples:**

```bash theme={null}
puzldai debate "microservices vs monolith" -a claude,gemini
puzldai debate "topic" -a claude,gemini -r 3 -m ollama
```

### puzldai consensus

Build consensus among multiple agents.

```bash theme={null}
puzldai consensus <task> -a <agents> [options]
```

| Option | Description |
| - | - |
| `-a, --agents <agents>` | Comma-separated agents (required) |
| `-r, --rounds <n>` | Number of voting rounds (default: 2) |
| `-s, --synthesizer <agent>` | Agent to synthesize final result |

**Examples:**

```bash theme={null}
puzldai consensus "best database choice" -a claude,gemini,ollama
puzldai consensus "task" -a claude,gemini -r 3 -s claude
```

***

## Model Commands

### puzldai model show

Show current model settings for all agents.

```bash theme={null}
puzldai model show
```

### puzldai model list

List available models.

```bash theme={null}
puzldai model list [agent]
```

### puzldai model set

Set model for an agent.

```bash theme={null}
puzldai model set <agent> <model>
```

**Examples:**

```bash theme={null}
puzldai model set claude opus
puzldai model set gemini gemini-2.0-flash
```

### puzldai model clear

Clear model override (use CLI default).

```bash theme={null}
puzldai model clear <agent>
```

***

## Template Commands

### puzldai template list

List all available templates.

```bash theme={null}
puzldai template list
```

### puzldai template show

Show template details.

```bash theme={null}
puzldai template show <name>
```

### puzldai template create

Create a new template.

```bash theme={null}
puzldai template create <name> -P <steps> [options]
```

| Option | Description |
| - | - |
| `-P, --pipeline <steps>` | Pipeline steps (required) |
| `-d, --description <desc>` | Template description |

**Example:**

```bash theme={null}
puzldai template create code-review -P "gemini:analyze,claude:code,gemini:review" -d "Code review pipeline"
```

### puzldai template edit

Edit an existing template.

```bash theme={null}
puzldai template edit <name> [options]
```

| Option | Description |
| - | - |
| `-P, --pipeline <steps>` | New pipeline steps |
| `-d, --description <desc>` | New description |

### puzldai template delete

Delete a template.

```bash theme={null}
puzldai template delete <name>
```

***

## Session Commands

### puzldai session list

List all sessions.

```bash theme={null}
puzldai session list [agent]
```

### puzldai session new

Create a new session.

```bash theme={null}
puzldai session new [agent]
```

### puzldai session info

Show session details.

```bash theme={null}
puzldai session info <id>
```

### puzldai session delete

Delete a session.

```bash theme={null}
puzldai session delete <id>
```

### puzldai session clear

Clear session history (keep session, remove messages).

```bash theme={null}
puzldai session clear <id>
```

***

## Index Commands

### puzldai index

Index codebase for semantic search.

```bash theme={null}
puzldai index [path] [options]
```

| Option | Description |
| - | - |
| `-q, --quick` | Quick index (skip embedding) |
| `-c, --clear` | Clear the code index |
| `-s, --stats` | Show index statistics |
| `-S, --search <query>` | Search indexed code |
| `-C, --context <task>` | Get relevant code context for a task |
| `--config` | Show project configuration details |
| `-g, --graph` | Show dependency graph summary |
| `-m, --max-files <n>` | Maximum files to index (default: 1000) |

**Examples:**

```bash theme={null}
puzldai index
puzldai index --quick
puzldai index --search "handleLogin"
puzldai index --context "fix auth bug"
puzldai index --config
puzldai index --graph
```

***

## Observe Commands

### puzldai observe summary

Show observation summary.

```bash theme={null}
puzldai observe summary [-a <agent>]
```

### puzldai observe list

List recent observations.

```bash theme={null}
puzldai observe list [options]
```

| Option | Description |
| - | - |
| `-a, --agent <agent>` | Filter by agent |
| `-n, --limit <n>` | Number to show (default: 10) |

### puzldai observe export

Export observations to file.

```bash theme={null}
puzldai observe export <output> [options]
```

| Option | Description |
| - | - |
| `-f, --format <format>` | Output format: jsonl, json, csv (default: jsonl) |
| `-a, --agent <agent>` | Filter by agent |
| `-n, --limit <n>` | Max records (default: 10000) |
| `-t, --type <type>` | Export type: observations, preferences |
| `--no-content` | Exclude content (metadata only) |

**Examples:**

```bash theme={null}
puzldai observe export data.jsonl
puzldai observe export prefs.jsonl -t preferences
puzldai observe export data.csv -f csv -a claude
```

***

## Server Commands

### puzldai serve

Start the API server or MCP bridge.

```bash theme={null}
puzldai serve [options]
```

| Option | Description |
| - | - |
| `-p, --port <port>` | Port to listen on (default: 3000) |
| `-H, --host <host>` | Host to bind to (default: 0.0.0.0) |
| `--mcp` | Start as MCP bridge (connects to puzld.cc) |
| `-w, --web` | Also start ttyd web terminal |
| `-t, --terminal-port <port>` | Terminal port (default: 3001) |

**Examples:**

```bash theme={null}
puzldai serve
puzldai serve -p 8080
puzldai serve --mcp
puzldai serve -w -t 3001
```

***

## Auth Commands

### puzldai login

Login to PuzldAI cloud.

```bash theme={null}
puzldai login
```

Opens a browser for authentication. After login, a token is saved to `~/.puzldai/config.json`.

### puzldai logout

Logout from PuzldAI cloud.

```bash theme={null}
puzldai logout
```

### puzldai whoami

Show current login status.

```bash theme={null}
puzldai whoami
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.