CLI reference

Run palmtop --help for the same list. Commands start the daemon when it isn’t running.

Daemon and setup

Command	What it does
palmtop status	Daemon, relay, project, connected devices and session. Shows “Update available”.
palmtop pair	Pairs a device with this computer: QR code in the terminal and in the browser
palmtop serve	Runs the daemon in the foreground
palmtop stop	Stops the daemon
palmtop update	Installs the latest palmtop, updates the skill and restarts the daemon
palmtop version	Version and build (also --version)
palmtop config name [name]	Shows or sets the name of this computer on your devices
palmtop config name --reset	Goes back to the host name
palmtop install	Claude Code: installs the skill and allows palmtop commands
palmtop guide	Prints the instructions for AI agents

Sessions and projects

Command	What it does
palmtop session start [title]	Starts a session and prints its 6-character ref
palmtop session list	Sessions of the project
palmtop session title <title>	Renames the session
palmtop sessions	Sessions of every project on this computer
palmtop sessions delete <ref>	Deletes a session everywhere, with its checklists
palmtop projects	Projects on this computer
palmtop projects remove <name|path>	Removes a project with its sessions, on the computer and on your devices

Deleting asks for confirmation in a terminal; without a terminal pass --yes.

Checklists (need --session)

Command	What it does
palmtop checklist create <title> --item <text>...	Creates a checklist with its items
palmtop checklist rename <ref> <title>	Renames a checklist
palmtop checklist remove <ref>	Removes a checklist
palmtop add <text> [--checklist <ref>]	Adds an item (default: latest checklist)
palmtop edit <ref> <text>	Changes the text of an item (clears its review)
palmtop remove <ref>	Removes an item
palmtop show	Checklists with review status and notes
palmtop message <text>	Shows a message at the top of the session
palmtop message --clear	Removes the message
palmtop feedback	Reviews changed since the last feedback, and items not reviewed yet

A text starting with - works after --item; as a positional argument put -- before it: palmtop add --session k3m9qz -- "--dry-run flag".

Options

Option	Meaning
--session <ref>	Session ref printed by session start (default: $PALMTOP_SESSION_ID)
--project <path>	Project directory (default: current directory)
--json	JSON output
-y, --yes	Delete without asking for confirmation
-h, --help	Help

Refs accept a prefix of at least 4 characters. Exit codes: 0 ok, 1 error, 2 wrong usage.

Environment

Variable	Meaning
PALMTOP_SESSION_ID	Default for --session
PALMTOP_HOME	Data directory instead of ~/.palmtopai

Use the same values in every terminal: the daemon started automatically inherits the environment of the first command.