Command reference

Every command here is meant to be typed by a human. The CLI has more subcommands than these, but the rest exist for the app and the background service to talk to each other and are deliberately left undocumented.

Pairing

Command	What it does
`onepilot pair`	Print a single use QR code that adds this server.
`onepilot pair --container NAME`	Pair a Docker container. Run it on the container's host.
`onepilot pair --clean`	Remove unused pairing codes.
`onepilot pair --clean-devices`	Remove device keys. Every paired phone must pair again.

Flags and the full walkthrough live in the pairing guide.

Sessions

These are the persistent shells that keep running after you disconnect. Normally the app drives them, but you can inspect and clear them from the host.

Command	What it does
`onepilot serve`	Start the daemon if it is not running, then print the port it is listening on. Safe to run repeatedly.
`onepilot list`	List the live session ids on this host.
`onepilot new`	Create a session and print its id.
`onepilot kill --session ID`	Terminate one session. The id is required.
`onepilot attach --session ID`	Attach the current terminal to a session. Mostly useful for debugging.

See what is running, then clear one

onepilot list
onepilot kill --session op-1a2b3c4d

Flags

Flag	Default	Applies to
`--port N`	24544	`serve`
`--session ID`	generated	`attach`, `new`, `kill`
`--cols N`	80	`attach`, `new`
`--rows N`	24	`attach`, `new`

If the preferred port is taken, the daemon walks upward until it finds a free one, so two hosts on the same machine will not fight over it.

Updating

Command	What it does
`onepilot upgrade`	Reinstall from npm and hand the running daemon over to the new binary in place.
`onepilot --version`	Print the installed version.

This is the only update command you need. See install and upgrade for what it prints and how Windows differs.

Kill switches

Two background behaviors can be turned off from the host, without the app and without uninstalling anything.

Host health reporting

This is what draws the graphs and sends the alerts. If you would rather the host reported nothing, turn it off here.

Command	What it does
`onepilot monitor status`	Show the current configuration, with the token redacted.
`onepilot monitor off`	Stop reporting. Keeps the configuration.
`onepilot monitor forget`	Delete the configuration entirely, including the webhook token and the rules.

Keeping the host awake

A laptop that sleeps is a laptop you cannot reach. This keeps the machine awake so it stays reachable, which you may not want on battery.

Command	What it does
`onepilot keepawake status`	Show whether it is on.
`onepilot keepawake on`	Keep this host awake.
`onepilot keepawake off`	Let it sleep normally.

Git credentials

Save a GitHub token on the host so pushes from a terminal or an agent work without a prompt. The token is read from stdin so it does not land in your shell history.

echo "$GITHUB_TOKEN" | onepilot github set-token

What is not documented

Running onepilot help will not show everything the binary accepts. The undocumented commands are internal: the background tunnel service entry point, the credential helper git calls on your behalf, the approval hook Claude Code invokes, and the update cache refresh. They exist to be called by software, take undocumented arguments, and can change between releases.