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. <base-path> can be a directory path or a registered project.

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. <base-path> can be a directory path or a registered project.

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. <base-path> can be a directory path or a registered project.

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. <base-path> can be a directory path or a registered project.

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 and calculate a Merge Confidence Score.

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

This command identifies files modified by more than one overlay. For Git-tracked repositories, it simulates a 3-way merge to distinguish between Clean Merges (different locations in the same file) and Hard Conflicts (overlapping changes).

The final Merge Confidence Score (0-100%) indicates how safely these overlays can be merged. In non-Git environments, any file overlap is considered an unresolvable hard conflict.

Flags:

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.

[!IMPORTANT] Path Protection (Blast Radius Control): If a .phantomignore file exists in the repository root, phantom apply will validate that no protected files or directories have been modified in the overlay. If any violation is found, the apply operation is rejected.

phantom apply <overlay-name> [flags]

Flags:

phantom revert

Revert a file or directory in an overlay to its base state. This removes any modifications, additions, or deletions made in the overlay for that specific path.

# Revert a modified config file in an overlay
phantom revert <overlay-name> config/database.yml

# Revert an entire directory
phantom revert <overlay-name> src/components/

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 project

Manage registered projects. This allows using a short project name instead of absolute directory paths for any command that accepts a base directory.

phantom project add myapp /path/to/my/app
phantom project list
phantom project remove myapp

# Use the short name 'myapp' instead of a full path
phantom start myapp -n my-feature
phantom run myapp -a aider -t "fix bug"

Subcommands:

• phantom project add <name> <path> - Register a new project and map its base directory path
• phantom project list - List all registered projects and their paths
• phantom project remove <name> - Delete a project mapping

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: