CLI Reference

Complete reference for all Autopilot CLI commands.

CLI Reference

Autopilot CLI exposes a set of commands to manage the background watcher process, check system health, and analyze productivity. This page documents every command, its options, and what it does under the hood.

Requirements: Node.js 18+, Git installed and on your PATH. Windows, macOS, and Linux are all supported — see Windows notes for platform-specific behavior.

Global options

These flags work across most commands, not just the one they're listed under:

Flag	Description
`--json`	Return structured JSON output instead of formatted text. Supported by `status`, `doctor`, `start`, `config`, and `insights`. Useful for scripting or editor integrations (e.g. the VS Code extension).
`--help`	Show help for the command.
`--version`	Print the installed Autopilot version.

`autopilot init`

Initializes Autopilot in the current directory.

Syntax:

autopilot init [options]

Options:

Flag	Description
`--team`	Initialize with team collaboration settings (pull-before-push, secret scanning).
`--ai`	Enable AI-generated commit messages via OpenRouter. Prompts for a free API key if one isn't already configured — no model selection needed, Autopilot picks a free model automatically.

What it does:

Checks whether the current directory is a git repository. If not, and the folder is empty or new, offers to run git init for you.
Creates a .autopilotrc.json configuration file with default settings.
Adds .autopilot/ to your .gitignore to keep local logs out of version control.
If --ai is passed, walks you through connecting an OpenRouter API key.
If --team is passed, applies the safe-team preset (see autopilot preset).

Example:

cd my-project
autopilot init --ai

`autopilot start`

Starts the file watcher.

Syntax:

autopilot start [options]

Options:

Flag	Description
`--background`	Run the watcher as a detached background process instead of holding the terminal in the foreground.
`--json`	Print machine-readable startup status.

What it does:

Monitors the current directory and subdirectories for file changes using chokidar.
Respects .gitignore and .autopilotignore rules.
Waits for the configured debounce period (default 20s), then stages, commits, and — if enabled — pushes changes.

Example output:

🚀 Starting Autopilot watcher…
Logs: ./autopilot.log
Press Ctrl+C to stop, or run "autopilot stop" in another terminal.

`autopilot stop`

Stops the running Autopilot daemon for the current project.

Syntax:

autopilot stop

What it does:

Reads the process ID from .autopilot/autopilot.pid.
Sends a termination signal to that process.
Removes the PID file.

Windows note: see Windows notes — process termination is handled differently than on macOS/Linux, but the command behaves the same from your perspective.

`autopilot status`

Checks whether the Autopilot daemon is running.

Syntax:

autopilot status [--json]

Output:

Reports whether the watcher is Running, Stopped, or Paused, along with its process ID and the active log file path.

`autopilot pause`

Temporarily pauses the watcher without stopping the process.

Syntax:

autopilot pause [reason]

Example:

autopilot pause "Refactoring large file"

Use case: performing a large refactor, rebase, or merge where you don't want intermediate auto-commits interrupting the process.

`autopilot resume`

Resumes a paused watcher.

Syntax:

autopilot resume

`autopilot undo`

Safely reverts the most recent commit made by Autopilot.

Syntax:

autopilot undo

What it does:

Verifies the last commit was made by Autopilot (checks the [autopilot] marker or commit author).
Runs git reset --soft HEAD~1.
Keeps your file changes staged, so nothing is lost — only the commit itself is undone.

Autopilot will refuse to undo a commit it didn't make, to avoid accidentally reverting your own manual work.

`autopilot preset`

Applies a pre-configured workflow to .autopilotrc.json.

Syntax:

autopilot preset [name]

Available presets:

Preset	Behavior
`safe-team`	Enables pull-before-push, secret scanning, and lint checks before committing.
`solo-speed`	Disables non-essential checks for fastest possible commit cycles.
`strict-ci`	Requires tests and lint to pass before any commit is created.

Example:

autopilot preset safe-team

Each preset is just a named set of values written into .autopilotrc.json — see Configuration for the full list of individual settings if you'd rather configure by hand.

`autopilot config`

Reads or writes individual configuration values without hand-editing .autopilotrc.json.

Syntax:

autopilot config get <key>
autopilot config set <key> <value>
autopilot config list [--json]

Examples:

autopilot config set ai.enabled true
autopilot config set debounceSeconds 30
autopilot config list

`autopilot doctor`

Diagnoses environment and configuration issues.

Syntax:

autopilot doctor [--json]

Checks:

Node.js version compatibility
Git installation and authentication
File and directory permissions
.autopilotrc.json validity
AI provider connectivity (if AI is enabled)

Example output:

✔ Node.js v20.11.0 (compatible)
✔ Git installed and authenticated
✔ .autopilotrc.json valid
✖ AI provider unreachable — check your OpenRouter API key

Run this first whenever something isn't behaving as expected — it's the fastest way to isolate the problem.

`autopilot dashboard`

Opens a live, real-time view of watcher activity.

Syntax:

autopilot dashboard

What it does:

Launches an interactive terminal UI showing current status, active branch, pending changes, and a rolling log of recent commits and pushes. Read-only — it doesn't affect the watcher itself and can be safely closed at any time.

`autopilot insights`

Displays productivity analytics for the current project.

Syntax:

autopilot insights [--export csv|json]

Options:

Flag	Description
`--export csv`	Writes the underlying data to `autopilot-insights.csv` in the project root, for use in a spreadsheet or external analytics tool.
`--export json`	Writes the same data to `autopilot-insights.json` in the project root for dashboards, scripts, or CI artifacts.

Includes:

Commit quality score — a rough measure of how descriptive and well-scoped your commits are.
Productivity metrics — peak coding hours and active streaks.

`autopilot leaderboard`

Interacts with the optional global Autopilot leaderboard.

Syntax:

autopilot leaderboard [--sync]

Options:

Flag	Description
`--sync`	Pushes your local productivity stats (focus time, streaks, score) to the global leaderboard.
(none)	Opens the leaderboard in your default browser.

Example:

# Sync your latest stats
autopilot leaderboard --sync

# View rankings
autopilot leaderboard

Participation is opt-in and off by default. Only anonymized metrics are synced — no code or file contents ever leave your machine for this feature. See AI & Privacy for the full data policy.

Exit codes

Autopilot uses standardized exit codes so scripts and CI pipelines can react programmatically:

Code	Meaning
`0`	Success / watcher running
`1`	General error (runtime failure)
`2`	Not a git repository
`3`	Not initialized (`autopilot init` not yet run)
`4`	Blocked branch (push attempted to a protected branch)
`5`	Invalid configuration
`6`	Watcher already running
`7`	Watcher not running

Windows notes

Autopilot is fully supported on Windows, with two behavioral differences worth knowing:

Process signals: Windows doesn't support POSIX signals like SIGTERM natively. autopilot stop uses an equivalent Windows-safe termination method — you don't need to do anything differently, but if you're scripting around the daemon directly, don't assume SIGTERM semantics.
Paths: Use forward slashes (/) in .autopilotignore — they're normalized automatically, but backslash-only paths can behave inconsistently across shells (PowerShell vs. Git Bash vs. cmd.exe).

If anything looks wrong, autopilot doctor checks Windows-specific conditions (like whether Git is on your PATH) as part of its standard checks.