Commands Reference

Complete reference for all Phantom CLI commands, flags, and options.

This page provides a comprehensive reference for all Phantom commands.

Overview

Overlay Management

phantom start

Create and mount a new overlay.

phantom start <base-path> --name <overlay-name> [flags]

Flags:

Examples:

# Create an overlay named "feature-auth"
phantom start ~/myproject --name feature-auth

# Create with custom branch name
phantom start ~/myproject --name feature-auth --branch auth-implementation

phantom stop

Unmount an overlay without deleting it.

phantom stop <overlay-name> [flags]

Flags:

phantom restart

Unmount and remount an overlay.

phantom restart <overlay-name>

phantom list

List all overlays.

phantom list [flags]

Flags:

phantom status

Show detailed status of an overlay.

phantom status <overlay-name>

phantom inspect

Show detailed information about an overlay in JSON format.

phantom inspect <overlay-name>

Running Agents

phantom run

Create an overlay and run a single agent.

phantom run <base-path> --agent <command> --task <task> --name <name> [flags]

Flags:

Examples:

# Run Claude on a feature
phantom run ~/myproject --agent "claude --print" --task "implement auth" --name auth-feature

# Run with timeout and cleanup
phantom run ~/myproject --agent "aider" --task "fix tests" --name fix-tests --timeout 15m --cleanup

phantom run-all

Run multiple agents in parallel on the same base.

phantom run-all <base-path> [flags]

Flags:

Config File Format (agents.yaml):

agents:
  - name: claude
    command: claude --print
    task: "implement authentication"
  - name: aider
    command: aider
    task: "add unit tests"
  - name: gemini
    command: gemini
    task: "improve error handling"

Examples:

# Run from config file
phantom run-all ~/myproject --config agents.yaml --cleanup

# Run inline agents
phantom run-all ~/myproject --agents "claude --print,aider,gemini" --timeout 30

phantom run-chain

Run agents sequentially, each building on the previous one’s work.

phantom run-chain <base-path> [flags]

Flags:

Examples:

# Chain two agents
phantom run-chain ~/myproject --steps "claude --print,aider" --name pipeline

# With cleanup
phantom run-chain ~/myproject --config chain.yaml --cleanup

Viewing Changes

phantom diff

Show changes in an overlay compared to the base.

phantom diff <overlay-name> [flags]

Flags:

phantom compare

Compare two overlays.

phantom compare <overlay-a> <overlay-b> [flags]

phantom conflicts

Check for potential conflicts between overlays.

phantom conflicts <overlay-a> <overlay-b>

Applying Changes

phantom commit

Commit changes in an overlay to its git branch.

phantom commit <overlay-name> [flags]

Flags:

phantom apply

Apply changes from an overlay back to the base repository.

phantom apply <overlay-name> [flags]

Flags:

phantom merge

Merge an overlay branch into the base branch.

phantom merge <overlay-name> [flags]

Flags:

phantom sync

Sync an overlay with the latest base changes.

phantom sync <overlay-name>

Monitoring

phantom watch

Watch an overlay for changes and trigger actions.

phantom watch <overlay-name> [flags]

Flags:

phantom logs

View logs for an overlay or agent run.

phantom logs <overlay-name> [flags]

Flags:

phantom replay

Replay an agent run.

phantom replay <overlay-name>

Hooks

phantom hook

Manage post-run hooks.

phantom hook <overlay-name> [flags]

Subcommands:

• phantom hook add - Add a hook
• phantom hook list - List hooks
• phantom hook remove - Remove a hook
• phantom hook run - Run hooks manually

Hook Types:

• on-success - Run when agent succeeds
• on-failure - Run when agent fails
• on-complete - Run regardless of outcome

Examples:

# Add a post-run test hook
phantom hook add auth-feature --type on-success --command "npm test"

# Add a notification hook
phantom hook add auth-feature --type on-complete --command 'notify-send "Phantom" "Task complete"'

Snapshots & Export

phantom snapshot

Create a snapshot of an overlay’s current state.

phantom snapshot <overlay-name> [flags]

Flags:

phantom export

Export an overlay to a tarball.

phantom export <overlay-name> --output <path>

phantom clone

Clone an overlay to a new overlay.

phantom clone <source-overlay> --name <new-name>

Protection

phantom lock

Lock an overlay to prevent accidental cleanup.

phantom lock <overlay-name>

phantom unlock

Unlock an overlay.

phantom unlock <overlay-name>

phantom pin

Pin an overlay to prevent base drift (won’t sync with base).

phantom pin <overlay-name>

phantom unpin

Unpin an overlay.

phantom unpin <overlay-name>

Maintenance

phantom prune

Remove stopped overlays older than a threshold.

phantom prune [flags]

Flags:

phantom gc

Run garbage collection.

phantom gc [flags]

Flags:

phantom health

Check system health and dependencies.

phantom health

phantom rename

Rename an overlay.

phantom rename <old-name> <new-name>

Configuration

phantom config

View or edit configuration.

phantom config [flags]

Subcommands:

• phantom config get <key> - Get a config value
• phantom config set <key> <value> - Set a config value
• phantom config edit - Open config in editor
• phantom config path - Show config file path

phantom init

Initialize Phantom configuration.

phantom init [flags]

Flags:

phantom template

Generate template files for configuration.

phantom template <type> [flags]

Template Types:

• agents - Agents config file
• chain - Chain config file
• hooks - Hooks config file

Shell Completion

phantom completion

Generate shell completion script.

phantom completion <shell>

Supported Shells:

• bash
• zsh
• fish
• powershell

Global Flags

These flags are available for all commands: