@pipod/cli 0.1.6 → 0.1.8

package/man/pipod.1

@@ -0,0 +1,865 @@
+.TH "PIPOD" "1" "October 2026" "0.1.8"
+.SH "NAME"
+\fBpipod\fR \- run pi coding\-agent sessions in server\-managed pods
+.SH SYNOPSIS
+.RS 2
+.nf
+Usage:
+  pipod [options]                   launch a pod for this project and start pi
+  pipod [options] \-\- <pi args…>     launch and pass arguments to pi: prompt words,
+                                    \-\-model <id>, \-\-thinking <level>, \-\-tui\-mode <mode>,
+                                    \-e/\-\-extension <path>, \-\-skill <path>,
+                                    \-\-prompt\-template <path> (each repeatable)
+  pipod <command> [options]         run a command
+  pipod help [command|topic]        print the full manual entry
+
+Sign in first with `pipod login`\. A pod\-scoped PI_POD_SERVER_TOKEN also counts as
+signed in\. While signed out, only login, whoami, init, doctor, update, help, and
+version are available\.
+
+Pod commands:
+  list [pod]             List pods; `list <pod>` shows one machine's group (ls)
+  attach [pod]           Reconnect to a pod session (a)
+  stop [pod…]            Stop pods now (files kept; attach restarts them)
+  fork <pod>             Launch a new pod forked from a pod's session
+  rename <pod> <name>    Rename a pod
+  send [pod] <path>      Copy host files into a pod
+  receive [pod] <path>   Copy pod files into the current directory
+  archive [pod…]         Hide pods from the list (files kept; restore brings them back)
+  restore [pod…]         Bring archived pods back
+  gc                     Report retention state; \-\-delete removes reclaimable pods
+
+Account commands:
+  login                  Sign in to a pi pod server via Zitadel
+  logout                 Revoke this session and delete the stored credentials
+  whoami                 Show the signed\-in account
+  account                Open the Zitadel self\-service console
+  org\-admin              Open the Zitadel Console for this organization
+  billing                Open Stripe Checkout or the billing portal (authenticated)
+  credentials            Connect account model\-provider sign\-ins
+
+Configuration commands:
+  init                   Scaffold \.pi\-pod/ config, env, env\.example, and init\.sh
+  templates              Manage account templates
+  push                   Upload a local config layer to its server bundle
+  pull                   Write a server bundle into its local config layer
+  diff                   Show local vs server drift for a config layer
+  secrets                Manage server and project secret scopes
+  settings               Show or edit one server settings config directly
+  jobs                   Manage server\-scheduled jobs
+
+Maintenance commands:
+  doctor                 Check auth, server, org, and launch\-resolution layers
+  update                 Upgrade pi pod itself
+
+Launch options:
+  \-\-template <name|id>   Launch from an account template
+  \-\-on <pod|self>        Co\-locate the new pod on an existing pod's machine
+  \-\-reuse                Restart this project's newest stopped pod instead of creating one
+  \-\-no\-seed              Start the pod with an empty workspace (skip workspace seeding)
+  \-\-dry\-run              Resolve and print the launch plan; create nothing
+
+General options:
+  \-y, \-\-yes              Skip supported confirmations
+  \-v, \-\-verbose          Debug logging (secrets redacted)
+  \-\-version              Print CLI, Node, and bundled Pi versions
+  \-h, \-\-help             Show help
+
+Topics (pipod help <topic>):
+  setup                  First\-time setup, in order, and who does each step
+  layers                 How org, user, and template settings combine
+  launch                 What a launch does: templates, workspace seeding, Pi resources
+  config                 Every config\.json key (man pipod\-config)
+  files                  Every file pipod reads or writes
+  environment            Environment variables
+
+`pipod <command> \-\-help` is a command's usage; `pipod help <command>` is its full
+manual entry; `man pipod` is the whole manual\.
+.fi
+.RE
+.SH DESCRIPTION
+.P
+pi pod runs pi sessions in pods: sandboxes on a pi pod server, which you attach to from a
+terminal or the phone apps and leave running when you detach\. You use one server, as a
+member of one organization on it\.
+.P
+What a pod starts with is decided on the server, from settings layers: the organization's
+defaults, your own defaults, and a template, which is the environment for one project\. Each
+layer holds pod config (pipod\-config(5)), an init script that runs in every pod at launch, a
+bake script that is built into the pod image once, and Pi files\. Secrets are stored apart from
+the layers and reach pods as environment variables\. \fBpipod help layers\fP explains how they
+combine\.
+.P
+Every server layer has a local source of truth: a directory you edit with any editor, then
+upload with \fBpipod push\fP\|\. \fBpipod pull\fP writes the server's copy back, and \fBpipod diff\fP
+compares the two\.
+.SH SETUP
+.P
+Setting pi pod up for yourself or an organization, in order\. A person has to do the steps
+marked (person): each needs a browser, a hidden prompt, or a decision about access or money\.
+An agent can do the rest with the commands shown, but should show the person every change
+before applying it\.
+.SS 1\. A server and an account (person)
+.P
+On your own server, the host's owner installs it (docs/self\-host\.md in the pipod repository)
+and creates accounts with \fBselfhost/add\-user <email>\fP on the host, adding \fB\-\-owner\fP for
+someone who may change organization settings\. On a server someone else runs, ask its owner
+for an account\.
+.SS 2\. Install the CLI and sign in (person)
+.RS 2
+.nf
+npm install \-g @pipod/cli        # Node 22\.19 or later
+pipod login \-\-server <url>
+pipod doctor
+.fi
+.RE
+.P
+\fBlogin\fP opens a browser, or prints a code to confirm on another device\. \fBdoctor\fP checks the
+sign\-in, the server, your organization and roles, and what a launch here would resolve\.
+.SS 3\. Model providers (person)
+.P
+\fBpipod credentials connect\fP connects every provider your local pi is signed in to;
+\fBpipod credentials connect <provider>\fP signs in to one\. The sign\-ins belong to your account
+and apply to every pod you launch\.
+.SS 4\. Organization defaults
+.P
+Only with the org:manage permission (\fBpipod whoami\fP lists yours); otherwise skip to step 5\.
+These reach every member's next pod: pod size, network policy, a default model, tools baked
+into the image, shared setup\. Change one key with \fBpipod settings org set <key> <value>\fP, or
+the whole layer from its local source:
+.RS 2
+.nf
+pipod pull org                   # writes ~/\.pi\-pod/org/
+                                 # edit config\.json, init\.sh, bake\.sh, pi/
+pipod diff org
+pipod push org
+.fi
+.RE
+.P
+Values for secrets the whole organization shares: \fBpipod secrets set org <NAME>\fP (person)\.
+Organization policy (limits rather than defaults) is set in the web dashboard,
+\fB<server>/dashboard/\fP\|\.
+.SS 5\. Your own defaults
+.P
+Your model and thinking level, your Pi settings, personal setup such as a git identity:
+.RS 2
+.nf
+pipod settings user set pi\.model <provider>/<model>
+pipod settings user set pi\.thinking high
+.fi
+.RE
+.P
+or the whole layer: \fBpipod pull user\fP, edit ~/\.pi\-pod/config\.json and ~/\.pi/agent/, then
+\fBpipod diff user\fP and \fBpipod push user\fP\|\.
+.SS 6\. A template for each project
+.P
+In the project's directory:
+.RS 2
+.nf
+pipod init                       # writes \.pi\-pod/
+                                 # edit \.pi\-pod/config\.json, init\.sh, and bake\.sh
+pipod \-\-dry\-run                  # what a launch would resolve; creates nothing
+pipod                            # the first launch offers to create the template and pin it
+.fi
+.RE
+.P
+Without a launch, \fBpipod templates create <name> \-\-from\-here\fP creates it; then pin it by
+adding \fB&quot;template&quot;: &quot;<name>&quot;\fP to \.pi\-pod/config\.json\. Afterwards the project stays its
+source: edit the files, \fBpipod diff\fP, \fBpipod push\fP\|\. Its secret values:
+\fBpipod secrets set template/<name> <NAME>\fP (person), or \fB\|\.pi\-pod/env\fP on this machine\. To
+tell its pods' agents what access the template is meant to have:
+\fBpipod templates edit <name> \-\-agent\-instructions <file>\fP\|\.
+.SS Rules for an agent
+
+.RS 1
+.IP \(bu 2
+Never put a secret value on a command line or in a chat; transcripts are stored\. Name the
+secret and let the person type it into \fBpipod secrets set\fP\|\.
+.IP \(bu 2
+Run \fBpipod diff <layer>\fP before \fBpipod push <layer>\fP: a push replaces the whole layer\.
+With no terminal, push declines instead of asking, so show the person the diff, then run
+\fBpipod push <layer> \-\-yes\fP\|\.
+.IP \(bu 2
+Organization changes reach every member's next pod, and \fBpipod templates share\fP cannot be
+undone: confirm both with the person first\.
+.IP \(bu 2
+Iterate with \fBpipod doctor\fP and \fBpipod \-\-dry\-run\fP; both create nothing\.
+
+.RE
+.SH LAYERS
+.P
+Each launch is resolved on the server from these layers, lowest first:
+.RS 2
+.nf
+built\-in defaults
+organization defaults
+org\-wide template          (when the launch uses one)
+your user layer
+personal template          (when the launch uses one)
+organization policy        (limits, applied last)
+.fi
+.RE
+.P
+The template is the one the launch names: \fB\-\-template\fP, or the \fBtemplate\fP pinned in the
+project's \.pi\-pod/config\.json\. Within the layers:
+
+.RS 1
+.IP \(bu 2
+config merges key by key, and the later layer wins; an array replaces the one below it\.
+.IP \(bu 2
+init scripts all run, in layer order, and so do bake scripts\.
+.IP \(bu 2
+Pi files merge the same way, file by file, except that settings\.json package lists add
+up\. They hold no credentials: models\.json and mcporter\.json name a secret as \fB$NAME\fP,
+and the server refuses a literal key\.
+
+.RE
+.P
+Organization policy holds limits rather than defaults: maximum idle and archive times,
+allowed providers, a required template, network rules, concurrency\. It clamps the merged
+result, and \fBpipod doctor\fP and \fBpipod \-\-dry\-run\fP report every clamp\. It is set in the web
+dashboard by someone with the policy:write permission\.
+.P
+Where each layer's source lives, and the commands that change it:
+.RS 2
+.nf
+org        ~/\.pi\-pod/org/: config\.json, init\.sh, bake\.sh, pi/, env
+           pipod pull|diff|push org; pipod settings org set      (org:manage)
+user       ~/\.pi\-pod/config\.json and ~/\.pi/agent/
+           pipod pull|diff|push user; pipod settings user set
+template   a project: \.pi\-pod/config\.json, init\.sh, bake\.sh, env, and \.pi/
+           pipod pull|diff|push [template [<name>]]; pipod templates
+.fi
+.RE
+.P
+What belongs where: the organization layer holds what everyone needs (pod size, network
+policy, shared tools); your user layer holds your preferences (model, Pi settings, git
+identity); a template holds one project's environment (cloning and installing it, the hosts
+it needs, its secrets)\. A project's own files reach pods only through its template, after
+\fBpipod push\fP\|\. The web dashboard, \fB<server>/dashboard/\fP, edits the same layers\.
+.P
+Secrets have their own order, lowest first: org, user, template, then the project's
+\|\.pi\-pod/env on the machine you launch from\. \fBpipod secrets list\fP shows which layer each
+name comes from\.
+.SH LAUNCH
+.P
+\fBpipod\fP with no command launches a pod for the current directory and attaches to it\.
+\fBpipod \-\-dry\-run\fP resolves the same launch and prints it without creating anything\.
+.P
+The launch uses the template named by \fB\-\-template\fP, or else the one pinned in the project's
+\|\.pi\-pod/config\.json\. In a project with a \.pi\-pod/config\.json and no pinned template, the
+first launch offers to create a template from the project and pin it\.
+.P
+Workspace seeding: launching from a directory with no \.pi\-pod/config\.json seeds the new pod
+from that directory (its git repository root when inside one)\. A clean, pushed checkout whose
+remote tip matches HEAD is cloned at that exact commit; anything else (dirty trees, unpushed
+commits, private remotes without usable credentials, plain directories) is streamed in as a
+tar archive, without git\-ignored paths, node_modules, or \.pi\-pod/env\. Private\-remote
+credentials are forwarded only after a prompt (\fB\-\-yes\fP approves it) and are never stored\.
+\fB\-\-dry\-run\fP prints the decision without prompting or creating a pod\. Forks, reused pods,
+\fB\-\-on\fP co\-location, and \fB\-\-no\-seed\fP never seed\. A project with a \.pi\-pod/config\.json gets its
+workspace from its init scripts instead\.
+.P
+Arguments after \fB\-\-\fP go to pi: prompt words start the session, and \fB\-\-model\fP, \fB\-\-thinking\fP,
+and \fB\-\-tui\-mode\fP apply to this launch\. Per\-launch Pi resources (\fB\-\-extension\fP, \fB\-\-skill\fP,
+\fB\-\-prompt\-template\fP) name files or directories inside the pod as absolute paths and add to
+the pod's configured Pi resources for that launch; anything else Pi\-related belongs in the
+\fBpi\.args\fP config\.
+.P
+\fB\-\-reuse\fP restarts this project's newest stopped pod instead of creating one\. \fB\-\-on <pod>\fP
+starts the new pod on an existing pod's machine, sharing its files; \fB\-\-on self\fP does that
+from inside a pod\.
+.P
+Inside a pod, signed in with the pod's own token, every launch (\fB\-\-on self\fP included) and
+every job it schedules uses the template that pod launched from; the server refuses any other\.
+.SH COMMANDS
+.SS pipod login
+.RS 2
+.nf
+Usage: pipod login [\-\-server <url>] [\-\-issuer <url>] [\-\-org <alias>] [\-\-device] [\-\-token <jwt>]
+
+Sign this machine in to a pi pod server via Zitadel (authorization code + PKCE,
+in your browser)\. Where no browser can open here (over SSH, on a headless
+server), it prints a page and a code to confirm on any other device instead\.
+The session is stored in ~/\.pi\-pod/auth\.json\.
+
+Options:
+  \-\-server <url>   Server to sign in to (default: the previous session's server,
+                   $PI_POD_ACCOUNT_URL, or the production server)
+  \-\-issuer <url>   OIDC issuer (default: $PI_POD_ISSUER, else the one the
+                   server publishes); needed only for a server too old to
+                   publish its own
+  \-\-org <alias>    Only sign in to the organization with this primary domain;
+                   omit it to sign in to your own organization
+  \-\-device         Sign in with a code on another device even if a browser
+                   could open here
+  \-\-token <jwt>    Use an existing access token instead of the browser flow (dev/CI)
+.fi
+.RE
+.P
+A person finishes the sign\-in, in a browser or with the printed code; an agent can start
+\fBpipod login\fP and wait for it\. Signing in works before you belong to an organization, but
+then nothing is permitted and \fBlogin\fP says access is pending organization membership: the
+server's owner adds you (\fBselfhost/add\-user\fP on a self\-hosted host), or an organization owner
+grants you a role in the Zitadel Console (\fBpipod org\-admin\fP)\.
+.SS pipod logout
+.RS 2
+.nf
+Usage: pipod logout
+
+Revoke the current account session and delete ~/\.pi\-pod/auth\.json\. Pod
+operations are unavailable until the next `pipod login`\.
+.fi
+.RE
+.SS pipod whoami
+.RS 2
+.nf
+Usage: pipod whoami
+
+Show the signed\-in server, user, permissions, active organization, and console
+links\. Exits 1 when signed out\.
+.fi
+.RE
+.SS pipod account
+.RS 2
+.nf
+Usage: pipod account
+
+Open the Zitadel self\-service console in your browser to manage profile,
+password, MFA, and active sessions\.
+.fi
+.RE
+.SS pipod org\-admin
+.RS 2
+.nf
+Usage: pipod org\-admin
+
+Open the Zitadel Console in your browser\. Organization owners manage members
+and role grants there\.
+.fi
+.RE
+.SS pipod billing
+.RS 2
+.nf
+Usage: pipod billing checkout [\-\-plan standard|pro] [\-\-trial]
+       pipod billing portal
+       pipod billing change \-\-plan standard|pro [\-\-yes]
+       pipod billing change preview \-\-plan standard|pro
+       pipod billing change confirm \-\-quote <quoteId> [\-\-yes]
+
+Authenticated Stripe Checkout and billing portal\. Checkout sends trial:false
+(paid) unless \-\-trial\. Closed public trial refuses \-\-trial with 402\. Change
+previews a Standard<\->Pro plan change and confirms it only after an explicit
+yes; stale quotes are never auto\-confirmed\. Return
+pages do not grant a plan\.
+.fi
+.RE
+.P
+Billing exists only on the hosted service; a self\-hosted server has none\. Paying, and
+changing plans, are a person's decisions: an agent may run \fBpreview\fP, never \fBconfirm\fP\|\.
+.SS pipod credentials
+.RS 2
+.nf
+Usage: pipod credentials [action]
+
+Manage account\-scoped model\-provider sign\-ins\. Connected credentials apply to
+every pod you launch; OAuth refresh tokens stay in server custody and never
+reach pods or this machine\.
+
+Actions:
+  list                       Saved credentials and connectable providers (default)
+  connect                    Connect every provider your local pi is signed in to:
+                             API keys are imported, everything else is a fresh
+                             account login; ready credentials are left alone
+  connect <provider>         Sign in to a provider (OAuth by default)
+  reconnect <provider>       Redo the sign\-in for a saved credential
+  test <provider>            Verify a saved credential against the provider
+  remove <provider> [\-\-yes]  Delete a saved credential (alias: rm)
+
+connect options:
+  \-\-api\-key            Enter an API key instead of the OAuth flow
+  \-\-api\-key \-\-from\-pi  Import the API key your local pi resolves for that
+                       provider (auth\.json or env) instead of typing it\.
+                       OAuth grants are never imported\.
+.fi
+.RE
+.P
+\fBconnect\fP and \fBreconnect\fP need a person, for the browser sign\-in or the hidden key prompt;
+\fBlist\fP and \fBtest\fP do not\. A model\-provider key is a credential here, not a secret: a template
+refuses one\.
+.SS pipod init
+.RS 2
+.nf
+Usage: pipod init [\-\-force]
+
+Scaffold project configuration under \.pi\-pod/ in the current directory:
+config\.json, env\.example, env (mode 600), and init\.sh\.
+
+Options:
+  \-\-force                Overwrite scaffold files that already exist
+.fi
+.RE
+.P
+The files are the local source of the project's template\. config\.json starts with every
+setting commented out: uncomment only what this project must decide for itself
+(pipod\-config(5))\. init\.sh runs in each new pod, in an empty workspace, so it usually clones
+the repository and installs dependencies\. Add \.pi\-pod/bake\.sh for setup that belongs in the
+image\. env holds the project's secret values and is added to \.gitignore; env\.example lists
+their names and is committed\.
+.SS pipod templates
+.RS 2
+.nf
+Usage: pipod templates [action]
+
+Manage pod templates on the pi pod server\. A template stores config, init and
+bake scripts, Pi settings files, named secrets, and agent instructions\.
+Templates are personal by default: only their owner sees and launches them\.
+\-\-org at creation or `templates share` makes one org\-wide\.
+
+Agent instructions are added to the agent's system prompt in every pod launched
+from the template, with the hosts and secrets the pod actually has: say what
+access the template is meant to have\. They guide the agent and enforce nothing;
+the template's secrets and egress decide what a pod can reach\. A pod's child
+pods and the jobs it schedules launch from the pod's own template\.
+
+Actions:
+  list             List templates with scope and key counts (default)
+  show <name|id>   Show config, scripts, agent instructions, Pi settings, and
+                   secret names
+  create <name>    Create a template
+  edit <name|id>   Update a template's name, description, config, scripts, or
+                   agent instructions
+  share <name|id>  Make a personal template org\-wide (cannot be undone)
+  rm <name|id>     Delete a template (alias: delete)
+
+create/edit options:
+  \-\-name <name>         New name (edit only)
+  \-\-description <text>  Set the description
+  \-\-config <file>       Store this config file (same shape as \.pi\-pod/config\.json)
+  \-\-from\-here           create only: store this project's authored config,
+                        scripts, and sanitized Pi files (contradicts \-\-config)
+  \-\-init\-script <file>  Store this init script
+  \-\-bake\-script <file>  Store this bake script
+  \-\-agent\-instructions <file>
+                        Store this file as the agent instructions (an empty
+                        file removes them); `pipod push` leaves them alone
+  \-\-org                 create only: make the template org\-wide from the start
+  \-\-with\-secrets        With \-\-from\-here: also upload project env values as
+                        template secrets
+  \-y, \-\-yes             Skip confirmations (rm)
+.fi
+.RE
+.P
+A template is one project's environment\. Keep a project as its source: accept the first
+launch's offer, which creates the template and pins it in \.pi\-pod/config\.json, or run
+\fBcreate \-\-from\-here\fP and add \fB&quot;template&quot;: &quot;<name>&quot;\fP to that file yourself\. Then change it
+with \fBpipod diff\fP and \fBpipod push\fP from the project\.
+A personal template sits above your user layer and an org\-wide one below it
+(\fBpipod help layers\fP); making one org\-wide needs the org:manage permission\.
+.SS pipod push
+.RS 2
+.nf
+Usage: pipod push [template [<name>] | user | org] [\-\-dir <path>]
+                  [\-\-with\-secrets] [\-\-yes]
+
+Replace a server config bundle with its local source, whole\. The layer names
+both sides; edit the local files with any editor, then push\. A diff preview
+precedes the confirmation\.
+
+Layers and their local source:
+  template [<name>]  This project: \.pi\-pod/config\.json, its init and bake
+                     scripts, Pi files under \.pi/, and the project env file
+                     (secrets, with \-\-with\-secrets or a prompt)\. Without
+                     <name> the project's pinned template is used\.
+  user               ~/\.pi\-pod/config\.json and ~/\.pi/agent/ (settings\.json,
+                     models\.json, mcporter\.json, subagents\.json, agents/)
+  org                ~/\.pi\-pod/org/: config\.json, init\.sh, bake\.sh, pi/…, and
+                     an optional env file whose values become org secrets
+
+Inside a project the layer defaults to template; elsewhere it is required\.
+Provider credentials, hooks, mcpServers, and model credential values never
+leave this machine\.
+
+Options:
+  \-\-dir <path>     org only: read the org source from <path> instead
+  \-\-with\-secrets   Also upload the layer's env values as secrets
+  \-y, \-\-yes        Apply the replacement without the confirmation prompt
+.fi
+.RE
+.P
+Whatever the local source lacks is removed from the server layer, so start from
+\fBpipod pull\fP when the server may have changes this machine does not\. With no terminal to
+confirm on, push declines unless \fB\-\-yes\fP is given\.
+.SS pipod pull
+.RS 2
+.nf
+Usage: pipod pull [template [<name>] | user | org] [\-\-dir <path>] [\-\-yes]
+
+Write a server config bundle into its local source files (see
+`pipod push \-\-help` for the layer → directory table)\. A diff preview
+precedes the confirmation; nothing is written when the two already match\.
+
+What pull keeps from the local files:
+  config\.json    client\-only keys: $schema, template, secretResolver,
+                 pi\.chords, pi\.sessionNaming
+  settings\.json  hooks and mcpServers (and packages when hostConfig\.packages
+                 is off)
+  models\.json    credential values the push had dropped
+  agents/        files the bundle no longer contains are removed
+
+Secrets stay on the server; their names are listed\. The user layer has no
+local script files, so user bundle scripts are shown but not written\.
+
+Options:
+  \-\-dir <path>   org only: write the org source to <path> instead
+  \-y, \-\-yes      Apply the local changes without the confirmation prompt
+.fi
+.RE
+.SS pipod diff
+.RS 2
+.nf
+Usage: pipod diff [template [<name>] | user | org] [\-\-dir <path>]
+
+Compare a config layer's local source with its server bundle (see
+`pipod push \-\-help` for the layer → directory table)\. Secrets compare by
+name only\. Exits 1 when they differ, 0 when they match\.
+
+Options:
+  \-\-dir <path>   org only: read the org source from <path> instead
+.fi
+.RE
+.SS pipod secrets
+.RS 2
+.nf
+Usage: pipod secrets [action]
+
+Manage the secret layers pods see\. Requires account or pod\-token auth\. Server
+scopes are org, user, and template/<name>; project is this project's dotenv
+file, the highest\-precedence layer for launches from the project\.
+
+Actions:
+  list                          Every secret a pod launched here would see,
+                                which layer wins, and who set it (default)
+  set <scope> <NAME>            Store a secret, its value read from a hidden
+                                prompt or stdin (never the command line)
+  rm <scope> <NAME>             Remove a secret (aliases: remove, unset)
+  sync <scope>                  Upload a dotenv file to a server scope
+
+sync options (scope must be org, user, or template/<name>):
+  \-\-file <path>   Dotenv file to upload (default: ~/\.pi\-pod/secrets/<scope>\.env)
+  \-\-prune         Also delete server secrets that are not in the file
+  \-\-dry\-run       Show what would change without writing
+
+Values may be op:// references; they resolve just\-in\-time (at upload for
+server scopes, at launch for the project file) and the references themselves
+are never stored on the server\.
+.fi
+.RE
+.P
+Precedence, lowest first: org, user, template, project\. A pod receives its secrets as
+environment variables, and anything running in it can read them all\. Stored values cannot be
+read back, only replaced\.
+.P
+Keep values out of command lines and chats: a person types them at \fBset\fP\|'s hidden prompt,
+or \fBsync\fP reads a dotenv file kept at mode 600\. op:// references resolve through the
+1Password CLI (\fBop\fP) on this machine\. Model\-provider keys belong in \fBpipod credentials\fP\|\.
+.SS pipod settings
+.RS 2
+.nf
+Usage: pipod settings <user|org> [show | edit | set <key> <value> | unset <key>]
+
+Show or edit a persistent settings bundle on the server: your own user bundle,
+or the org\-wide defaults (org scope needs the org:manage permission)\. Edits
+change only the config; scripts and Pi files stay as they are — replace the
+whole bundle from local files with `pipod push user` or `pipod push org`\.
+Edits use compare\-and\-swap on the bundle version, so concurrent changes fail
+cleanly instead of overwriting each other\.
+
+Actions:
+  show                    Print the settings bundle as JSON (default)
+  edit                    Edit the config in $VISUAL/$EDITOR, then save
+  set <key> <value>       Set one dotted key to a JSON value, or to the text as
+                          a string: pipod settings user set pi\.model provider/model
+  unset <key>             Remove one dotted key, so the layers below decide it
+.fi
+.RE
+.P
+Keys are those of pipod\-config(5)\. \fBset\fP changes the server only: a later \fBpipod push\fP of the
+same layer replaces it with the local source, so after a \fBset\fP, run \fBpipod pull\fP before
+editing that source\.
+.SS pipod jobs
+.RS 2
+.nf
+Usage: pipod jobs [action] [args] [\-\-quiet] [\-\-yes] [\-\-project] [\-\-org]
+
+Manage scheduled jobs the pi pod server runs for you: at each trigger it
+launches a pod from the job's template and sends the job's prompt\. Local job
+files in \.pi\-pod/jobs/ (project) or ~/\.pi\-pod/jobs/ (user) are the reviewable
+source; `jobs push` promotes them to the server\. <job> is an id, short ref
+(j\-…), or name\.
+
+Actions:
+  list                 List server jobs (default)
+  show <job>           Show a job's schedule, template, model, and prompt
+  runs <job>           List a job's recent runs
+  run <job>            Run an active job once, now; its schedule is unchanged
+  activate <job>       Activate a job
+  pause <job>          Pause a job's schedule
+  resume <job>         Resume a paused job
+  rm <job>             Remove a job; its schedule stops firing
+  push [job…]          Create or update server jobs from local job files
+  pull <job>           Write a server job to a local job file
+  diff [job…]          Show local vs server drift; exits 1 when drifted
+
+Options:
+  \-\-org        push: create org\-scoped jobs or promote matching user jobs
+               (promotion is one\-way)
+  \-\-project    pull: write into this project's \.pi\-pod/jobs/ instead of
+               ~/\.pi\-pod/jobs/
+  \-q, \-\-quiet  list: print job ids only, one per line
+  \-y, \-\-yes    Skip confirmations; pull: overwrite an existing local file
+.fi
+.RE
+.P
+A job file is \fB<name>\.json\fP (comments allowed), and its file name is the job's name:
+.RS 2
+.nf
+{
+  "description": "Triage new issues every morning",
+  "trigger": { "type": "cron", "cron": "0 6 * * *" },
+  "template": "my\-service",
+  "model": "anthropic/claude\-opus\-4\-7",
+  "prompt": "Review yesterday's new issues and post a triage summary\."
+}
+.fi
+.RE
+.P
+\fBtrigger\fP is a cron expression, evaluated in UTC, or \fB{ &quot;type&quot;: &quot;at&quot;, &quot;times&quot;: [\.\.\.] }\fP with
+up to 100 ISO 8601 timestamps that each name their timezone\. Runs must be at least 5
+minutes apart, since each run is a pod\. \fBmodel\fP (provider/model\-id) is required\.
+\fBpromptFile\fP names a file beside the job file instead of \fBprompt\fP; prompts are at most 64 KiB
+and must say everything the run needs, since it starts in a fresh pod\. A job runs on its own
+until paused, so agree its schedule with the person before \fBpipod jobs push\fP\|\.
+.SS pipod list
+.RS 2
+.nf
+Usage: pipod list [pod] [\-\-all] [\-\-archived] [\-\-template <name|id>] [\-\-quiet]
+
+Alias: ls
+
+List pods on the signed\-in server with stable short refs (p\-…)\. The project is
+the directory's git repository (or the directory, or its \.pi\-pod/ config): a
+listing shows that project's pods when it has any — its pinned template's when
+it pins one — and every pod otherwise\. Co\-located pods are grouped under the pod
+whose machine they share, with an ON column naming it\.
+With a pod argument, show just that machine's group: the pod and everything
+co\-located on it\.
+
+Status says where a pod's files are: a stopped pod keeps them on disk and restarts on
+attach; an archived workspace is restored on next use, which takes longer the bigger it is\.
+Pods you archive stay hidden unless \-\-archived is passed\.
+
+Options:
+  \-a, \-\-all              Every pod; ignore the current project and its template pin
+  \-\-archived             Include logically archived pods
+  \-\-template <name|id>   Only pods launched from that template (whole account)
+  \-q, \-\-quiet            Print pod ids only, one per line
+.fi
+.RE
+.SS pipod attach
+.RS 2
+.nf
+Usage: pipod attach [pod] [\-\-yes] [\-\- <prompt…> [\-\-tui\-mode <mode>]]
+
+Alias: a
+
+Reconnect to a pod session through the server gateway\. Name the pod by id,
+short ref (p\-…), or name; omit it when this project has exactly one pod\.
+Quitting detaches: the pod keeps running until the server's idle policy reaps
+it or `pipod stop` stops it\. Raw pod shells are not available\.
+Attaching to an archived pod offers to restore it first\.
+
+After \-\-:
+  <prompt…>              Words are sent to the session as a startup prompt
+  \-\-tui\-mode <mode>      Local TUI layout for this attach: regular or fullscreen
+
+Options:
+  \-y, \-\-yes              Restore an archived pod without asking
+.fi
+.RE
+.SS pipod stop
+.RS 2
+.nf
+Usage: pipod stop [pod…]
+
+Stop pods now by id, short ref (p\-…), or name; omit the argument when this
+project has exactly one pod\. Stopped pods keep their files and `pipod attach`
+restarts them\. Stopping a pod that hosts co\-located pods stops those too\.
+.fi
+.RE
+.SS pipod fork
+.RS 2
+.nf
+Usage: pipod fork <pod> [\-\-session <path>] [launch options] [\-\- <pi args…>]
+
+Launch a new pod whose session starts as a fork of <pod>'s current session\.
+<pod> is an id, short ref (p\-…), or name\. The workspace is not copied —
+commit and push first if the new pod needs those changes\. \-\-on is not
+supported: a fork launches a new sandbox, not a co\-located pod\.
+
+Options:
+  \-\-session <path>       Fork a specific session file instead of the newest
+  \-\-template <name|id>   Launch the new pod from an account template
+  \-\-dry\-run              Resolve and print the launch plan; create nothing
+  \-y, \-\-yes              Skip supported confirmations
+.fi
+.RE
+.SS pipod rename
+.RS 2
+.nf
+Usage: pipod rename <pod> <name>
+
+Rename a server\-managed pod\. <pod> is an id, short ref (p\-…), or the current
+name\.
+.fi
+.RE
+.SS pipod send
+.RS 2
+.nf
+Usage: pipod send [pod] <path> [\-\-yes]
+
+Copy a host file or directory into a pod through the server\. Omit the pod when
+this project has exactly one\. Sending to an archived pod offers to restore it
+first\.
+
+Options:
+  \-y, \-\-yes   Restore an archived pod without asking
+.fi
+.RE
+.SS pipod receive
+.RS 2
+.nf
+Usage: pipod receive [pod] <path> [\-\-yes]
+
+Copy a file or directory from a pod into the current local directory\. <path>
+may be a workdir\-relative path or an absolute path inside that workdir, such
+as foo or /workspace/foo\. The destination must not already exist\. Omit the
+pod when this project has exactly one\. Receiving from an archived pod offers
+to restore it first\.
+
+Options:
+  \-y, \-\-yes   Restore an archived pod without asking
+.fi
+.RE
+.SS pipod archive
+.RS 2
+.nf
+Usage: pipod archive [pod…] [\-\-all] [\-\-template <name|id>] [\-\-idle <duration>] [\-\-dry\-run] [\-\-yes]
+
+Archive pods by id, short ref (p\-…), or name\. Archiving hides pods from
+`pipod list` (`pipod list \-\-archived` shows them); it never deletes work, and
+`pipod restore` brings them back\. Archiving a pod that hosts co\-located pods
+archives those too\.
+
+Options:
+  \-a, \-\-all              Archive every pod (cannot be combined with pod refs)
+  \-\-template <name|id>   Only pods launched from that template (whole account)
+  \-\-idle <duration>      Only pods whose last activity is older than this (4h, 2d, 30m)
+  \-\-dry\-run              Print the matching pods; archive nothing
+  \-y, \-\-yes              Skip the bulk confirmation
+.fi
+.RE
+.SS pipod restore
+.RS 2
+.nf
+Usage: pipod restore [pod…] [\-\-all] [\-\-yes]
+
+Bring archived pods back by id, short ref (p\-…), or name\. Restoring a host
+restores the co\-located pods archived with it\. `pipod attach` then starts the
+pod; a workspace in cold storage takes longer the bigger it is\.
+
+Options:
+  \-a, \-\-all   Restore every archived pod (cannot be combined with pod refs)
+  \-y, \-\-yes   Skip the \-\-all confirmation
+.fi
+.RE
+.SS pipod gc
+.RS 2
+.nf
+Usage: pipod gc [\-\-delete] [\-\-yes]
+
+List the archived and failed pods that can be deleted for good; \-\-delete deletes
+them\. (The server stops idle pods and moves stopped workspaces to cold storage on
+its own schedule; that never deletes anything\.)
+
+Options:
+  \-\-delete    Permanently delete the reclaimable pods
+  \-y, \-\-yes   Delete without a confirmation prompt
+.fi
+.RE
+.SS pipod doctor
+.RS 2
+.nf
+Usage: pipod doctor [\-\-template <name|id>]
+
+Check each layer a launch depends on: account auth, server reachability and
+version, organization membership and roles, secret references, and the
+server\-resolved settings bundle chain for this directory\. Works while signed
+out to diagnose auth problems\. Exits non\-zero when a layer fails\.
+
+Options:
+  \-\-template <name|id>   Plan the checked launch with this template
+.fi
+.RE
+.SS pipod update
+.RS 2
+.nf
+Usage: pipod update [\-\-dry\-run]
+
+Upgrade pi pod itself: a registry install updates to the latest published
+version; a git checkout pulls its upstream and rebuilds\.
+
+Options:
+  \-\-dry\-run   Report what an update would do without changing anything
+.fi
+.RE
+.SH FILES
+.RS 2
+.nf
+~/\.pi\-pod/auth\.json          this machine's sign\-in (pipod login)
+~/\.pi\-pod/config\.json        this machine's preferences, and the config of your
+                             user layer (pipod\-config(5))
+~/\.pi/agent/                 your Pi files, the rest of your user layer:
+                             settings\.json, models\.json, mcporter\.json,
+                             subagents\.json, agents/
+~/\.pi\-pod/org/               the organization layer's source: config\.json,
+                             init\.sh, bake\.sh, pi/, env
+~/\.pi\-pod/secrets/           dotenv files for pipod secrets sync
+~/\.pi\-pod/jobs/              your job files
+\|\.pi\-pod/config\.json          a project's config and its template pin
+\|\.pi\-pod/init\.sh              runs in each of the project's new pods
+\|\.pi\-pod/bake\.sh              built into the project's pod image
+\|\.pi\-pod/env                  the project's secret values; never committed
+\|\.pi\-pod/env\.example          the names of the project's secrets; committed
+\|\.pi\-pod/jobs/                the project's job files
+\|\.pi/                         the project's Pi files, as in ~/\.pi/agent/
+.fi
+.RE
+.SH ENVIRONMENT
+.RS 2
+.nf
+PI_POD_ACCOUNT_URL     the server pipod login uses with no \-\-server and no
+                       previous session
+PI_POD_ISSUER          the OIDC issuer pipod login uses, for a server too old
+                       to publish its own
+PI_POD_SERVER_URL      set in every pod: pipod there signs in with the pod's
+PI_POD_SERVER_TOKEN    own token, which reaches only the pods it launched and
+                       launches only from the pod's own template
+VISUAL, EDITOR         the editor for pipod settings edit
+NO_COLOR               plain output without color
+.fi
+.RE
+.SH SEE ALSO
+.P
+pipod\-config(5), https://github.com/pi-pod/pipod and docs/self\-host\.md there for running
+a server\.