# CLI Reference

Complete reference for the `legion` command-line interface.

## Global Options

```
legion --version    Show version number
legion --help       Show help message
```

---

## init

Initialize a parent with optional children.

### Synopsis

```bash
legion init <parent> [children...] [options]
```

### Arguments

| Argument | Description |
|----------|-------------|
| `parent` | Parent name/ID (required) |
| `children` | Child names/IDs (optional, space-separated) |

### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--repo PATH` | Path to git repository | Current directory |
| `--agent {claude,cursor}` | Agent to launch in children | `claude` |
| `--no-agent` | Don't launch agents | - |
| `--no-tmux` | Git-only mode, skip tmux/agents | - |
| `--dry-run` | Print actions without executing | - |
| `--verbose, -v` | Verbose output | - |

### Examples

```bash
# Create parent only
legion init my-feature

# Create with children
legion init my-feature task-a task-b

# Use Cursor instead of Claude
legion init my-feature task-a --agent cursor

# Git-only, no tmux
legion init my-feature task-a --no-tmux

# Add children to existing parent
legion init my-feature new-task
```

### Behavior

1. Slugifies and validates all IDs
2. Creates parent worktree and branch (if missing)
3. Creates tmux session (if not `--no-tmux`)
4. Discovers existing children from:
   - Worktree directories
   - Git branches matching `<parent>/*`
   - tmux windows
5. Creates/ensures each child's worktree, branch, and window
6. Launches agents in children (unless `--no-agent`)
7. Reorders windows and applies colors

---

## remove

Remove parent and/or children.

### Synopsis

```bash
legion remove <parent> [children...] [options]
```

### Arguments

| Argument | Description |
|----------|-------------|
| `parent` | Parent name/ID (required) |
| `children` | Child names/IDs to remove (optional) |

### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--repo PATH` | Path to git repository | Current directory |
| `--force` | Force removal of dirty worktrees | - |
| `--dry-run` | Print actions without executing | - |
| `--yes, -y` | Skip confirmation prompts | - |
| `--verbose, -v` | Verbose output | - |

### Examples

```bash
# Remove specific children
legion remove my-feature task-a task-b

# Remove all children and parent
legion remove my-feature

# Force remove dirty worktrees
legion remove my-feature --force

# Preview removal
legion remove my-feature --dry-run
```

### Behavior

**When children specified:**

1. For each child:
   - Kill tmux window
   - Terminate agent process
   - Remove git worktree
   - Delete git branch

**When no children specified:**

1. Remove all children (as above)
2. Kill tmux session
3. Remove parent worktree
4. Delete parent branch
5. Clean up parent directory

---

## list

List parents and children.

### Synopsis

```bash
legion list [parent] [options]
```

### Arguments

| Argument | Description |
|----------|-------------|
| `parent` | Parent to list children for (optional) |

### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--repo PATH` | Path to git repository | Current directory |
| `--json` | Output as JSON | - |
| `--verbose, -v` | Verbose output | - |

### Examples

```bash
# List all parents
legion list

# List children of a parent
legion list my-feature

# Verbose output
legion list my-feature -v
```

### Output

**List all parents:**

```
my-feature (3 children, session=managed)
other-feature (0 children, session=none)
```

**List children:**

```
Parent: my-feature
  Branch: my-feature/parent
  Worktree: /path/to/worktrees/my-feature/parent
  Session: managed

Children:
  task-a
    my-feature/task-a | window=yes | agent=running
  task-b
    my-feature/task-b | window=yes | agent=stopped
```

---

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Error (invalid arguments, git errors, etc.) |
