# CLI Reference Paperclip CLI now supports both: - installation and lifecycle management (`install`, `uninstall`, `update`, `upgrade`, `service`) - instance setup/diagnostics (`onboard`, `doctor`, `configure`, `env`, `allowed-hostname`, `env-lab`) - control-plane client operations (issues, approvals, agents, activity, dashboard) ## Browser-approved Board authentication `npx paperclipai auth login --api-base ` creates a ten-minute challenge and prints a browser approval link. Sign in to the instance, review the requesting command and full Board access, then approve. The pending token cannot authenticate before approval. The CLI verifies its resulting identity before storing its credential in its private auth store. The default Board key expires after thirty days; `npx paperclipai auth logout` attempts server-side revocation and removes the local credential; check its `revoked` result. A requested company supplies audit context, not a restriction on the key's access. Approval requires current access to that company (active membership or instance-admin authority). A different person cannot take over an approved challenge. Cancellation and approval serialize on the same challenge; cancelling an already approved challenge does not revoke its key. The instance limits challenge creation to twenty requests per minute per client IP, and polling to 120, using separate process-local budgets. The normal one-second poll interval remains supported. HTTP 429 includes `Retry-After`. Operators behind a proxy must configure `TRUST_PROXY` for their actual trusted proxy boundary; client-supplied forwarding headers alone never mint a budget. These limits are per instance process, not a distributed denial-of-service or historical-record retention guarantee. The browser approval page retries only rate-limited challenge reads, up to three times. It honors the server delay, or waits sixty seconds when no valid delay is provided. Scheduling stops at ten minutes or a known earlier challenge expiry. Browser suspension can delay a queued read. The server still enforces the original expiry. Approval is never resubmitted automatically. Cloud front doors must preserve only anonymous challenge creation and capability-bound status polling. Approval uses the normal signed-in browser; no Cloud user identity is synthesized for the CLI's unauthenticated requests. ## Security: safe invocation for content-bearing arguments Use `npx paperclipai` for any command whose argument can hold untrusted or semi-trusted content. Untrusted content includes issue text, comment bodies, Markdown, pasted snippets, and model output. `npx` runs the CLI binary directly. It passes the argument as an inert `argv` value. It does not run a shell over the value. `npx paperclipai` works on any machine with Node: it runs a local install of the `paperclipai` package, and it fetches the published package when no local install is present. Do not use `pnpm paperclipai` for a content-bearing argument. `pnpm paperclipai` is a `package.json` script. `pnpm` builds a `/bin/sh` command string and appends the argument to it, so the shell reads the argument first. The shell interprets these spans before the CLI starts: - command substitution: a backtick pair or `$( )` - variable expansion: `$NAME` or `${NAME}` (this can leak a secret value into the persisted argument) A crafted value can run an arbitrary command as the invoking user. A crafted value can also expand an environment variable into the stored argument. No CLI-side check stops this, because the shell runs before `cli/src` starts. This is true even when the argument comes from a quoted shell variable, because `pnpm` re-evaluates the value in its own shell. Safe forms: - `npx paperclipai ` — the documented default. It passes an inert `argv` value and runs on any machine. - `node cli/node_modules/tsx/dist/cli.mjs cli/src/index.ts ` — the safe form to run the local source from a monorepo checkout. It is the exact command that the `pnpm paperclipai` script wraps, but it runs directly, so no shell reads the argument. Use it when you must test your local `cli/src` changes with a content-bearing argument. Unsafe or broken forms: - `pnpm paperclipai ` — unsafe. `pnpm` runs the argument through a shell first. - `pnpm run