CLI reference

pando help prints every command, as below. Flags can go before or after a command’s other arguments. Commands that read the API take --json and print the API’s own JSON; see For scripts and agents. pando api reaches every route of the API.

Every command

usage: pando <command> [args]

  pando login [--server <url>] [--bootstrap | --with-credential]   sign this machine in (in the browser)
  pando logout [--server <url>]                                   sign this machine out
  pando auth status                                               who this machine is signed in as
  pando init [folder] [--name <name>] [--owner <org>] [--yes] [--dry-run]   make a Pando repo or monorepo from a folder
  pando clone <owner/name | name> [folder] [--text-only]         set up a Pando repo or monorepo on this machine
  pando worktree add <repo> <branch> [--issue n] | list | remove <path> | follow | mount   one branch, one folder
  pando branch list [--repo <path>] [--all]                       branches with ahead, behind and checks
  pando branch view [<branch>] [--commits]                        one branch: checks, merge, reviews, head commit
  pando diff [<branch>] [--json | --patch] [paths...]             the branch diff against main
  pando review [<branch>] [-m <comment>]                          review in Plannotator, or comment
  pando merge [<branch>] [--force]                                land a branch on main with a merge commit
  pando reference update <path> | sync                            move a reference to its newest commit
  pando status                                                    this folder, its worktrees and references
  pando status <pending|success|failure|error> [--context ci] [--target-url u] [--description d]
                                                                  in a CI build: a check on its commit (PANDO_STATUS_TOKEN)
  pando issue list [--state s] [--label l] [--assignee a] [--search w]   a monorepo's issues, newest first
  pando issue view <n> [--comments]                               one issue: its body, branches and timeline
  pando issue create --title t [--body b] [--label l] [--key k]   open an issue
  pando issue comment <n> --body b [--key k]                      comment on one
  pando issue close <n> [--reason not-planned] | reopen <n>       close or reopen one
  pando issue edit <n> [--title t] [--body b] [--base-version v]   edit, label, assign one
  pando issue link | unlink <n> [<branch>]                        merging the branch closes the issue
  pando issue react <n> <reaction> [--comment id] [--remove]      +1, -1, laugh, hooray, confused, heart, rocket, eyes
  pando monorepo list | view [<owner/name>]                       your monorepos; one with its repos and members
  pando monorepo rename <new-name>                                rename one (owners); the old name keeps working
  pando monorepo edit --description <text>                        its one line under the name on the web (owners)
  pando monorepo transfer <owner/name> <new-owner> [--yes]        move one to an org, or back to a person (owners)
  pando monorepo delete <owner/name> [--yes]                      delete one (owners)
  pando members list | invite <email> [--owner] | remove <who>    who belongs to a monorepo
  pando members invites | revoke <email>                          invites still waiting; withdraw one
  pando org create <login> [--name n] | list | view <org>         organizations: a namespace many people share
  pando org members [<org>] | add <org> <email | login> [--owner]   who is in one; add someone (owners)
  pando org remove <org> <login | email> | leave <org>            take someone out (owners), or leave
  pando mac broker [--dry-run]                                    load Pando.app's broker (before FSKit mounts)
  pando ci connect --org <slug> | status | disconnect --org <slug>   a monorepo's Buildkite connection [--monorepo <owner/name>]
  pando ci pipeline add <repo> <pipeline> | list | remove <repo> <pipeline>   the pipeline pushes and merges start
  pando ci build list [--pipeline p] [--branch b] [--state s]     builds, newest first
  pando ci build view | log | rebuild | cancel <build>            one build: its jobs, a job's log [--job j] [--follow]
  pando ci job retry <build> <job>                                run a job again
  pando ci run <pipeline> [--branch b]                            start a build of a branch (default: main)
  pando mirror status [--json]                                    mirroring to GitHub: on or paused, one row per project [--monorepo <owner/name>]
  pando mirror on | off [<project>]                               turn mirroring on or pause it, or one project's (owners)
  pando mirror retry [<project>...]                               try again now, with the wait reset (owners)
  pando mirror connect                                            set it up: opens the repository's Settings (GitHub needs a browser)
  pando release list | view [<tag>]                               a project's releases, newest first; one with its notes [--repo <path>]
  pando release create <tag> [--generate] [--title t] [--notes n] [--draft]   tag main and publish it (checks green, or --force)
  pando release create <tag> <file>...                            with files: a draft, its files, then published
  pando release upload <tag> <file>... | download [<tag>]         a release's files (checked by SHA-256) [--pattern p] [--dir d]
  pando release publish <tag> [--force] | delete <tag>            publish a draft; delete one (its tag stays)
  pando artifact add [<branch>] <file> [<image>...]               a document (and its images) on a branch's page; the same name again is v2
  pando artifact list [<branch>]                                  the branch's artifacts, their versions and open comments
  pando artifact get [<branch>] <name> [--version n] [-o dir]     download a version's files (checked by SHA-256)
  pando artifact open [<branch>] <name>                           its page in the browser
  pando artifact comments [<branch>] [<name>] [--all]             open threads: the quote, the comment, replies, ids
  pando artifact comment [<branch>] <name> [--quote words] -m c   comment on words, or on the whole file
  pando artifact reply <id> -m c | resolve <id> [--reopen]        answer a thread; resolve or reopen it
  pando credential create --name <sandbox> | list | revoke <id>   credentials that act as you
  pando hook list | create <url> | delete <id>                    a repo's web hooks [--repo <path>] (owners write)
  pando hook deliveries <id> | redeliver <delivery-id>            what a hook sent; send one again
  pando machine list                                              machines that acted in the monorepo, and which are connected
  pando profile [<login>] [--json]                                a person's profile: their graph for the last year, by month
  pando activity [--monorepo <owner/name> | --all] [--limit n]    what happened, newest first
  pando session enable | disable                                  record coding sessions on this machine, or stop
  pando session status                                            what this machine records, from where, and what it skips
  pando session paths [add <folder> --program <name> | remove <folder>]   where Claude Code, Codex, Pi or OpenCode keep sessions
  pando session exclude | include [<owner/name>] [--project <path>]   a repository or project you do not record, on every machine
  pando session delete <id> [--monorepo <owner/name>]             delete a session at once and for good
  pando api <path> [-X method] [-f k=v] [-F k=v] [--paginate]     any API call, signed as this machine (like gh api)
  pando sync [--once]                                             keep the monorepo's files outside projects/ live (the daemon)
  pando history <path> [--limit n] [--json]                       every saved version of a file outside projects/
  pando restore <path> --to <version | HH:MM>                     write an old version back, as a new save
  pando resolve [<path>...]                                       unfreeze a file after a conflict
  pando fetch <path>...                                           download large files outside projects/ kept as pointers

The CLI names a repository a monorepo in its own words: the pando monorepo command, the --monorepo flag and its help text. They mean the repository.

Sign in

pando login

pando login [--server <url>] [--bootstrap | --with-credential]

Signs this machine in. It shows a code and a link, opens your browser when it can, and waits for you to confirm. git and pando on this machine then act as you.

The credential is kept in ~/.pando/credentials/, readable only by you.

pando logout

pando logout [--server <url>]

Deletes this machine’s credential. The credential keeps working on the server until you revoke it with pando credential revoke.

pando auth status

pando auth status

Shows the server, where the credential comes from, this machine’s name, and who the server says you are. It takes --server <url> too.

Set up a repository

pando init

pando init [folder] [--name <name>] [--owner <org>] [--yes] [--dry-run]

Makes a Pando repository from a folder (default: the current folder), and you become its owner. A git repo becomes a plain repository. Any other folder becomes a repository with projects: each git repo under projects/ becomes one of its projects, other git repos inside it become references, and the rest of the folder becomes its shared files. Run it again after a failure: it skips what is done.

A name is lower-case letters, digits, ., _ and -, at most 39 characters, with no --.

pando clone

pando clone <owner/name | name> [folder] [--text-only]

Sets up a repository on this machine: the shared files outside projects/ and a read-only main for every project, each a git clone. References are cloned when you ask, with pando reference sync. The folder defaults to the name. A bare name means the one in your own account, else the only one so named that you belong to.

pando status

pando status

Run inside a repository: shows the server and your role, then each project with this machine’s worktrees (branch, kind, commit, changed files, unpushed commits) and each reference. With a state it posts a check instead; see pando status in a CI build.

Worktrees and branches

One branch, one folder. See Worktrees.

pando worktree

pando worktree add <repo> <branch> [--issue n] | list | remove <path> | follow | mount

pando branch list

pando branch list [--repo <path>] [--all]

Lists open branches with ahead, behind, author, checks, whether they merge cleanly, state and head.

pando branch view

pando branch view [<branch>] [--commits]

Shows one branch as its page does: its state and title, its head commit, who made it and the machine that last pushed it, how far it is ahead of and behind main, whether it merges cleanly (and, when not, the paths changed on both sides), each check, and its reviews. With no branch, the branch of the worktree you are in.

Review and merge

diff, review and merge take the branch of the worktree you are in when you name none.

pando diff

pando diff [<branch>] [--json | --patch] [paths...]

Shows the branch diff against main: the changes since the branch left main, as GitHub shows a pull request. Name paths to see only those.

pando review

pando review [<branch>] [-m <comment>]

With no -m, opens the branch diff in Plannotator (it must be installed). Approving there posts an approval; annotations post a request for changes. With -m, posts the comment with no Plannotator. Reviews are comments and approvals, not a gate on merging.

pando artifact

pando artifact add [<branch>] <file> [<image>...]
pando artifact list [<branch>]
pando artifact get [<branch>] <name> [--version n] [-o dir]
pando artifact open [<branch>] <name>
pando artifact comments [<branch>] [<name>] [--all]
pando artifact comment [<branch>] <name> [--quote "<words>"] -m "<comment>"
pando artifact reply <id> -m "<reply>"
pando artifact resolve <id> [--reopen]

Documents on a branch’s page, never in git: a plan, a diagram, a design, an exported guided review. add uploads the first file and the images it uses, kept by their paths from the document’s folder; the same name again is its next version. An agent reads the comments people leave with comments, uploads the next version with add, and answers with reply and resolve. With no branch, the branch of the worktree you are in. See Artifacts.

pando merge

pando merge [<branch>] [--force]

Lands the branch on main with a merge commit, and names the issues the merge closes (each closes about a second later). It stops when checks are not green, when the branch and main both changed a file in different ways (Pando merges whole files, with no line-by-line merge), or, run in the branch’s worktree, when the branch on the server is not what you pushed. This machine’s read-only main then follows within a moment.

Issues

A repository has one list of issues, numbered #1, #2, … An issue can be about one of its projects. A branch is linked to an issue by “Fixes #12” in its title, its description or one of its commits, or by pando issue link; merging the branch into main closes the issue.

pando issue

pando issue list [--state s] [--label l] [--assignee a] [--search w]
pando issue view <n> [--comments]
pando issue create --title t [--body b] [--label l] [--key k]
pando issue comment <n> --body b [--key k]
pando issue close <n> [--reason not-planned] | reopen <n>
pando issue edit <n> [--title t] [--body b] [--base-version v]
pando issue link | unlink <n> [<branch>]
pando issue react <n> <reaction> [--comment id] [--remove]

A number can be written 12 or #12.

Labels are made and changed by owners in the web’s Settings, or with pando api on /monorepos/{owner}/{monorepo}/labels.

A task, start to end:

n=$(pando issue create --title "Merge refuses when pando.toml has a trailing comma" \
      --body-file report.md --label bug --project projects/pando --key task-41 --json | jq .number)
pando worktree add projects/pando toml-error-line --issue "$n"
# work, commit, git push
pando merge          # This merge closes #41 (each within about a second).

References

pando reference

pando reference update <path> | sync

A reference is someone else’s repo inside the repository, kept as a pointer to one commit. See References.

--kind <kind> (sparse, the default, fuse or fskit) sets how a new reference folder is checked out.

Members, credentials and repositories

pando members

pando members list | invite <email> [--owner] | remove <who>
pando members invites | revoke <email>

Each subcommand takes the repository as owner/name before its other arguments, or uses the repository you are in.

pando credential

pando credential create --name <sandbox> | list | revoke <id>

Credentials that act as you, for another machine or a cloud sandbox.

git also runs pando credential as its credential helper for Pando URLs. You never run that part yourself.

pando monorepo

pando monorepo list | view [<owner/name>]
pando monorepo rename <new-name>
pando monorepo transfer <owner/name> <new-owner> [--yes]
pando monorepo delete <owner/name> [--yes]

Organizations

An organization is a namespace many people share, like a person’s login: its repositories are org/name. Everyone in it can open and push to every repository it owns; its owners own them all. People are added at once, or by email at their first sign-in.

pando org

pando org create <login> [--name n] | list | view <org>
pando org members [<org>] | add <org> <email | login> [--owner]
pando org remove <org> <login | email> | leave <org>

An organization’s display name (up to 100 characters), description (up to 160) and website (an https address, up to 2,048) are changed by its owners in the web, or with pando api: pando api -X PATCH /orgs/<org> -f description="...". Make a repository in one with pando init --owner <org>, or move one in with pando monorepo transfer.

CI

Pando starts builds on Buildkite and shows their checks. See CI with Buildkite.

pando ci

pando ci connect --org <slug> | status | disconnect --org <slug>
pando ci pipeline add <repo> <pipeline> | list | remove <repo> <pipeline>

pando ci build

pando ci build list [--pipeline p] [--branch b] [--state s]
pando ci build view | log | rebuild | cancel <build>

Builds as Pando has them from Buildkite’s webhooks, newest first. Name a build by its number (12 or #12, with --pipeline unless the repository has one pipeline), by its pipeline and number (pando-ci/12, as in its page’s address), or by its id (cib_...).

pando ci job retry

pando ci job retry <build> <job>

Runs a job again in Buildkite, with the build’s first environment, so it can still clone for 24 hours after the build started. Name the job by its key, name or id. Its check goes back to pending. It takes --pipeline, --monorepo and --json (the API’s answer).

pando ci run

pando ci run <pipeline> [--branch b]

Starts a build of the pipeline for the head of a branch as Pando has it (default: its project’s main), with fresh tokens, the way a push starts one. It takes --monorepo and --json (the API’s answer).

pando status in a CI build

pando status <pending|success|failure|error> [--context ci] [--target-url u] [--description d]

Only in a build Pando started. Posts a check on the build’s commit, using PANDO_STATUS_URL and PANDO_STATUS_TOKEN from the build’s environment. Pando shows the CI service’s mark on the check.

Releases

A release is a tag on a project’s main, with notes and files. See Releases.

pando release

pando release list | view [<tag>]
pando release create <tag> [<file>...] [--generate] [--title t] [--notes n | --notes-file f] [--target <sha>] [--draft] [--force]
pando release publish <tag> [--force]
pando release upload <tag> <file>...
pando release download [<tag>] [--pattern p] [--dir d]
pando release delete <tag> [--yes]

Hooks

pando hook

pando hook list | create <url> | delete <id>
pando hook deliveries <id> | redeliver <delivery-id>

A repo’s web hooks: on a push, a new branch or a merge, Pando POSTs JSON to a URL, signed with a secret you choose (X-Pando-Signature-256). Buildkite hooks are added with pando ci pipeline add and show in the list too. Adding, deleting and sending again need an owner.

Machines and activity

pando worktree list shows every worktree on every machine.

pando machine list

pando machine list

Each machine (a credential: a laptop, a cloud sandbox) that acted in the repository or is connected to it, latest activity first: whose it is, its kind, whether it is connected now and since when, how many worktrees it has open, and its last action. It takes --monorepo and --json (the API’s answer).

pando activity

pando activity [--monorepo <owner/name> | --all] [--limit n]

What happened, newest first, one line each, as the home page shows it: pushes, new and deleted branches, merges, reviews, checks that changed, worktrees added and removed, and shared files saved. Inside a repository’s folder, that repository’s lines; elsewhere, or with --all, those of every repository you belong to.

pando profile

pando profile [<login>] [--json]

A person’s profile, yours by default: their name, bio and links, their contribution graph for the last year drawn in the terminal (a column a week, Sunday on top, · for a day with nothing and ░▒▓█ for busier days), then each month in a line. You see only their work in repositories you can open. --json prints the API’s answer.

The API

pando api

pando api <path> [-X method] [-f k=v] [-F k=v] [--paginate]

Calls any route of the API with this machine’s credential, like gh api, and prints the answer: indented on a terminal, on one line in a pipe. The path may leave out /v1. In the path, {owner} and {monorepo} stand for the repository you are in (or --monorepo), {repo} for the project you are in (or --repo), and {branch} for the branch of the worktree you are in.

pando api /monorepos/{owner}/{monorepo}/repos/{repo}/branches --paginate
pando api /monorepos/{owner}/{monorepo}/repos/{repo}/branches -f name=fix-login -f title="Fix the login page"
pando api -X PATCH /monorepos/{owner}/{monorepo}/repos/{repo}/branches/{branch} --input body.json

It exits 0 on a 2xx or 3xx answer; a 3xx with no body (an artifact’s download) prints where it leads. Any other answer puts the API’s error body on stderr and exits 1. A full URL is refused: the credential goes only to the server you signed in to. There is no --jq; pipe the output to jq.

For scripts and agents

• --json is the API’s JSON. Each command above links the answer it prints, and the API reference holds every field. A few commands put several answers together under fixed keys: branch view (branch, reviews, commits), monorepo view (monorepo, repos, members), issue view --comments (the issue, with its timeline under timeline), and ci build log (an array, one answer per job). A list read in several pages comes out as one answer, the lists end to end. On a terminal the JSON is indented; in a pipe it is one line.
• Exit codes. 0 when the command worked. 1 when it did not, with one line on stderr that says why and ends with the API’s code and HTTP status, as in pando: no pipeline nope here (not_found, HTTP 404); pando issue with --json prints the API’s error object there instead. 2 when the command was used wrongly, with its usage.
• Running a write again. Only issues and comments take an idempotency key: pando issue create and pando issue comment always send one (--key, else one made for the run), and try again with it after a network error or a 502, 503 or 504, so a lost answer never makes a second issue. An agent that may run the command again after a crash passes its own stable --key, such as its task id. The rest of the API takes none, so another write retried after a lost answer may happen twice. These are safe to run again; a second run changes nothing (a delete or revoke already done answers not_found): every other pando issue subcommand (states, labels, assignees, links and reactions are set, not added twice; a body edit with --base-version is refused, not repeated), pando hook create and pando ci pipeline add (they look first, and add nothing when it is there), pando monorepo rename and transfer, pando org create, add, remove and leave, pando members invite, revoke and remove, pando hook delete, pando ci build cancel and pando merge. These are not: pando ci run and pando ci build rebuild start another build (look with pando ci build list --branch <b> first); pando review -m posts another review; pando credential create makes another credential; pando hook redeliver sends again (the receiver sees the same X-Pando-Delivery id and can drop it). pando ci job retry with a job’s key retries that job’s newest run, so once a first retry has finished, a second runs it again; name the job by its id to retry it once.

Shared files

A repository’s shared files are every file outside projects/ and outside references: notes, decisions, plans. They are plain files on every machine. While pando sync runs, a save on one machine goes to the others as soon as it is made, and becomes a git commit after 10 seconds without changes.

Each of these commands takes --root <folder> for a repository in another folder than the one you are in.

pando sync

pando sync [--once]

Keeps the shared files live until stopped: it sends this machine’s saves and writes everyone else’s. It also keeps this machine’s read-only mains at the server’s main. --once sends and receives what is waiting, then exits.

If you lose access to the repository (an owner removes you, you leave the organization that owns it, or it moves out of that organization), pando sync stops at once and says so. The folder keeps its files.

pando history

pando history <path> [--limit n] [--json]

Every saved version of a shared file, newest first: version, when, who, machine, what, and the commit.

pando restore

pando restore <path> --to <version | HH:MM>

Writes an old version back as a new save, which every machine gets. --to takes a version number, a time today (10:42), or a date and time (2026-10-03 10:42). A time means the latest version at or before it.

pando resolve

pando resolve [<path>...]

When two machines change a file at once, one keeps a conflict copy beside it and the file stops syncing there. pando resolve <path> makes it sync again: if you edited the file, your version goes out. With no path, it lists the files that are stopped.

pando fetch

pando fetch <path>...

Downloads the bytes of large shared files that a --text-only clone keeps as pointers. See Limits for file sizes.

The Mac

pando mac broker

pando mac broker [--dry-run]

macOS only. Loads Pando.app’s background helper, which a worktree mounted through Pando.app (--kind fskit) needs. The first mount runs this step on its own.

Environment

Pando sets these in a build it starts: