Quick Start

Go from zero to automated commits in under 5 minutes.

Quick Start Guide

This guide walks you through setting up Autopilot CLI in a new project and demonstrates its core functionality, end to end.

1. Set up a project

First, create a new directory and initialize a git repository. Autopilot can do this for you automatically during autopilot init if it doesn't find a repo, but it's worth knowing what's happening under the hood.

mkdir my-new-project
cd my-new-project
git init

2. Initialize Autopilot

Run the initialization command to generate the default configuration file:

autopilot init

This creates a .autopilotrc.json file in your project root. You can inspect it, but the defaults are fine for now.

3. Connect a remote repository

Autopilot pushes to a remote, so it needs one to push to. If you already have a GitHub (or similar) repository, connect it:

git remote add origin https://github.com/your-username/my-new-project.git

Skipping this step? That's fine — Autopilot will still watch and commit locally, it just won't have anywhere to push to. It logs [INFO] No remote configured — committing locally only instead of failing, so nothing breaks. Add a remote later with the same command whenever you're ready.

4. Recommended workflow: use a dev branch

By default, Autopilot is configured not to push to protected branches like main or master, as a safety measure. We strongly recommend working on a feature or development branch instead.

Create and switch to a new branch:

git checkout -b develop

5. (Optional) Enable AI commit messages

By default, Autopilot writes commit messages from a template. If you'd rather have them generated for you:

autopilot config set ai.enabled true

You'll be prompted for a free OpenRouter API key the first time this runs. Autopilot picks a working free model on its own — there's nothing further to configure.

6. Start the watcher

Now start the background daemon. This spawns a separate process that watches your files:

autopilot start

You should see a message confirming that the watcher has started.

7. Make some changes

Now for the magic. Create a new file or modify an existing one:

echo "Hello Autopilot" > README.md

Wait a few seconds — the default debounce period is 20 seconds. Autopilot will detect the change, stage it, create a commit message (a conventional-commit style message like docs: update README.md if AI is enabled, or a template-based one otherwise), and push it to your remote develop branch, if one is configured.

8. Monitor status

Check what the daemon is doing at any time:

autopilot status

This reports whether the service is running, stopped, paused, or has encountered an error.

9. Stop the watcher

When you're finished coding for the session, stop the background process:

autopilot stop

Viewing logs

If something isn't working as expected, check the logs. Autopilot writes them to the .autopilot directory in your project root (this directory is added to .gitignore automatically during init).

macOS / Linux / Git Bash:

cat .autopilot/autopilot.log

Windows (PowerShell or cmd.exe):

type .autopilot\autopilot.log

Common log entries:

Next steps

• CLI Reference — the full list of commands and flags.
• Configuration — customize debounce timers, ignored files, and presets.
• Troubleshooting — common issues and how to resolve them.