Skip to content
Skip to content
PilotPods

Reference

Every PilotPods command

The CLI is the source of truth. Every command has its own --help. This page groups them with real flags and examples.

Get startedRead the docs
pilotpods
$

Overview

At a glance

This page covers 21 of the 26 top level commands, in five groups. Most take --instance NAME. Without it, PilotPods uses the last instance you chose with instances use, else default. Also available: approvals, budget, launchd and task. Run ./pilotpods --help for the full list.

21

commands covered

5

groups

--help

on every command

0

outbound calls (verify-isolation)

Setup

init, instances, status, doctor, ui, service, demo and upgrade get an instance running and visible.

initinstancesstatusdoctorui

Pods and people

pod, hire, checkin and session manage who works where.

podhirecheckinsession

Engines

Detect and configure claude, codex, antigravity, gemini and grokbot.

engines listengines detectengines enableengines setengines test

Safety and spend

stop --all, spend, audit, cleanup and verify-isolation keep you in control.

stopspendauditcleanupverify-isolation

Backup: backup, backup-list and restore archive an instance and bring it back, with a dry run first.

Anatomy of a command

./pilotpods is the the CLI.

Reference

Commands by group

Pick a group. Each card shows usage, the flags that matter and a command you can copy.

Setup. Create instances, check health and open the console.

init

Create or re-open a named instance.

pilotpods init [--instance NAME] [--data-dir DIR] [--mission TEXT]

--data-dir
Override this instance's data directory.
--mission
One line mission statement for the plan file.
Example
$ ./pilotpods init --instance project-a --mission "Ship the weekly report"

instances

Manage named instances: list, status, start, stop, remove, use.

pilotpods instances {list,status,start,stop,remove,use}

use
Make an instance the default for later commands.
remove --keep-data
Unregister only; never touch the data directory.
remove --yes
Skip the typed name confirmation and delete data.
Example
$ ./pilotpods instances list$ ./pilotpods instances use project-a

status

Bus health summary for one instance.

pilotpods status [--instance NAME]

--instance
Named instance (default: last used, else default).
Example
$ ./pilotpods status --instance project-a

doctor

Service health check.

pilotpods doctor [--instance NAME] [--selftest]

--selftest
Run the real self_test.py suite.
Example
$ ./pilotpods doctor --selftest

ui

Serve the web console and its API on 127.0.0.1.

pilotpods ui [--port PORT] [--open] [--dev-origin ORIGIN]

--port
Port (default: this instance's first port).
--open
Open the console in your default browser.
--dev-origin
Extra allowed Origin, for a Vite dev server.
Example
$ ./pilotpods ui --instance project-a --open

service

Run or list background services (launchd calls this).

pilotpods service {run,list}

run NAME
Run one service loop until STOP ALL is pressed.
run --once
Run a single pass and exit.
list
List services and their last heartbeat.
Example
$ ./pilotpods service list

demo

Seed a few clearly labelled demo members and pods.

pilotpods demo [--force]

--force
Reseed even if demo data already exists.
Example
$ ./pilotpods demo --instance project-a

upgrade

Apply any pending schema migrations to one instance's database.

pilotpods upgrade [--instance NAME]

--instance
Named instance to migrate.
Example
$ ./pilotpods upgrade --instance project-a

Recipes

Three common sequences

Real commands, in order. Replace project-a with your instance name.

Step 1 of 3

First run

Create an instance, check it, open the console.

Terminal
$ ./pilotpods init --instance project-a$ ./pilotpods engines detect --instance project-a$ ./pilotpods doctor --instance project-a$ ./pilotpods ui --instance project-a --open
Step 2 of 3

Add a pod

Create a pod, hire a COS into it, log a check-in.

Terminal
$ ./pilotpods pod create "Research pod" --instance project-a$ ./pilotpods hire analyst --pod 1 --instance project-a$ ./pilotpods checkin list --instance project-a
Step 3 of 3

Back up and stop

Archive first, then use the kill switch if you need to.

Terminal
$ ./pilotpods backup --instance project-a$ ./pilotpods stop --all --instance project-a

Good to know

Command questions

Run ./pilotpods --help for the list, then ./pilotpods <command> --help, and for nested ones ./pilotpods <command> <subcommand> --help.

Still unsure? Ask the CLI

Help text is generated by the same code that runs the command, so it never drifts from what the CLI really does.

Terminal
$ ./pilotpods --help$ ./pilotpods pod --help$ ./pilotpods engines test --help

Run your first pod in minutes

Install on a Mac, create an instance, and open the console. Everything stays on your machine.

Get started Read the docs
  • MIT licence
  • No telemetry
  • CLI and console
Quick start
$ ./install.sh$ ./pilotpods init --instance default$ ./pilotpods ui --open