CLI reference
Every public CLI command, grouped by task
Ask your agent
Show me the Percher commands for managing my app.Read the guide at percher.app/docs/cli-reference
How it works, with exact details
Run commands as bunx percher command, or use npx percher command when Bun is unavailable. New users normally only need publish, doctor, and logs.
<required> arguments must be supplied; [optional] arguments may be omitted. Run any command with --help for every option.
Start here
These commands cover the normal path from a local project to a tested live app.
percher loginSign in through the browser. Use --force to switch accounts.percher whoamiShow the signed-in account and token status.percher initDetect the project and create percher.toml. --force replaces an existing file.percher publishRecommended deploy command: inspect, package, upload, wait, and diagnose failures.percher publish --dry-runValidate and package without uploading anything.percher publish --previewCreate a temporary preview without replacing the live version.percher publish -m "note"Attach a note to deploy history. --no-cache forces a fresh build.percher wait-for-deploy <deployId>Wait for a queued deploy; --timeout sets the maximum seconds.percher doctor [app]Diagnose configuration, build, health, and runtime failures; --json is agent-friendly.percher open [app]Open the live app URL.Apps and deploys
Commands that change or inspect an app. Delete and rollback require deliberate confirmation or an explicit target.
percher create [name] --template <type>Create a starter app: node, python, static, nextjs, hono, or express.percher pushLow-level package and deploy. Prefer publish unless you need the lower-level flow.percher redeploy [deployId]Deploy existing uploaded source again; --no-cache rebuilds it from scratch.percher deploys [app]List recent deploy IDs, states, timestamps, and errors.percher deploys inspect [id]Show status and build log. --latest-failed resolves the latest failed deploy.percher logs [app]Stream runtime logs; use --tail N, --no-follow, or --build [deployId].percher versions [app]List deploy history and source commit SHAs.percher diff [base] [head]Compare two deploys. --patch includes unified file diffs for the owner.percher rollback [sha] [app]Restore a version. Without a SHA, choose among five recent versions; --last-good selects the latest healthy one.percher reproduce <deployId>Download a deploy source bundle and reproduce its build locally.percher preview <action>list, promote <id>, discard <id>, branch set <name>, branch unset, or branch show.percher rename <name> [app]Rename an app and change its percher.run subdomain.percher resume [app]Resume an app suspended for inactivity.percher claimAttach an anonymously published app to the signed-in account.percher inspect-link [app]Create a public read-only diagnostic link; --revoke disables it.percher cache reset [app]Clear the build cache so the next deploy runs cold.percher dashboard [tab]Open the app dashboard, optionally at a named tab.percher dev [app]Watch local files and deploy changes; --confirm asks before every push.percher appstore-kitGenerate PWA, TWA/Capacitor, and asset-link starter files.percher delete [app]Permanently delete an app. --yes skips the interactive confirmation.Configuration, data, and domains
Secret values belong in Percher environment variables, never in percher.toml or committed files.
percher env set KEY=VALUESet a secret or setting. Also supports --from-stdin, --from-file, --from-env-file, and --scope live|preview|all.percher env listList configured keys with values masked.percher env unset KEYRemove a key, optionally from one scope.percher generateGenerate .env.example and TypeScript env types from percher.toml.percher data [app]Show PocketBase/capsule data status and collections; --json returns structured output.percher data oauth <provider>Configure capsule OAuth, including provider client ID and secret.percher data reset-superuser [app]Rotate PocketBase admin credentials; --reveal prints the new password once.percher data export [app]Download PocketBase data as .tar.gz; --out chooses the destination.percher backups [app]List restorable backup IDs and dates.percher restore <source> [app]Restore app data; use --dry-run first and --components to limit scope.percher export [app]Download a portable app bundle without secrets; --git adds repository metadata.percher domains <action> [domain]add, verify, list, or remove a custom domain.percher analytics [app]Show privacy-preserving visitor analytics; --days accepts 1–90.percher importConvert supported Vercel or Netlify configuration to percher.toml.percher migrate-from-supabaseCreate a PocketBase schema/data migration and optionally rewrite SDK calls.Automation and access
URLs, tokens, and signing secrets shown once should be stored in a secret manager.
percher mcpPrint paste-ready MCP configuration for supported AI clients; --json returns only JSON.percher ai-files <action>install, update, status, or remove managed CLAUDE.md and Cursor instructions.percher github connect <https-url>Connect, deploy, and enable auto-deploy for a full HTTPS GitHub repository URL.percher github setup-webhookRegenerate webhook setup after an incomplete GitHub connection.percher hook <action>create <name>, list, or revoke <id> deploy hooks. A new hook URL is shown once.percher token <action>create <name>, list, or revoke <id>; create supports --scope, --app, and --ttl-days.percher statusShow public API and worker health; --json returns structured output.Collaboration, ownership, and account
Agents should inventory impact and ask for confirmation before revoking access, transferring ownership, or deleting data.
percher share <action>list, invite <email>, role <shareId> <viewer|admin>, or revoke <shareId>.percher invites <action>list, accept <shareId>, or decline <shareId> incoming app invitations.percher transfer <email>Start an ownership transfer; --list shows history and --cancel <id> cancels pending work.percher transfers <action>list, accept <transferId>, or decline <transferId> incoming ownership transfers.percher account exportDownload GDPR account data; --include-app-data can include app snapshots.percher account preview-deleteRead-only list of every blocker and cleanup action before account deletion.percher account deleteRequest permanent account erasure after all blockers are cleared.