The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
fix(security): standardize paperclipai CLI guidance on safe npx path (#11343)
Nicky Leach5ca7b4c1fefb
diff --git a/.agents/skills/paperclip-page/README.md b/.agents/skills/paperclip-page/README.mdindex cfe2d87882..47cf6d0f1e 100644--- a/.agents/skills/paperclip-page/README.md+++ b/.agents/skills/paperclip-page/README.md@@ -493,12 +493,12 @@ Create secrets from environment variables so values do not land in shell historyexport PAPERCLIP_PAGE_AWS_ACCESS_KEY_ID="$(jq -r '.AccessKey.AccessKeyId' /tmp/paperclip-page-uploader-key.json)"export PAPERCLIP_PAGE_AWS_SECRET_ACCESS_KEY="$(jq -r '.AccessKey.SecretAccessKey' /tmp/paperclip-page-uploader-key.json)"-pnpm paperclipai secrets create \+pnpm exec paperclipai secrets create \--company-id <company-id> \--name paperclip-page-aws-access-key-id \--value-env PAPERCLIP_PAGE_AWS_ACCESS_KEY_ID-pnpm paperclipai secrets create \+pnpm exec paperclipai secrets create \--company-id <company-id> \--name paperclip-page-aws-secret-access-key \--value-env PAPERCLIP_PAGE_AWS_SECRET_ACCESS_KEY@@ -532,7 +532,7 @@ host `AWS_PROFILE` identity for the entire agent run:Create or update the company skill from this package:```bash-pnpm paperclipai skills create \+pnpm exec paperclipai skills create \--company-id <company-id> \--name "Paperclip Page" \--slug paperclip-page \@@ -543,7 +543,7 @@ pnpm paperclipai skills create \Attach it to an agent:```bash-pnpm paperclipai skills agent sync <agent-id-or-shortname> \+pnpm exec paperclipai skills agent sync <agent-id-or-shortname> \--company-id <company-id> \--skill paperclip-page```diff --git a/doc/CLI.md b/doc/CLI.mdindex 5c75aeb4e8..c5eff04686 100644--- a/doc/CLI.md+++ b/doc/CLI.md@@ -6,6 +6,56 @@ Paperclip CLI now supports both:- instance setup/diagnostics (`onboard`, `doctor`, `configure`, `env`, `allowed-hostname`, `env-lab`)- control-plane client operations (issues, approvals, agents, activity, dashboard)+## Security: safe invocation for content-bearing arguments++Use `pnpm exec 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. `pnpm exec` runs the installed+binary directly. It passes the argument as an inert `argv` value. It does not+run a shell over the value.++Do not use `pnpm paperclipai` for a content-bearing argument. The safe form and+the unsafe form differ only by the `exec` keyword, so read the command with+care. `pnpm paperclipai` is a `package.json` script. `pnpm` runs the argument+through `/bin/sh` first. The shell interprets these metacharacters 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)+- other shell syntax: `; | & < >`++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.++Safe forms:++- `pnpm exec paperclipai <command> <args>` — the documented default+- `npx paperclipai <command> <args>` — also injection-safe; use it when no local+ install is present. `npx` fetches the package from the npm registry when the+ binary is not installed locally, so a mistyped name can start a network+ fetch. `pnpm exec` never does this; it runs only the locally installed binary.+- `node <cli>/dist/index.js <command> <args>` — trusted direct-binary call++Unsafe forms for a content-bearing argument:++- `pnpm paperclipai <command> <args>`+- `pnpm run <script> -- <args>`+- any `package.json` script that wraps the CLI++`pnpm paperclipai` stays acceptable only for local lifecycle and setup commands+that take fixed, trusted arguments (for example `run`, `onboard`, `doctor`,+`configure --section <name>`, `connect`, `env-lab up`, `worktree ensure-seeded`).+A command is content-bearing, and needs `pnpm exec`, when it takes a non-fixed+value: a hostname (`allowed-hostname`), an import URL or folder (`company+import`), an identifier or secret (`--company-id`, `--agent-id`,+`--claim-secret`), a payload (`--payload-json`), or free text (`--body`,+`--title`, `--comment`). A runtime value counts as non-fixed even when it looks+safe: the private-hostname guard builds `allowed-hostname <value>` from the+request Host header, so it must use `pnpm exec`. The `pnpm --filter+@paperclipai/*` build and test commands are not CLI invocation. They do not+change.+## Base UsageUse repo script in development:@@ -116,7 +166,7 @@ Canonical behavior is documented in `doc/DEPLOYMENT-MODES.md`.Allow an authenticated/private hostname (for example custom Tailscale DNS):```sh-pnpm paperclipai allowed-hostname dotta-macbook-pro+pnpm exec paperclipai allowed-hostname dotta-macbook-pro```Bring up the default local SSH fixture for environment testing:@@ -174,8 +224,8 @@ pnpm paperclipai issue list --data-dir ./tmp/paperclip-devStore local defaults in `~/.paperclip/context.json`:```sh-pnpm paperclipai context set --api-base http://localhost:3100 --company-id <company-id>-pnpm paperclipai context set --persona agent --agent-id <agent-id> --api-key-env-var-name PAPERCLIP_API_KEY+pnpm exec paperclipai context set --api-base http://localhost:3100 --company-id <company-id>+pnpm exec paperclipai context set --persona agent --agent-id <agent-id> --api-key-env-var-name PAPERCLIP_API_KEYpnpm paperclipai context showpnpm paperclipai context listpnpm paperclipai context use default@@ -184,35 +234,35 @@ pnpm paperclipai context use defaultTo avoid storing secrets in context, set `apiKeyEnvVarName` and keep the key in env:```sh-pnpm paperclipai context set --api-key-env-var-name PAPERCLIP_API_KEY+pnpm exec paperclipai context set --api-key-env-var-name PAPERCLIP_API_KEYexport PAPERCLIP_API_KEY=...```## Company Commands```sh-pnpm paperclipai company list-pnpm paperclipai company get <company-id>-pnpm paperclipai company current [--company-id <company-id>]-pnpm paperclipai company stats-pnpm paperclipai company create --payload-json '{...}'-pnpm paperclipai company update <company-id> --payload-json '{...}'-pnpm paperclipai company branding:update <company-id> --payload-json '{...}'-pnpm paperclipai company archive <company-id>-pnpm paperclipai company export <company-id> --out ./company --include company,agents,projects,issues,skills-pnpm paperclipai company export:preview <company-id> --payload-json '{...}'-pnpm paperclipai company export:api <company-id> --payload-json '{...}'-pnpm paperclipai company import ./company --target new --new-company-name "Imported Company"-pnpm paperclipai company import:preview <company-id> --payload-json '{...}'-pnpm paperclipai company import:apply <company-id> --payload-json '{...}'-pnpm paperclipai company delete <company-id-or-prefix> --yes --confirm <same-id-or-prefix>+pnpm exec paperclipai company list+pnpm exec paperclipai company get <company-id>+pnpm exec paperclipai company current [--company-id <company-id>]+pnpm exec paperclipai company stats+pnpm exec paperclipai company create --payload-json '{...}'+pnpm exec paperclipai company update <company-id> --payload-json '{...}'+pnpm exec paperclipai company branding:update <company-id> --payload-json '{...}'+pnpm exec paperclipai company archive <company-id>+pnpm exec paperclipai company export <company-id> --out ./company --include company,agents,projects,issues,skills+pnpm exec paperclipai company export:preview <company-id> --payload-json '{...}'+pnpm exec paperclipai company export:api <company-id> --payload-json '{...}'+pnpm exec paperclipai company import ./company --target new --new-company-name "Imported Company"+pnpm exec paperclipai company import:preview <company-id> --payload-json '{...}'+pnpm exec paperclipai company import:apply <company-id> --payload-json '{...}'+pnpm exec paperclipai company delete <company-id-or-prefix> --yes --confirm <same-id-or-prefix>```Examples:```sh-pnpm paperclipai company delete PAP --yes --confirm PAP-pnpm paperclipai company delete 5cbe79ee-acb3-4597-896e-7662742593cd --yes --confirm 5cbe79ee-acb3-4597-896e-7662742593cd+pnpm exec paperclipai company delete PAP --yes --confirm PAP+pnpm exec paperclipai company delete 5cbe79ee-acb3-4597-896e-7662742593cd --yes --confirm 5cbe79ee-acb3-4597-896e-7662742593cd```Notes:@@ -229,149 +279,149 @@ Notes:## Issue Commands```sh-pnpm paperclipai issue list --company-id <company-id> [--status todo,in_progress] [--assignee-agent-id <agent-id>] [--match text]-pnpm paperclipai issue get <issue-id-or-identifier>-pnpm paperclipai issue create --company-id <company-id> --title "..." [--description "..."] [--status todo] [--priority high]-pnpm paperclipai issue update <issue-id> [--status in_progress] [--comment "..."]-pnpm paperclipai issue delete <issue-id> --yes-pnpm paperclipai issue comment <issue-id> --body "..." [--reopen]-pnpm paperclipai issue comments <issue-id> [--limit 50]-pnpm paperclipai issue comment:get <issue-id> <comment-id>-pnpm paperclipai issue comment:delete <issue-id> <comment-id>-pnpm paperclipai issue runs <issue-id-or-identifier>-pnpm paperclipai issue live-runs <issue-id-or-identifier>-pnpm paperclipai issue active-run <issue-id-or-identifier>-pnpm paperclipai issue heartbeat-context <issue-id>-pnpm paperclipai issue checkout <issue-id> --agent-id <agent-id> [--expected-statuses todo,backlog,blocked]-pnpm paperclipai issue release <issue-id>-pnpm paperclipai issue force-release <issue-id>+pnpm exec paperclipai issue list --company-id <company-id> [--status todo,in_progress] [--assignee-agent-id <agent-id>] [--match text]+pnpm exec paperclipai issue get <issue-id-or-identifier>+pnpm exec paperclipai issue create --company-id <company-id> --title "..." [--description "..."] [--status todo] [--priority high]+pnpm exec paperclipai issue update <issue-id> [--status in_progress] [--comment "..."]+pnpm exec paperclipai issue delete <issue-id> --yes+pnpm exec paperclipai issue comment <issue-id> --body "..." [--reopen]+pnpm exec paperclipai issue comments <issue-id> [--limit 50]+pnpm exec paperclipai issue comment:get <issue-id> <comment-id>+pnpm exec paperclipai issue comment:delete <issue-id> <comment-id>+pnpm exec paperclipai issue runs <issue-id-or-identifier>+pnpm exec paperclipai issue live-runs <issue-id-or-identifier>+pnpm exec paperclipai issue active-run <issue-id-or-identifier>+pnpm exec paperclipai issue heartbeat-context <issue-id>+pnpm exec paperclipai issue checkout <issue-id> --agent-id <agent-id> [--expected-statuses todo,backlog,blocked]+pnpm exec paperclipai issue release <issue-id>+pnpm exec paperclipai issue force-release <issue-id>```Issue subresources are exposed as Paperclip API wrappers. Commands that map to broad server schemas accept JSON payloads and validate them with shared schemas before sending.```sh-pnpm paperclipai issue child:create <issue-id> --payload-json '{"title":"Child task"}'-pnpm paperclipai issue approvals <issue-id>-pnpm paperclipai issue approval:link <issue-id> <approval-id>-pnpm paperclipai issue approval:unlink <issue-id> <approval-id>-pnpm paperclipai issue read <issue-id>-pnpm paperclipai issue unread <issue-id>-pnpm paperclipai issue archive <issue-id>-pnpm paperclipai issue unarchive <issue-id>-pnpm paperclipai issue recovery-actions <issue-id>-pnpm paperclipai issue recovery:resolve <issue-id> --outcome restored --source-issue-status todo-```--```sh-pnpm paperclipai issue documents <issue-id> [--include-system]-pnpm paperclipai issue document:get <issue-id> <key>-pnpm paperclipai issue document:put <issue-id> <key> --body-file ./plan.md [--title Plan]-pnpm paperclipai issue document:lock <issue-id> <key>-pnpm paperclipai issue document:unlock <issue-id> <key>-pnpm paperclipai issue document:revisions <issue-id> <key>-pnpm paperclipai issue document:restore <issue-id> <key> <revision-id>-pnpm paperclipai issue document:delete <issue-id> <key>-```--```sh-pnpm paperclipai issue work-products <issue-id>-pnpm paperclipai issue work-product:create <issue-id> --payload-json '{"type":"pull_request","provider":"github","title":"PR"}'-pnpm paperclipai issue work-product:update <work-product-id> --payload-json '{"status":"archived"}'-pnpm paperclipai issue work-product:delete <work-product-id>-pnpm paperclipai issue interactions <issue-id>-pnpm paperclipai issue interaction:create <issue-id> --payload-json '{"kind":"request_confirmation","payload":{"version":1,"prompt":"Continue?"}}'-pnpm paperclipai issue interaction:accept <issue-id> <interaction-id> [--selected-client-keys key1,key2]-pnpm paperclipai issue interaction:reject <issue-id> <interaction-id> [--reason "..."]-pnpm paperclipai issue interaction:respond <issue-id> <interaction-id> --answers-json '[{"questionId":"q1","optionIds":["yes"]}]'-pnpm paperclipai issue interaction:cancel <issue-id> <interaction-id> [--reason "..."]-```--```sh-pnpm paperclipai issue tree-state <issue-id>-pnpm paperclipai issue tree-preview <issue-id> --payload-json '{"mode":"pause"}'-pnpm paperclipai issue tree-holds <issue-id> [--status active] [--include-members]-pnpm paperclipai issue tree-hold:create <issue-id> --payload-json '{"mode":"pause","reason":"review"}'-pnpm paperclipai issue tree-hold:get <issue-id> <hold-id>-pnpm paperclipai issue tree-hold:release <issue-id> <hold-id> [--payload-json '{"reason":"done"}']-pnpm paperclipai issue attachments <issue-id>-pnpm paperclipai issue attachment:upload <issue-id> --company-id <company-id> --file ./artifact.txt-pnpm paperclipai issue attachment:download <attachment-id> [--out ./artifact.txt]-pnpm paperclipai issue attachment:delete <attachment-id>-pnpm paperclipai issue label:list --company-id <company-id>-pnpm paperclipai issue label:create --company-id <company-id> --name bug --color '#ff0000'-pnpm paperclipai issue label:delete <label-id>-pnpm paperclipai issue feedback:votes <issue-id>-pnpm paperclipai issue feedback:vote <issue-id> --payload-json '{"targetType":"issue_comment","targetId":"...","vote":"up"}'+pnpm exec paperclipai issue child:create <issue-id> --payload-json '{"title":"Child task"}'+pnpm exec paperclipai issue approvals <issue-id>+pnpm exec paperclipai issue approval:link <issue-id> <approval-id>+pnpm exec paperclipai issue approval:unlink <issue-id> <approval-id>+pnpm exec paperclipai issue read <issue-id>+pnpm exec paperclipai issue unread <issue-id>+pnpm exec paperclipai issue archive <issue-id>+pnpm exec paperclipai issue unarchive <issue-id>+pnpm exec paperclipai issue recovery-actions <issue-id>+pnpm exec paperclipai issue recovery:resolve <issue-id> --outcome restored --source-issue-status todo+```++```sh+pnpm exec paperclipai issue documents <issue-id> [--include-system]+pnpm exec paperclipai issue document:get <issue-id> <key>+pnpm exec paperclipai issue document:put <issue-id> <key> --body-file ./plan.md [--title Plan]+pnpm exec paperclipai issue document:lock <issue-id> <key>+pnpm exec paperclipai issue document:unlock <issue-id> <key>+pnpm exec paperclipai issue document:revisions <issue-id> <key>+pnpm exec paperclipai issue document:restore <issue-id> <key> <revision-id>+pnpm exec paperclipai issue document:delete <issue-id> <key>+```++```sh+pnpm exec paperclipai issue work-products <issue-id>+pnpm exec paperclipai issue work-product:create <issue-id> --payload-json '{"type":"pull_request","provider":"github","title":"PR"}'+pnpm exec paperclipai issue work-product:update <work-product-id> --payload-json '{"status":"archived"}'+pnpm exec paperclipai issue work-product:delete <work-product-id>+pnpm exec paperclipai issue interactions <issue-id>+pnpm exec paperclipai issue interaction:create <issue-id> --payload-json '{"kind":"request_confirmation","payload":{"version":1,"prompt":"Continue?"}}'+pnpm exec paperclipai issue interaction:accept <issue-id> <interaction-id> [--selected-client-keys key1,key2]+pnpm exec paperclipai issue interaction:reject <issue-id> <interaction-id> [--reason "..."]+pnpm exec paperclipai issue interaction:respond <issue-id> <interaction-id> --answers-json '[{"questionId":"q1","optionIds":["yes"]}]'+pnpm exec paperclipai issue interaction:cancel <issue-id> <interaction-id> [--reason "..."]+```++```sh+pnpm exec paperclipai issue tree-state <issue-id>+pnpm exec paperclipai issue tree-preview <issue-id> --payload-json '{"mode":"pause"}'+pnpm exec paperclipai issue tree-holds <issue-id> [--status active] [--include-members]+pnpm exec paperclipai issue tree-hold:create <issue-id> --payload-json '{"mode":"pause","reason":"review"}'+pnpm exec paperclipai issue tree-hold:get <issue-id> <hold-id>+pnpm exec paperclipai issue tree-hold:release <issue-id> <hold-id> [--payload-json '{"reason":"done"}']+pnpm exec paperclipai issue attachments <issue-id>+pnpm exec paperclipai issue attachment:upload <issue-id> --company-id <company-id> --file ./artifact.txt+pnpm exec paperclipai issue attachment:download <attachment-id> [--out ./artifact.txt]+pnpm exec paperclipai issue attachment:delete <attachment-id>+pnpm exec paperclipai issue label:list --company-id <company-id>+pnpm exec paperclipai issue label:create --company-id <company-id> --name bug --color '#ff0000'+pnpm exec paperclipai issue label:delete <label-id>+pnpm exec paperclipai issue feedback:votes <issue-id>+pnpm exec paperclipai issue feedback:vote <issue-id> --payload-json '{"targetType":"issue_comment","targetId":"...","vote":"up"}'```## Project Commands```sh-pnpm paperclipai project list --company-id <company-id>-pnpm paperclipai project get <project-id-or-shortname> [--company-id <company-id>]-pnpm paperclipai project create --company-id <company-id> --name "Launch Site" [--goal-ids <id1,id2>] [--lead-agent-id <id>]-pnpm paperclipai project update <project-id-or-shortname> [--status in_progress] [--company-id <company-id>]-pnpm paperclipai project delete <project-id-or-shortname> --yes [--company-id <company-id>]+pnpm exec paperclipai project list --company-id <company-id>+pnpm exec paperclipai project get <project-id-or-shortname> [--company-id <company-id>]+pnpm exec paperclipai project create --company-id <company-id> --name "Launch Site" [--goal-ids <id1,id2>] [--lead-agent-id <id>]+pnpm exec paperclipai project update <project-id-or-shortname> [--status in_progress] [--company-id <company-id>]+pnpm exec paperclipai project delete <project-id-or-shortname> --yes [--company-id <company-id>]```Advanced project fields accept JSON:```sh-pnpm paperclipai project create --company-id <company-id> --name "Ops" --env-json '{"OPENAI_API_KEY":{"kind":"secret","secretName":"openai-api-key"}}'-pnpm paperclipai project update <project-id> --execution-workspace-policy-json '{"enabled":true,"defaultMode":"shared_workspace"}'+pnpm exec paperclipai project create --company-id <company-id> --name "Ops" --env-json '{"OPENAI_API_KEY":{"kind":"secret","secretName":"openai-api-key"}}'+pnpm exec paperclipai project update <project-id> --execution-workspace-policy-json '{"enabled":true,"defaultMode":"shared_workspace"}'```## Goal Commands```sh-pnpm paperclipai goal list --company-id <company-id>-pnpm paperclipai goal get <goal-id>-pnpm paperclipai goal create --company-id <company-id> --title "Grow revenue" [--level company] [--status active]-pnpm paperclipai goal update <goal-id> [--title "..."] [--status achieved]-pnpm paperclipai goal delete <goal-id> --yes+pnpm exec paperclipai goal list --company-id <company-id>+pnpm exec paperclipai goal get <goal-id>+pnpm exec paperclipai goal create --company-id <company-id> --title "Grow revenue" [--level company] [--status active]+pnpm exec paperclipai goal update <goal-id> [--title "..."] [--status achieved]+pnpm exec paperclipai goal delete <goal-id> --yes```## Agent Commands```sh-pnpm paperclipai agent list --company-id <company-id>-pnpm paperclipai agent get <agent-id>-pnpm paperclipai agent create --company-id <company-id> --payload-json '{"name":"Builder","adapterType":"codex_local"}'-pnpm paperclipai agent hire --company-id <company-id> --payload-json '{...}'-pnpm paperclipai agent update <agent-id> --payload-json '{"title":"Senior Builder"}'-pnpm paperclipai agent delete <agent-id> --yes-pnpm paperclipai agent me-pnpm paperclipai agent inbox-pnpm paperclipai agent inbox-mine --user-id <board-user-id>-pnpm paperclipai agent wake <agent-id-or-shortname> [--company-id <company-id>] [--reason "..."] [--payload '{"issueId":"..."}']-pnpm paperclipai agent pause <agent-id>-pnpm paperclipai agent resume <agent-id>-pnpm paperclipai agent approve <agent-id>-pnpm paperclipai agent terminate <agent-id>-pnpm paperclipai agent heartbeat:invoke <agent-id>-pnpm paperclipai agent claude-login <agent-id>-pnpm paperclipai agent local-cli <agent-id-or-shortname> --company-id <company-id>+pnpm exec paperclipai agent list --company-id <company-id>+pnpm exec paperclipai agent get <agent-id>+pnpm exec paperclipai agent create --company-id <company-id> --payload-json '{"name":"Builder","adapterType":"codex_local"}'+pnpm exec paperclipai agent hire --company-id <company-id> --payload-json '{...}'+pnpm exec paperclipai agent update <agent-id> --payload-json '{"title":"Senior Builder"}'+pnpm exec paperclipai agent delete <agent-id> --yes+pnpm exec paperclipai agent me+pnpm exec paperclipai agent inbox+pnpm exec paperclipai agent inbox-mine --user-id <board-user-id>+pnpm exec paperclipai agent wake <agent-id-or-shortname> [--company-id <company-id>] [--reason "..."] [--payload '{"issueId":"..."}']+pnpm exec paperclipai agent pause <agent-id>+pnpm exec paperclipai agent resume <agent-id>+pnpm exec paperclipai agent approve <agent-id>+pnpm exec paperclipai agent terminate <agent-id>+pnpm exec paperclipai agent heartbeat:invoke <agent-id>+pnpm exec paperclipai agent claude-login <agent-id>+pnpm exec paperclipai agent local-cli <agent-id-or-shortname> --company-id <company-id>```Agent configuration and runtime endpoints:```sh-pnpm paperclipai agent permissions:update <agent-id> --payload-json '{"canCreateAgents":true,"canCreateSkills":true,"canAssignTasks":true}'-pnpm paperclipai agent configuration <agent-id>-pnpm paperclipai agent config-revisions <agent-id>-pnpm paperclipai agent config-revision:get <agent-id> <revision-id>-pnpm paperclipai agent config-revision:rollback <agent-id> <revision-id>-pnpm paperclipai agent runtime-state <agent-id>-pnpm paperclipai agent runtime-state:reset-session <agent-id> [--task-key <key>]-pnpm paperclipai agent task-sessions <agent-id>-pnpm paperclipai agent skills <agent-id>-pnpm paperclipai agent skills:sync <agent-id> --desired-skills paperclip,github --mode add-pnpm paperclipai agent instructions-path:update <agent-id> --payload-json '{"path":"/path/to/AGENTS.md"}'-pnpm paperclipai agent instructions-bundle <agent-id>-pnpm paperclipai agent instructions-bundle:update <agent-id> --payload-json '{"mode":"managed"}'-pnpm paperclipai agent instructions-file:get <agent-id> --path AGENTS.md-pnpm paperclipai agent instructions-file:put <agent-id> --path AGENTS.md --content-file ./AGENTS.md-pnpm paperclipai agent instructions-file:delete <agent-id> --path AGENTS.md+pnpm exec paperclipai agent permissions:update <agent-id> --payload-json '{"canCreateAgents":true,"canCreateSkills":true,"canAssignTasks":true}'+pnpm exec paperclipai agent configuration <agent-id>+pnpm exec paperclipai agent config-revisions <agent-id>+pnpm exec paperclipai agent config-revision:get <agent-id> <revision-id>+pnpm exec paperclipai agent config-revision:rollback <agent-id> <revision-id>+pnpm exec paperclipai agent runtime-state <agent-id>+pnpm exec paperclipai agent runtime-state:reset-session <agent-id> [--task-key <key>]+pnpm exec paperclipai agent task-sessions <agent-id>+pnpm exec paperclipai agent skills <agent-id>+pnpm exec paperclipai agent skills:sync <agent-id> --desired-skills paperclip,github --mode add+pnpm exec paperclipai agent instructions-path:update <agent-id> --payload-json '{"path":"/path/to/AGENTS.md"}'+pnpm exec paperclipai agent instructions-bundle <agent-id>+pnpm exec paperclipai agent instructions-bundle:update <agent-id> --payload-json '{"mode":"managed"}'+pnpm exec paperclipai agent instructions-file:get <agent-id> --path AGENTS.md+pnpm exec paperclipai agent instructions-file:put <agent-id> --path AGENTS.md --content-file ./AGENTS.md+pnpm exec paperclipai agent instructions-file:delete <agent-id> --path AGENTS.md```Agent config, instructions, skills, project env, environment, secret, and workspace edits affect the next run. Active runs finish with the config they started with. When a saved session, reused workspace, or sandbox lease no longer matches the effective next-run config, Paperclip may start fresh execution and records non-sensitive freshness categories in run result JSON and workspace operation logs.@@ -385,8 +435,8 @@ Agent config, instructions, skills, project env, environment, secret, and workspExample for shortname-based local setup:```sh-pnpm paperclipai agent local-cli codexcoder --company-id <company-id>-pnpm paperclipai agent local-cli claudecoder --company-id <company-id>+pnpm exec paperclipai agent local-cli codexcoder --company-id <company-id>+pnpm exec paperclipai agent local-cli claudecoder --company-id <company-id>```## Token Commands@@ -394,18 +444,18 @@ pnpm paperclipai agent local-cli claudecoder --company-id <company-id>Agent API keys are scoped to one company and one agent. Plaintext tokens are printed once at creation.```sh-pnpm paperclipai token agent create --company-id <company-id> --agent <agent-id-or-name> --name external-worker-pnpm paperclipai token agent list --company-id <company-id> --agent <agent-id-or-name>-pnpm paperclipai token agent revoke --company-id <company-id> --agent <agent-id-or-name> <key-id>+pnpm exec paperclipai token agent create --company-id <company-id> --agent <agent-id-or-name> --name external-worker+pnpm exec paperclipai token agent list --company-id <company-id> --agent <agent-id-or-name>+pnpm exec paperclipai token agent revoke --company-id <company-id> --agent <agent-id-or-name> <key-id>```Named board API keys use the board authorization model, support revocation and expiration metadata, and are audited server-side.```sh-pnpm paperclipai token board create --company-id <company-id> --name external-admin-pnpm paperclipai token board create --name short-lived --ttl-days 7-pnpm paperclipai token board list-pnpm paperclipai token board revoke <key-id>+pnpm exec paperclipai token board create --company-id <company-id> --name external-admin+pnpm exec paperclipai token board create --name short-lived --ttl-days 7+pnpm exec paperclipai token board list+pnpm exec paperclipai token board revoke <key-id>```## Run Commands@@ -413,16 +463,16 @@ pnpm paperclipai token board revoke <key-id>`paperclipai run` without a subcommand still bootstraps and starts a local Paperclip instance. The subcommands below inspect and control API heartbeat runs.```sh-pnpm paperclipai run list --company-id <company-id> [--agent-id <agent-id>] [--limit 50]-pnpm paperclipai run live --company-id <company-id> [--limit 50] [--min-count 0]-pnpm paperclipai run get <run-id>-pnpm paperclipai run events <run-id> [--after-seq 0] [--limit 200]-pnpm paperclipai run log <run-id> [--offset 0] [--limit-bytes 16384] [--text]-pnpm paperclipai run cancel <run-id>-pnpm paperclipai run issues <run-id>-pnpm paperclipai run workspace-operations <run-id>-pnpm paperclipai run workspace-log <operation-id> [--offset 0] [--limit-bytes 16384] [--text]-pnpm paperclipai run watchdog-decision <run-id> --decision continue [--reason "..."]+pnpm exec paperclipai run list --company-id <company-id> [--agent-id <agent-id>] [--limit 50]+pnpm exec paperclipai run live --company-id <company-id> [--limit 50] [--min-count 0]+pnpm exec paperclipai run get <run-id>+pnpm exec paperclipai run events <run-id> [--after-seq 0] [--limit 200]+pnpm exec paperclipai run log <run-id> [--offset 0] [--limit-bytes 16384] [--text]+pnpm exec paperclipai run cancel <run-id>+pnpm exec paperclipai run issues <run-id>+pnpm exec paperclipai run workspace-operations <run-id>+pnpm exec paperclipai run workspace-log <operation-id> [--offset 0] [--limit-bytes 16384] [--text]+pnpm exec paperclipai run watchdog-decision <run-id> --decision continue [--reason "..."]```## Routine Commands@@ -430,19 +480,19 @@ pnpm paperclipai run watchdog-decision <run-id> --decision continue [--reason ".`paperclipai routines disable-all` remains the local maintenance command. The singular `routine` group maps to the REST API.```sh-pnpm paperclipai routine list --company-id <company-id> [--project-id <project-id>]-pnpm paperclipai routine create --company-id <company-id> --payload-json '{...}'-pnpm paperclipai routine get <routine-id>-pnpm paperclipai routine update <routine-id> --payload-json '{...}'-pnpm paperclipai routine revisions <routine-id>-pnpm paperclipai routine revision:restore <routine-id> <revision-id>-pnpm paperclipai routine runs <routine-id> [--limit 50]-pnpm paperclipai routine run <routine-id> [--payload-json '{...}']-pnpm paperclipai routine trigger:create <routine-id> --payload-json '{...}'-pnpm paperclipai routine trigger:update <trigger-id> --payload-json '{...}'-pnpm paperclipai routine trigger:delete <trigger-id>-pnpm paperclipai routine trigger:rotate-secret <trigger-id>-pnpm paperclipai routine trigger:fire <public-id> [--payload-json '{...}']+pnpm exec paperclipai routine list --company-id <company-id> [--project-id <project-id>]+pnpm exec paperclipai routine create --company-id <company-id> --payload-json '{...}'+pnpm exec paperclipai routine get <routine-id>+pnpm exec paperclipai routine update <routine-id> --payload-json '{...}'+pnpm exec paperclipai routine revisions <routine-id>+pnpm exec paperclipai routine revision:restore <routine-id> <revision-id>+pnpm exec paperclipai routine runs <routine-id> [--limit 50]+pnpm exec paperclipai routine run <routine-id> [--payload-json '{...}']+pnpm exec paperclipai routine trigger:create <routine-id> --payload-json '{...}'+pnpm exec paperclipai routine trigger:update <trigger-id> --payload-json '{...}'+pnpm exec paperclipai routine trigger:delete <trigger-id>+pnpm exec paperclipai routine trigger:rotate-secret <trigger-id>+pnpm exec paperclipai routine trigger:fire <public-id> [--payload-json '{...}']```## Prompt Handoff@@ -450,10 +500,10 @@ pnpm paperclipai routine trigger:fire <public-id> [--payload-json '{...}']Prompt handoff creates Paperclip work. It does not create a chat session.```sh-pnpm paperclipai agent-prompt <agent-name-or-id> <agent-api-key> "Prompt here"-pnpm paperclipai agent prompt --agent <agent-name-or-id> --api-key-env PAPERCLIP_API_KEY "Prompt here"-pnpm paperclipai agent prompt --profile my-agent "Prompt here"-pnpm paperclipai board prompt --company-id <company-id> --agent <agent-name-or-id> "Prompt here"+pnpm exec paperclipai agent-prompt <agent-name-or-id> <agent-api-key> "Prompt here"+pnpm exec paperclipai agent prompt --agent <agent-name-or-id> --api-key-env PAPERCLIP_API_KEY "Prompt here"+pnpm exec paperclipai agent prompt --profile my-agent "Prompt here"+pnpm exec paperclipai board prompt --company-id <company-id> --agent <agent-name-or-id> "Prompt here"```By default the command creates a `todo` issue assigned to the target agent and wakes the agent. Use `--issue <issue-id>` to add a comment to existing work, and `--no-wake` to skip the wakeup.@@ -490,10 +540,10 @@ Browse and inspect commands never mutate company state; `install` adds a catalogskill to the company library.```sh-pnpm paperclipai skills browse [--kind bundled|optional] [--category <slug>] [--query <text>]-pnpm paperclipai skills search "<text>" [--kind bundled|optional] [--category <slug>]-pnpm paperclipai skills inspect <catalog-id-or-key-or-slug>-pnpm paperclipai skills install <catalog-id-or-key-or-slug> [--as <slug>] [--force] --company-id <company-id>+pnpm exec paperclipai skills browse [--kind bundled|optional] [--category <slug>] [--query <text>]+pnpm exec paperclipai skills search "<text>" [--kind bundled|optional] [--category <slug>]+pnpm exec paperclipai skills inspect <catalog-id-or-key-or-slug>+pnpm exec paperclipai skills install <catalog-id-or-key-or-slug> [--as <slug>] [--force] --company-id <company-id>```Catalog semantics:@@ -514,11 +564,11 @@ Catalog semantics:Examples:```sh-pnpm paperclipai skills browse --kind bundled --company-id <company-id>-pnpm paperclipai skills search "pull request" --kind bundled-pnpm paperclipai skills inspect github-pr-workflow-pnpm paperclipai skills install github-pr-workflow --company-id <company-id>-pnpm paperclipai skills install paperclipai:optional:browser:agent-browser --company-id <company-id>+pnpm exec paperclipai skills browse --kind bundled --company-id <company-id>+pnpm exec paperclipai skills search "pull request" --kind bundled+pnpm exec paperclipai skills inspect github-pr-workflow+pnpm exec paperclipai skills install github-pr-workflow --company-id <company-id>+pnpm exec paperclipai skills install paperclipai:optional:browser:agent-browser --company-id <company-id>```External GitHub, skills.sh, local-path, and URL sources still go through@@ -527,18 +577,18 @@ External GitHub, skills.sh, local-path, and URL sources still go through### Company library```sh-pnpm paperclipai skills list --company-id <company-id>-pnpm paperclipai skills show <skill-id-or-key-or-slug> --company-id <company-id>-pnpm paperclipai skills file <skill-id-or-key-or-slug> [--path SKILL.md] --company-id <company-id>-pnpm paperclipai skills import <source> --company-id <company-id>-pnpm paperclipai skills create --name "Review PRs" [--slug review-prs] [--description "..."] [--body-file SKILL.md] --company-id <company-id>-pnpm paperclipai skills scan-projects [--project-id <id>...] [--workspace-id <id>...] --company-id <company-id>-pnpm paperclipai skills check [skill-id-or-key-or-slug] --company-id <company-id>-pnpm paperclipai skills update <skill-id-or-key-or-slug> [--force] --company-id <company-id>-pnpm paperclipai skills update --all [--force] --company-id <company-id>-pnpm paperclipai skills audit [skill-id-or-key-or-slug] --company-id <company-id>-pnpm paperclipai skills reset <skill-id-or-key-or-slug> [--yes] [--force] --company-id <company-id>-pnpm paperclipai skills remove <skill-id-or-key-or-slug> --yes --company-id <company-id>+pnpm exec paperclipai skills list --company-id <company-id>+pnpm exec paperclipai skills show <skill-id-or-key-or-slug> --company-id <company-id>+pnpm exec paperclipai skills file <skill-id-or-key-or-slug> [--path SKILL.md] --company-id <company-id>+pnpm exec paperclipai skills import <source> --company-id <company-id>+pnpm exec paperclipai skills create --name "Review PRs" [--slug review-prs] [--description "..."] [--body-file SKILL.md] --company-id <company-id>+pnpm exec paperclipai skills scan-projects [--project-id <id>...] [--workspace-id <id>...] --company-id <company-id>+pnpm exec paperclipai skills check [skill-id-or-key-or-slug] --company-id <company-id>+pnpm exec paperclipai skills update <skill-id-or-key-or-slug> [--force] --company-id <company-id>+pnpm exec paperclipai skills update --all [--force] --company-id <company-id>+pnpm exec paperclipai skills audit [skill-id-or-key-or-slug] --company-id <company-id>+pnpm exec paperclipai skills reset <skill-id-or-key-or-slug> [--yes] [--force] --company-id <company-id>+pnpm exec paperclipai skills remove <skill-id-or-key-or-slug> --yes --company-id <company-id>````skills import <source>` accepts a skills.sh URL, the equivalent@@ -564,9 +614,9 @@ maintenance loop for catalog-installed skills:### Agent attach```sh-pnpm paperclipai skills agent list <agent-id-or-shortname> --company-id <company-id>-pnpm paperclipai skills agent sync <agent-id-or-shortname> --skill <skill-id-or-key-or-slug> [--skill <skill-id-or-key-or-slug>...] --mode <add|remove|replace> --company-id <company-id>-pnpm paperclipai skills agent clear <agent-id-or-shortname> --yes --company-id <company-id>+pnpm exec paperclipai skills agent list <agent-id-or-shortname> --company-id <company-id>+pnpm exec paperclipai skills agent sync <agent-id-or-shortname> --skill <skill-id-or-key-or-slug> [--skill <skill-id-or-key-or-slug>...] --mode <add|remove|replace> --company-id <company-id>+pnpm exec paperclipai skills agent clear <agent-id-or-shortname> --yes --company-id <company-id>````skills agent sync` requires a merge mode and returns the resulting adapter@@ -594,11 +644,11 @@ change company state. `preview` runs the company import planner, and `install`imports the catalog team into an existing company.```sh-pnpm paperclipai teams browse [--kind bundled|optional] [--category <slug>] [--query <text>]-pnpm paperclipai teams search "<text>" [--kind bundled|optional] [--category <slug>]-pnpm paperclipai teams inspect <catalog-id-or-key-or-slug> [--file TEAM.md]-pnpm paperclipai teams preview <catalog-id-or-key-or-slug> --company-id <company-id>-pnpm paperclipai teams install <catalog-id-or-key-or-slug> --company-id <company-id>+pnpm exec paperclipai teams browse [--kind bundled|optional] [--category <slug>] [--query <text>]+pnpm exec paperclipai teams search "<text>" [--kind bundled|optional] [--category <slug>]+pnpm exec paperclipai teams inspect <catalog-id-or-key-or-slug> [--file TEAM.md]+pnpm exec paperclipai teams preview <catalog-id-or-key-or-slug> --company-id <company-id>+pnpm exec paperclipai teams install <catalog-id-or-key-or-slug> --company-id <company-id>```Preview/install options:@@ -626,22 +676,22 @@ Preview/install options:## Secrets Commands```sh-pnpm paperclipai secrets list --company-id <company-id>-pnpm paperclipai secrets declarations --company-id <company-id> [--include agents,projects] [--kind secret]-pnpm paperclipai secrets create --company-id <company-id> --name anthropic-api-key --value-env ANTHROPIC_API_KEY-pnpm paperclipai secrets link --company-id <company-id> --name prod-stripe-key --provider aws_secrets_manager --external-ref <provider-ref>-pnpm paperclipai secrets doctor --company-id <company-id>-pnpm paperclipai secrets provider-configs --company-id <company-id>-pnpm paperclipai secrets provider-config:create --company-id <company-id> --payload-json '{...}'-pnpm paperclipai secrets provider-config:discovery-preview --company-id <company-id> --payload-json '{...}'-pnpm paperclipai secrets provider-config:get <config-id>-pnpm paperclipai secrets provider-config:update <config-id> --payload-json '{...}'-pnpm paperclipai secrets provider-config:default <config-id>-pnpm paperclipai secrets provider-config:health <config-id>-pnpm paperclipai secrets provider-config:delete <config-id>-pnpm paperclipai secrets remote-import:preview --company-id <company-id> --payload-json '{...}'-pnpm paperclipai secrets remote-import --company-id <company-id> --payload-json '{...}'-pnpm paperclipai secrets migrate-inline-env --company-id <company-id> [--apply]+pnpm exec paperclipai secrets list --company-id <company-id>+pnpm exec paperclipai secrets declarations --company-id <company-id> [--include agents,projects] [--kind secret]+pnpm exec paperclipai secrets create --company-id <company-id> --name anthropic-api-key --value-env ANTHROPIC_API_KEY+pnpm exec paperclipai secrets link --company-id <company-id> --name prod-stripe-key --provider aws_secrets_manager --external-ref <provider-ref>+pnpm exec paperclipai secrets doctor --company-id <company-id>+pnpm exec paperclipai secrets provider-configs --company-id <company-id>+pnpm exec paperclipai secrets provider-config:create --company-id <company-id> --payload-json '{...}'+pnpm exec paperclipai secrets provider-config:discovery-preview --company-id <company-id> --payload-json '{...}'+pnpm exec paperclipai secrets provider-config:get <config-id>+pnpm exec paperclipai secrets provider-config:update <config-id> --payload-json '{...}'+pnpm exec paperclipai secrets provider-config:default <config-id>+pnpm exec paperclipai secrets provider-config:health <config-id>+pnpm exec paperclipai secrets provider-config:delete <config-id>+pnpm exec paperclipai secrets remote-import:preview --company-id <company-id> --payload-json '{...}'+pnpm exec paperclipai secrets remote-import --company-id <company-id> --payload-json '{...}'+pnpm exec paperclipai secrets migrate-inline-env --company-id <company-id> [--apply]```Secret listing and declarations never print secret values. `create` accepts@@ -661,78 +711,78 @@ commands above. See the## Approval Commands```sh-pnpm paperclipai approval list --company-id <company-id> [--status pending]-pnpm paperclipai approval get <approval-id>-pnpm paperclipai approval create --company-id <company-id> --type hire_agent --payload '{"name":"..."}' [--issue-ids <id1,id2>]-pnpm paperclipai approval approve <approval-id> [--decision-note "..."]-pnpm paperclipai approval reject <approval-id> [--decision-note "..."]-pnpm paperclipai approval request-revision <approval-id> [--decision-note "..."]-pnpm paperclipai approval resubmit <approval-id> [--payload '{"...":"..."}']-pnpm paperclipai approval comment <approval-id> --body "..."+pnpm exec paperclipai approval list --company-id <company-id> [--status pending]+pnpm exec paperclipai approval get <approval-id>+pnpm exec paperclipai approval create --company-id <company-id> --type hire_agent --payload '{"name":"..."}' [--issue-ids <id1,id2>]+pnpm exec paperclipai approval approve <approval-id> [--decision-note "..."]+pnpm exec paperclipai approval reject <approval-id> [--decision-note "..."]+pnpm exec paperclipai approval request-revision <approval-id> [--decision-note "..."]+pnpm exec paperclipai approval resubmit <approval-id> [--payload '{"...":"..."}']+pnpm exec paperclipai approval comment <approval-id> --body "..."```## Activity Commands```sh-pnpm paperclipai activity list --company-id <company-id> [--agent-id <agent-id>] [--entity-type issue] [--entity-id <id>]-pnpm paperclipai activity create --company-id <company-id> --payload-json '{...}'-pnpm paperclipai activity issue <issue-id>+pnpm exec paperclipai activity list --company-id <company-id> [--agent-id <agent-id>] [--entity-type issue] [--entity-id <id>]+pnpm exec paperclipai activity create --company-id <company-id> --payload-json '{...}'+pnpm exec paperclipai activity issue <issue-id>```## Dashboard Commands```sh-pnpm paperclipai dashboard get --company-id <company-id>+pnpm exec paperclipai dashboard get --company-id <company-id>```## Org And Agent Config Commands```sh-pnpm paperclipai whoami-pnpm paperclipai openapi-pnpm paperclipai org get --company-id <company-id>-pnpm paperclipai org svg --company-id <company-id> [--out org.svg]-pnpm paperclipai org png --company-id <company-id> [--out org.png]-pnpm paperclipai agent-config list --company-id <company-id>+pnpm exec paperclipai whoami+pnpm exec paperclipai openapi+pnpm exec paperclipai org get --company-id <company-id>+pnpm exec paperclipai org svg --company-id <company-id> [--out org.svg]+pnpm exec paperclipai org png --company-id <company-id> [--out org.png]+pnpm exec paperclipai agent-config list --company-id <company-id>```## Access, Profile, And Instance Commands```sh-pnpm paperclipai profile session-pnpm paperclipai profile get-pnpm paperclipai profile update --payload-json '{...}'-pnpm paperclipai profile company-user <user-slug> --company-id <company-id>-pnpm paperclipai invite list --company-id <company-id>-pnpm paperclipai invite create --company-id <company-id> --payload-json '{...}'-pnpm paperclipai invite revoke <invite-id>-pnpm paperclipai invite show <token>-pnpm paperclipai invite accept <token> [--payload-json '{...}']-pnpm paperclipai invite onboarding:text <token>-pnpm paperclipai join list --company-id <company-id> [--status pending_approval]-pnpm paperclipai join approve <request-id> --company-id <company-id>-pnpm paperclipai join reject <request-id> --company-id <company-id>-pnpm paperclipai join claim-key <request-id> --claim-secret <secret>-pnpm paperclipai member list --company-id <company-id>-pnpm paperclipai member update <member-id> --company-id <company-id> --payload-json '{...}'-pnpm paperclipai member role-and-grants <member-id> --company-id <company-id> --payload-json '{...}'-pnpm paperclipai member permissions <member-id> --company-id <company-id> --payload-json '{...}'-pnpm paperclipai member archive <member-id> --company-id <company-id> [--payload-json '{...}']-pnpm paperclipai admin user list [--query <text>]-pnpm paperclipai admin user promote <user-id>-pnpm paperclipai admin user demote <user-id>-pnpm paperclipai admin user company-access <user-id>-pnpm paperclipai admin user company-access:update <user-id> --payload-json '{...}'+pnpm exec paperclipai profile session+pnpm exec paperclipai profile get+pnpm exec paperclipai profile update --payload-json '{...}'+pnpm exec paperclipai profile company-user <user-slug> --company-id <company-id>+pnpm exec paperclipai invite list --company-id <company-id>+pnpm exec paperclipai invite create --company-id <company-id> --payload-json '{...}'+pnpm exec paperclipai invite revoke <invite-id>+pnpm exec paperclipai invite show <token>+pnpm exec paperclipai invite accept <token> [--payload-json '{...}']+pnpm exec paperclipai invite onboarding:text <token>+pnpm exec paperclipai join list --company-id <company-id> [--status pending_approval]+pnpm exec paperclipai join approve <request-id> --company-id <company-id>+pnpm exec paperclipai join reject <request-id> --company-id <company-id>+pnpm exec paperclipai join claim-key <request-id> --claim-secret <secret>+pnpm exec paperclipai member list --company-id <company-id>+pnpm exec paperclipai member update <member-id> --company-id <company-id> --payload-json '{...}'+pnpm exec paperclipai member role-and-grants <member-id> --company-id <company-id> --payload-json '{...}'+pnpm exec paperclipai member permissions <member-id> --company-id <company-id> --payload-json '{...}'+pnpm exec paperclipai member archive <member-id> --company-id <company-id> [--payload-json '{...}']+pnpm exec paperclipai admin user list [--query <text>]+pnpm exec paperclipai admin user promote <user-id>+pnpm exec paperclipai admin user demote <user-id>+pnpm exec paperclipai admin user company-access <user-id>+pnpm exec paperclipai admin user company-access:update <user-id> --payload-json '{...}'```CLI auth challenge endpoints are also exposed for tooling that needs the raw challenge lifecycle:```sh-pnpm paperclipai auth challenge create --payload-json '{...}'-PAPERCLIP_CHALLENGE_SECRET=<challenge-secret> pnpm paperclipai auth challenge get <challenge-id> --token-env PAPERCLIP_CHALLENGE_SECRET-PAPERCLIP_CHALLENGE_SECRET=<challenge-secret> pnpm paperclipai auth challenge approve <challenge-id> --token-env PAPERCLIP_CHALLENGE_SECRET-PAPERCLIP_CHALLENGE_SECRET=<challenge-secret> pnpm paperclipai auth challenge cancel <challenge-id> --token-env PAPERCLIP_CHALLENGE_SECRET-pnpm paperclipai auth revoke-current+pnpm exec paperclipai auth challenge create --payload-json '{...}'+PAPERCLIP_CHALLENGE_SECRET=<challenge-secret> pnpm exec paperclipai auth challenge get <challenge-id> --token-env PAPERCLIP_CHALLENGE_SECRET+PAPERCLIP_CHALLENGE_SECRET=<challenge-secret> pnpm exec paperclipai auth challenge approve <challenge-id> --token-env PAPERCLIP_CHALLENGE_SECRET+PAPERCLIP_CHALLENGE_SECRET=<challenge-secret> pnpm exec paperclipai auth challenge cancel <challenge-id> --token-env PAPERCLIP_CHALLENGE_SECRET+pnpm exec paperclipai auth revoke-current````--token <challenge-secret>` is still supported for compatibility, but `--token-env` avoids putting challenge secrets in shell history or process arguments.@@ -740,33 +790,33 @@ pnpm paperclipai auth revoke-current## Instance Settings Commands```sh-pnpm paperclipai instance scheduler-heartbeats-pnpm paperclipai instance settings:general-pnpm paperclipai instance settings:general:update --payload-json '{...}'-pnpm paperclipai instance settings:experimental-pnpm paperclipai instance settings:experimental:update --payload-json '{...}'-pnpm paperclipai instance database-backup+pnpm exec paperclipai instance scheduler-heartbeats+pnpm exec paperclipai instance settings:general+pnpm exec paperclipai instance settings:general:update --payload-json '{...}'+pnpm exec paperclipai instance settings:experimental+pnpm exec paperclipai instance settings:experimental:update --payload-json '{...}'+pnpm exec paperclipai instance database-backup```Experimental features are opt-in and are provided without compatibility guarantees. They may break, change, or be removed at any time. Use them at your own risk.```sh-pnpm paperclipai sidebar preferences-pnpm paperclipai sidebar preferences:update --payload-json '{...}'-pnpm paperclipai sidebar project-preferences --company-id <company-id>-pnpm paperclipai sidebar project-preferences:update --company-id <company-id> --payload-json '{...}'-pnpm paperclipai sidebar badges --company-id <company-id>-pnpm paperclipai inbox dismissals --company-id <company-id>-pnpm paperclipai inbox dismiss --company-id <company-id> --payload-json '{"itemKey":"run:<run-id>"}'-pnpm paperclipai board-claim show <token>-pnpm paperclipai board-claim claim <token> [--payload-json '{...}']-pnpm paperclipai openclaw invite-prompt --company-id <company-id> --payload-json '{...}'-pnpm paperclipai available-skill list-pnpm paperclipai available-skill index-pnpm paperclipai available-skill get <skill-name>-pnpm paperclipai llm agent-configuration-pnpm paperclipai llm agent-configuration:adapter <adapter-type>-pnpm paperclipai llm agent-icons+pnpm exec paperclipai sidebar preferences+pnpm exec paperclipai sidebar preferences:update --payload-json '{...}'+pnpm exec paperclipai sidebar project-preferences --company-id <company-id>+pnpm exec paperclipai sidebar project-preferences:update --company-id <company-id> --payload-json '{...}'+pnpm exec paperclipai sidebar badges --company-id <company-id>+pnpm exec paperclipai inbox dismissals --company-id <company-id>+pnpm exec paperclipai inbox dismiss --company-id <company-id> --payload-json '{"itemKey":"run:<run-id>"}'+pnpm exec paperclipai board-claim show <token>+pnpm exec paperclipai board-claim claim <token> [--payload-json '{...}']+pnpm exec paperclipai openclaw invite-prompt --company-id <company-id> --payload-json '{...}'+pnpm exec paperclipai available-skill list+pnpm exec paperclipai available-skill index+pnpm exec paperclipai available-skill get <skill-name>+pnpm exec paperclipai llm agent-configuration+pnpm exec paperclipai llm agent-configuration:adapter <adapter-type>+pnpm exec paperclipai llm agent-icons```Hermes gateway uses the generic invite/join commands above rather than@@ -779,101 +829,101 @@ commands. See [HERMES_GATEWAY_ONBOARDING.md](./HERMES_GATEWAY_ONBOARDING.md).## Adapter, Asset, And Skill Commands```sh-pnpm paperclipai adapter list-pnpm paperclipai adapter install --payload-json '{"packageName":"@scope/adapter","version":"1.2.3"}'-pnpm paperclipai adapter get <adapter-type>-pnpm paperclipai adapter update <adapter-type> --payload-json '{"disabled":true}'-pnpm paperclipai adapter override <adapter-type> --payload-json '{"paused":true}'-pnpm paperclipai adapter reload <adapter-type>-pnpm paperclipai adapter reinstall <adapter-type>-pnpm paperclipai adapter delete <adapter-type>-pnpm paperclipai adapter config-schema <adapter-type>-pnpm paperclipai adapter ui-parser <adapter-type>-pnpm paperclipai adapter models <adapter-type> --company-id <company-id> [--refresh] [--environment-id <id>]-pnpm paperclipai adapter model-profiles <adapter-type> --company-id <company-id>-pnpm paperclipai adapter detect-model <adapter-type> --company-id <company-id>-pnpm paperclipai adapter test-environment <adapter-type> --company-id <company-id> --payload-json '{...}'+pnpm exec paperclipai adapter list+pnpm exec paperclipai adapter install --payload-json '{"packageName":"@scope/adapter","version":"1.2.3"}'+pnpm exec paperclipai adapter get <adapter-type>+pnpm exec paperclipai adapter update <adapter-type> --payload-json '{"disabled":true}'+pnpm exec paperclipai adapter override <adapter-type> --payload-json '{"paused":true}'+pnpm exec paperclipai adapter reload <adapter-type>+pnpm exec paperclipai adapter reinstall <adapter-type>+pnpm exec paperclipai adapter delete <adapter-type>+pnpm exec paperclipai adapter config-schema <adapter-type>+pnpm exec paperclipai adapter ui-parser <adapter-type>+pnpm exec paperclipai adapter models <adapter-type> --company-id <company-id> [--refresh] [--environment-id <id>]+pnpm exec paperclipai adapter model-profiles <adapter-type> --company-id <company-id>+pnpm exec paperclipai adapter detect-model <adapter-type> --company-id <company-id>+pnpm exec paperclipai adapter test-environment <adapter-type> --company-id <company-id> --payload-json '{...}'``````sh-pnpm paperclipai asset image:upload --company-id <company-id> --file ./image.png [--namespace docs] [--alt "..."]-pnpm paperclipai asset logo:upload --company-id <company-id> --file ./logo.svg-pnpm paperclipai asset content <asset-id> --out ./asset.bin+pnpm exec paperclipai asset image:upload --company-id <company-id> --file ./image.png [--namespace docs] [--alt "..."]+pnpm exec paperclipai asset logo:upload --company-id <company-id> --file ./logo.svg+pnpm exec paperclipai asset content <asset-id> --out ./asset.bin``````sh-pnpm paperclipai skill list --company-id <company-id>-pnpm paperclipai skill get <skill-id> --company-id <company-id>-pnpm paperclipai skill file <skill-id> --company-id <company-id> [--path SKILL.md]-pnpm paperclipai skill create --company-id <company-id> --payload-json '{...}'-pnpm paperclipai skill file:update <skill-id> --company-id <company-id> --payload-json '{...}'-pnpm paperclipai skill import --company-id <company-id> --payload-json '{"source":"github:owner/repo/path"}'-pnpm paperclipai skill scan-projects --company-id <company-id> --payload-json '{...}'-pnpm paperclipai skill update-status <skill-id> --company-id <company-id>-pnpm paperclipai skill install-update <skill-id> --company-id <company-id>-pnpm paperclipai skill delete <skill-id> --company-id <company-id>+pnpm exec paperclipai skill list --company-id <company-id>+pnpm exec paperclipai skill get <skill-id> --company-id <company-id>+pnpm exec paperclipai skill file <skill-id> --company-id <company-id> [--path SKILL.md]+pnpm exec paperclipai skill create --company-id <company-id> --payload-json '{...}'+pnpm exec paperclipai skill file:update <skill-id> --company-id <company-id> --payload-json '{...}'+pnpm exec paperclipai skill import --company-id <company-id> --payload-json '{"source":"github:owner/repo/path"}'+pnpm exec paperclipai skill scan-projects --company-id <company-id> --payload-json '{...}'+pnpm exec paperclipai skill update-status <skill-id> --company-id <company-id>+pnpm exec paperclipai skill install-update <skill-id> --company-id <company-id>+pnpm exec paperclipai skill delete <skill-id> --company-id <company-id>```## Cost, Finance, And Budget Commands```sh-pnpm paperclipai cost summary --company-id <company-id>-pnpm paperclipai cost by-agent --company-id <company-id>-pnpm paperclipai cost by-agent-model --company-id <company-id>-pnpm paperclipai cost by-provider --company-id <company-id>-pnpm paperclipai cost by-biller --company-id <company-id>-pnpm paperclipai cost by-project --company-id <company-id>-pnpm paperclipai cost window-spend --company-id <company-id>-pnpm paperclipai cost quota-windows --company-id <company-id>-pnpm paperclipai cost issue <issue-id>-pnpm paperclipai cost event:create --company-id <company-id> --payload-json '{...}'+pnpm exec paperclipai cost summary --company-id <company-id>+pnpm exec paperclipai cost by-agent --company-id <company-id>+pnpm exec paperclipai cost by-agent-model --company-id <company-id>+pnpm exec paperclipai cost by-provider --company-id <company-id>+pnpm exec paperclipai cost by-biller --company-id <company-id>+pnpm exec paperclipai cost by-project --company-id <company-id>+pnpm exec paperclipai cost window-spend --company-id <company-id>+pnpm exec paperclipai cost quota-windows --company-id <company-id>+pnpm exec paperclipai cost issue <issue-id>+pnpm exec paperclipai cost event:create --company-id <company-id> --payload-json '{...}'``````sh-pnpm paperclipai finance event:create --company-id <company-id> --payload-json '{...}'-pnpm paperclipai finance events --company-id <company-id>-pnpm paperclipai finance summary --company-id <company-id>-pnpm paperclipai finance by-biller --company-id <company-id>-pnpm paperclipai finance by-kind --company-id <company-id>-pnpm paperclipai budget overview --company-id <company-id>-pnpm paperclipai budget policy:upsert --company-id <company-id> --payload-json '{...}'-pnpm paperclipai budget company:update --company-id <company-id> --payload-json '{...}'-pnpm paperclipai budget agent:update <agent-id> --payload-json '{...}'-pnpm paperclipai budget incident:resolve <incident-id> --company-id <company-id> [--payload-json '{...}']+pnpm exec paperclipai finance event:create --company-id <company-id> --payload-json '{...}'+pnpm exec paperclipai finance events --company-id <company-id>+pnpm exec paperclipai finance summary --company-id <company-id>+pnpm exec paperclipai finance by-biller --company-id <company-id>+pnpm exec paperclipai finance by-kind --company-id <company-id>+pnpm exec paperclipai budget overview --company-id <company-id>+pnpm exec paperclipai budget policy:upsert --company-id <company-id> --payload-json '{...}'+pnpm exec paperclipai budget company:update --company-id <company-id> --payload-json '{...}'+pnpm exec paperclipai budget agent:update <agent-id> --payload-json '{...}'+pnpm exec paperclipai budget incident:resolve <incident-id> --company-id <company-id> [--payload-json '{...}']```## Workspace And Environment Commands```sh-pnpm paperclipai workspace list --company-id <company-id>-pnpm paperclipai workspace get <execution-workspace-id>-pnpm paperclipai workspace close-readiness <execution-workspace-id>-pnpm paperclipai workspace operations <execution-workspace-id>-pnpm paperclipai workspace update <execution-workspace-id> --payload-json '{...}'-pnpm paperclipai workspace runtime-service <execution-workspace-id> start --payload-json '{...}'-pnpm paperclipai workspace runtime-command <execution-workspace-id> run --payload-json '{...}'+pnpm exec paperclipai workspace list --company-id <company-id>+pnpm exec paperclipai workspace get <execution-workspace-id>+pnpm exec paperclipai workspace close-readiness <execution-workspace-id>+pnpm exec paperclipai workspace operations <execution-workspace-id>+pnpm exec paperclipai workspace update <execution-workspace-id> --payload-json '{...}'+pnpm exec paperclipai workspace runtime-service <execution-workspace-id> start --payload-json '{...}'+pnpm exec paperclipai workspace runtime-command <execution-workspace-id> run --payload-json '{...}'``````sh-pnpm paperclipai environment list --company-id <company-id>-pnpm paperclipai environment capabilities --company-id <company-id>-pnpm paperclipai environment create --company-id <company-id> --payload-json '{...}'-pnpm paperclipai environment get <environment-id>-pnpm paperclipai environment leases <environment-id>-pnpm paperclipai environment lease <lease-id>-pnpm paperclipai environment update <environment-id> --payload-json '{...}'-pnpm paperclipai environment delete <environment-id>-pnpm paperclipai environment probe <environment-id>-pnpm paperclipai environment probe-config --company-id <company-id> --payload-json '{...}'+pnpm exec paperclipai environment list --company-id <company-id>+pnpm exec paperclipai environment capabilities --company-id <company-id>+pnpm exec paperclipai environment create --company-id <company-id> --payload-json '{...}'+pnpm exec paperclipai environment get <environment-id>+pnpm exec paperclipai environment leases <environment-id>+pnpm exec paperclipai environment lease <lease-id>+pnpm exec paperclipai environment update <environment-id> --payload-json '{...}'+pnpm exec paperclipai environment delete <environment-id>+pnpm exec paperclipai environment probe <environment-id>+pnpm exec paperclipai environment probe-config --company-id <company-id> --payload-json '{...}'``````sh-pnpm paperclipai project-workspace list <project-id>-pnpm paperclipai project-workspace create <project-id> --payload-json '{...}'-pnpm paperclipai project-workspace update <project-id> <workspace-id> --payload-json '{...}'-pnpm paperclipai project-workspace delete <project-id> <workspace-id>-pnpm paperclipai project-workspace runtime-service <project-id> <workspace-id> restart --payload-json '{...}'-pnpm paperclipai project-workspace runtime-command <project-id> <workspace-id> run --payload-json '{...}'+pnpm exec paperclipai project-workspace list <project-id>+pnpm exec paperclipai project-workspace create <project-id> --payload-json '{...}'+pnpm exec paperclipai project-workspace update <project-id> <workspace-id> --payload-json '{...}'+pnpm exec paperclipai project-workspace delete <project-id> <workspace-id>+pnpm exec paperclipai project-workspace runtime-service <project-id> <workspace-id> restart --payload-json '{...}'+pnpm exec paperclipai project-workspace runtime-command <project-id> <workspace-id> run --payload-json '{...}'```## Plugin Commands@@ -881,36 +931,36 @@ pnpm paperclipai project-workspace runtime-command <project-id> <workspace-id> rExisting plugin lifecycle commands remain available: `plugin init`, `list`, `install`, `uninstall`, `enable`, `disable`, `inspect`, and `examples`.```sh-pnpm paperclipai plugin ui-contributions-pnpm paperclipai plugin tools-pnpm paperclipai plugin tool:execute --payload-json '{...}'-pnpm paperclipai plugin health <plugin-id>-pnpm paperclipai plugin logs <plugin-id>-pnpm paperclipai plugin upgrade <plugin-id>-pnpm paperclipai plugin config <plugin-id> --company-id <company-id>-pnpm paperclipai plugin config:set <plugin-id> --company-id <company-id> --payload-json '{"configJson":{...}}'-pnpm paperclipai plugin config:test <plugin-id> --company-id <company-id> --payload-json '{"configJson":{...}}'-pnpm paperclipai plugin jobs <plugin-id>-pnpm paperclipai plugin job:runs <plugin-id> <job-id>-pnpm paperclipai plugin job:trigger <plugin-id> <job-id> [--payload-json '{...}']-pnpm paperclipai plugin webhook <plugin-id> <endpoint-key> [--payload-json '{...}']-pnpm paperclipai plugin dashboard <plugin-id>-pnpm paperclipai plugin bridge:data <plugin-id> --payload-json '{...}'-pnpm paperclipai plugin bridge:action <plugin-id> --payload-json '{...}'-pnpm paperclipai plugin bridge:stream <plugin-id> <channel> [--duration-ms 10000]-pnpm paperclipai plugin data <plugin-id> <key> --payload-json '{...}'-pnpm paperclipai plugin action <plugin-id> <key> --payload-json '{...}'-pnpm paperclipai plugin local-folders <plugin-id> --company-id <company-id>-pnpm paperclipai plugin local-folder:status <plugin-id> <folder-key> --company-id <company-id>-pnpm paperclipai plugin local-folder:validate <plugin-id> <folder-key> --company-id <company-id> [--payload-json '{...}']-pnpm paperclipai plugin local-folder:set <plugin-id> <folder-key> --company-id <company-id> --payload-json '{...}'+pnpm exec paperclipai plugin ui-contributions+pnpm exec paperclipai plugin tools+pnpm exec paperclipai plugin tool:execute --payload-json '{...}'+pnpm exec paperclipai plugin health <plugin-id>+pnpm exec paperclipai plugin logs <plugin-id>+pnpm exec paperclipai plugin upgrade <plugin-id>+pnpm exec paperclipai plugin config <plugin-id> --company-id <company-id>+pnpm exec paperclipai plugin config:set <plugin-id> --company-id <company-id> --payload-json '{"configJson":{...}}'+pnpm exec paperclipai plugin config:test <plugin-id> --company-id <company-id> --payload-json '{"configJson":{...}}'+pnpm exec paperclipai plugin jobs <plugin-id>+pnpm exec paperclipai plugin job:runs <plugin-id> <job-id>+pnpm exec paperclipai plugin job:trigger <plugin-id> <job-id> [--payload-json '{...}']+pnpm exec paperclipai plugin webhook <plugin-id> <endpoint-key> [--payload-json '{...}']+pnpm exec paperclipai plugin dashboard <plugin-id>+pnpm exec paperclipai plugin bridge:data <plugin-id> --payload-json '{...}'+pnpm exec paperclipai plugin bridge:action <plugin-id> --payload-json '{...}'+pnpm exec paperclipai plugin bridge:stream <plugin-id> <channel> [--duration-ms 10000]+pnpm exec paperclipai plugin data <plugin-id> <key> --payload-json '{...}'+pnpm exec paperclipai plugin action <plugin-id> <key> --payload-json '{...}'+pnpm exec paperclipai plugin local-folders <plugin-id> --company-id <company-id>+pnpm exec paperclipai plugin local-folder:status <plugin-id> <folder-key> --company-id <company-id>+pnpm exec paperclipai plugin local-folder:validate <plugin-id> <folder-key> --company-id <company-id> [--payload-json '{...}']+pnpm exec paperclipai plugin local-folder:set <plugin-id> <folder-key> --company-id <company-id> --payload-json '{...}'```Feedback traces can be fetched directly by ID when automating export workflows:```sh-pnpm paperclipai feedback trace <trace-id>-pnpm paperclipai feedback bundle <trace-id>+pnpm exec paperclipai feedback trace <trace-id>+pnpm exec paperclipai feedback bundle <trace-id>```## Heartbeat Command@@ -918,7 +968,7 @@ pnpm paperclipai feedback bundle <trace-id>`heartbeat run` now also supports context/api-key options and uses the shared client stack:```sh-pnpm paperclipai heartbeat run --agent-id <agent-id> [--api-base http://localhost:3100] [--api-key <token>]+pnpm exec paperclipai heartbeat run --agent-id <agent-id> [--api-base http://localhost:3100] [--api-key <token>]```## Local Storage Defaultsdiff --git a/doc/DATABASE.md b/doc/DATABASE.mdindex 6c80f1f500..18a7208f20 100644--- a/doc/DATABASE.md+++ b/doc/DATABASE.md@@ -267,7 +267,7 @@ pnpm paperclipai configure --section secretsInline secret migration command:```sh-pnpm paperclipai secrets migrate-inline-env --company-id <company-id> --apply+pnpm exec paperclipai secrets migrate-inline-env --company-id <company-id> --apply# direct database maintenance fallbackpnpm secrets:migrate-inline-env --applydiff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.mdindex ac53ac1b4f..d446e818a8 100644--- a/doc/DEVELOPING.md+++ b/doc/DEVELOPING.md@@ -230,7 +230,7 @@ pnpm dev --authenticated-privateAllow additional private hostnames (for example custom Tailscale hostnames):```sh-pnpm paperclipai allowed-hostname dotta-macbook-pro+pnpm exec paperclipai allowed-hostname dotta-macbook-pro```## Test Commands@@ -537,7 +537,7 @@ Repair an already-created repo-managed worktree and reseed its isolated instance```shcd /path/to/paperclip/.paperclip/worktrees/PAP-884-ai-commits-component-pnpm paperclipai worktree init --force --seed-mode minimal \+pnpm exec paperclipai worktree init --force --seed-mode minimal \--name PAP-884-ai-commits-component \--from-config ~/.paperclip/instances/default/config.json```@@ -869,15 +869,15 @@ Paperclip CLI now includes client-side control-plane commands in addition to setQuick examples:```sh-pnpm paperclipai issue list --company-id <company-id>-pnpm paperclipai issue create --company-id <company-id> --title "Investigate checkout conflict"-pnpm paperclipai issue update <issue-id> --status in_progress --comment "Started triage"+pnpm exec paperclipai issue list --company-id <company-id>+pnpm exec paperclipai issue create --company-id <company-id> --title "Investigate checkout conflict"+pnpm exec paperclipai issue update <issue-id> --status in_progress --comment "Started triage"```Set defaults once with context profiles:```sh-pnpm paperclipai context set --api-base http://localhost:3100 --company-id <company-id>+pnpm exec paperclipai context set --api-base http://localhost:3100 --company-id <company-id>```Then run commands without repeating flags:@@ -961,4 +961,4 @@ Networking behavior for this smoke script:- auto-detects and prints a Paperclip host URL reachable from inside OpenClaw Docker- default container-side host alias is `host.docker.internal` (override with `PAPERCLIP_HOST_FROM_CONTAINER` / `PAPERCLIP_HOST_PORT`)-- if Paperclip rejects container hostnames in authenticated/private mode, allow `host.docker.internal` via `pnpm paperclipai allowed-hostname host.docker.internal` and restart Paperclip+- if Paperclip rejects container hostnames in authenticated/private mode, allow `host.docker.internal` via `pnpm exec paperclipai allowed-hostname host.docker.internal` and restart Paperclipdiff --git a/doc/HERMES_GATEWAY_ONBOARDING.md b/doc/HERMES_GATEWAY_ONBOARDING.mdindex 58b9dfc5b0..29d9385516 100644--- a/doc/HERMES_GATEWAY_ONBOARDING.md+++ b/doc/HERMES_GATEWAY_ONBOARDING.md@@ -79,9 +79,9 @@ The UI prompt points Hermes at the same machine-readable onboarding endpoints:For CLI-driven setup, create and inspect the invite directly:```sh-pnpm paperclipai invite create --company-id <company-id> --payload-json '{"requestType":"agent"}'-pnpm paperclipai invite show <token>-pnpm paperclipai invite onboarding:text <token>+pnpm exec paperclipai invite create --company-id <company-id> --payload-json '{"requestType":"agent"}'+pnpm exec paperclipai invite show <token>+pnpm exec paperclipai invite onboarding:text <token>```Hermes should submit a join request with `requestType: "agent"` and@@ -119,14 +119,14 @@ After Hermes submits the join request:2. Approve it from the board UI, or use:```sh- pnpm paperclipai join list --company-id <company-id> --status pending_approval- pnpm paperclipai join approve <request-id> --company-id <company-id>+ pnpm exec paperclipai join list --company-id <company-id> --status pending_approval+ pnpm exec paperclipai join approve <request-id> --company-id <company-id>```3. Hermes claims the one-time agent API key:```sh- pnpm paperclipai join claim-key <request-id> --claim-secret <secret>+ pnpm exec paperclipai join claim-key <request-id> --claim-secret <secret>```4. Store the claimed Paperclip key in Hermes runtime state or secrets. The claim@@ -182,7 +182,7 @@ Use these entry points depending on who is driving setup:onboarding prompt.- Invite API: `GET /api/invites/:token/onboarding.txt` for the generatedllm.txt-style setup instructions.-- CLI invite flow: `pnpm paperclipai invite create`, `invite show`,+- CLI invite flow: `pnpm exec paperclipai invite create`, `invite show`,`invite onboarding:text`, `join approve`, and `join claim-key`.- Smoke helpers: `pnpm smoke:hermes-gateway-e2e` for fresh-state Dockerverification and `pnpm smoke:hermes-gateway-join` for an already-runningdiff --git a/docs/adapters/claude-local.md b/docs/adapters/claude-local.mdindex 1a13d0459c..a154327f5d 100644--- a/docs/adapters/claude-local.md+++ b/docs/adapters/claude-local.md@@ -102,7 +102,7 @@ therefore shadows any Codex login already present inside the sandbox image.For manual local CLI usage outside heartbeat runs (for example running as `claudecoder` directly), use:```sh-pnpm paperclipai agent local-cli claudecoder --company-id <company-id>+pnpm exec paperclipai agent local-cli claudecoder --company-id <company-id>```This installs Paperclip skills in `~/.claude/skills`, creates an agent API key, and prints shell exports to run as that agent.diff --git a/docs/adapters/codex-local.md b/docs/adapters/codex-local.mdindex 5a539f150e..526ce11013 100644--- a/docs/adapters/codex-local.md+++ b/docs/adapters/codex-local.md@@ -141,7 +141,7 @@ change.For manual local CLI usage outside heartbeat runs (for example running as `codexcoder` directly), use:```sh-pnpm paperclipai agent local-cli codexcoder --company-id <company-id>+pnpm exec paperclipai agent local-cli codexcoder --company-id <company-id>```This installs any missing skills, creates an agent API key, and prints shell exports to run as that agent.diff --git a/docs/api/secrets.md b/docs/api/secrets.mdindex 0369922928..2e4a9c017e 100644--- a/docs/api/secrets.md+++ b/docs/api/secrets.md@@ -114,7 +114,7 @@ credentials must not be stored in Paperclip `company_secrets`.The equivalent CLI check is:```sh-pnpm paperclipai secrets doctor --company-id {companyId}+pnpm exec paperclipai secrets doctor --company-id {companyId}```## Provider Vaults@@ -485,7 +485,7 @@ as declarations in the package manifest. Exports omit secret values, secret IDs,provider references, and encrypted provider material. Use:```sh-pnpm paperclipai secrets declarations --company-id {companyId}+pnpm exec paperclipai secrets declarations --company-id {companyId}```to inspect the declarations that an export would emit before moving a package.diff --git a/docs/cli/control-plane-commands.md b/docs/cli/control-plane-commands.mdindex 70adf99ad2..f2ac4908f0 100644--- a/docs/cli/control-plane-commands.md+++ b/docs/cli/control-plane-commands.md@@ -9,39 +9,39 @@ Client-side commands for managing issues, agents, approvals, and more.```sh# List issues-pnpm paperclipai issue list [--status todo,in_progress] [--assignee-agent-id <id>] [--match text]+pnpm exec paperclipai issue list [--status todo,in_progress] [--assignee-agent-id <id>] [--match text]# Get issue details-pnpm paperclipai issue get <issue-id-or-identifier>+pnpm exec paperclipai issue get <issue-id-or-identifier># Create issue-pnpm paperclipai issue create --title "..." [--description "..."] [--status todo] [--priority high]+pnpm exec paperclipai issue create --title "..." [--description "..."] [--status todo] [--priority high]# Update issue-pnpm paperclipai issue update <issue-id> [--status in_progress] [--comment "..."]+pnpm exec paperclipai issue update <issue-id> [--status in_progress] [--comment "..."]# Add comment-pnpm paperclipai issue comment <issue-id> --body "..." [--reopen]+pnpm exec paperclipai issue comment <issue-id> --body "..." [--reopen]# Checkout task-pnpm paperclipai issue checkout <issue-id> --agent-id <agent-id>+pnpm exec paperclipai issue checkout <issue-id> --agent-id <agent-id># Release task-pnpm paperclipai issue release <issue-id>+pnpm exec paperclipai issue release <issue-id>```## Company Commands```sh-pnpm paperclipai company list-pnpm paperclipai company get <company-id>-pnpm paperclipai company current [--company-id <company-id>]+pnpm exec paperclipai company list+pnpm exec paperclipai company get <company-id>+pnpm exec paperclipai company current [--company-id <company-id>]# Export to portable folder package (writes manifest + markdown files)-pnpm paperclipai company export <company-id> --out ./exports/acme --include company,agents+pnpm exec paperclipai company export <company-id> --out ./exports/acme --include company,agents# Preview import (no writes)-pnpm paperclipai company import \+pnpm exec paperclipai company import \<owner>/<repo>/<path> \--target existing \--company-id <company-id> \@@ -50,7 +50,7 @@ pnpm paperclipai company import \--dry-run# Apply import-pnpm paperclipai company import \+pnpm exec paperclipai company import \./exports/acme \--target new \--new-company-name "Acme Imported" \@@ -67,80 +67,80 @@ command.## Agent Commands```sh-pnpm paperclipai agent list-pnpm paperclipai agent get <agent-id>+pnpm exec paperclipai agent list+pnpm exec paperclipai agent get <agent-id>```## Skills Commands```sh# Browse app-shipped catalog skills without changing company state-pnpm paperclipai skills browse [--kind bundled|optional] [--category software-development] [--query github]-pnpm paperclipai skills search "pull request" [--json]+pnpm exec paperclipai skills browse [--kind bundled|optional] [--category software-development] [--query github]+pnpm exec paperclipai skills search "pull request" [--json]# Inspect catalog metadata and file inventory before install-pnpm paperclipai skills inspect github-pr-workflow+pnpm exec paperclipai skills inspect github-pr-workflow# Install a catalog skill into the company skill library# This does not attach the skill to any agent.-pnpm paperclipai skills install github-pr-workflow --company-id <company-id>-pnpm paperclipai skills install github-pr-workflow --as pr-flow --force --company-id <company-id>+pnpm exec paperclipai skills install github-pr-workflow --company-id <company-id>+pnpm exec paperclipai skills install github-pr-workflow --as pr-flow --force --company-id <company-id># External sources still use import instead of catalog install-pnpm paperclipai skills import ./skills/my-skill --company-id <company-id>-pnpm paperclipai skills import owner/repo/path/to/skill --company-id <company-id>+pnpm exec paperclipai skills import ./skills/my-skill --company-id <company-id>+pnpm exec paperclipai skills import owner/repo/path/to/skill --company-id <company-id># Attach desired company skills to an agent after install/import-pnpm paperclipai skills agent sync <agent-id> --skill github-pr-workflow --mode add --company-id <company-id>+pnpm exec paperclipai skills agent sync <agent-id> --skill github-pr-workflow --mode add --company-id <company-id>```## Approval Commands```sh# List approvals-pnpm paperclipai approval list [--status pending]+pnpm exec paperclipai approval list [--status pending]# Get approval-pnpm paperclipai approval get <approval-id>+pnpm exec paperclipai approval get <approval-id># Create approval-pnpm paperclipai approval create --type hire_agent --payload '{"name":"..."}' [--issue-ids <id1,id2>]+pnpm exec paperclipai approval create --type hire_agent --payload '{"name":"..."}' [--issue-ids <id1,id2>]# Approve-pnpm paperclipai approval approve <approval-id> [--decision-note "..."]+pnpm exec paperclipai approval approve <approval-id> [--decision-note "..."]# Reject-pnpm paperclipai approval reject <approval-id> [--decision-note "..."]+pnpm exec paperclipai approval reject <approval-id> [--decision-note "..."]# Request revision-pnpm paperclipai approval request-revision <approval-id> [--decision-note "..."]+pnpm exec paperclipai approval request-revision <approval-id> [--decision-note "..."]# Resubmit-pnpm paperclipai approval resubmit <approval-id> [--payload '{"..."}']+pnpm exec paperclipai approval resubmit <approval-id> [--payload '{"..."}']# Comment-pnpm paperclipai approval comment <approval-id> --body "..."+pnpm exec paperclipai approval comment <approval-id> --body "..."```## Activity Commands```sh-pnpm paperclipai activity list [--agent-id <id>] [--entity-type issue] [--entity-id <id>]+pnpm exec paperclipai activity list [--agent-id <id>] [--entity-type issue] [--entity-id <id>]```## Dashboard```sh-pnpm paperclipai dashboard get+pnpm exec paperclipai dashboard get```## Instance Settings```sh-pnpm paperclipai instance settings:general-pnpm paperclipai instance settings:general:update --payload-json '{...}'-pnpm paperclipai instance settings:experimental-pnpm paperclipai instance settings:experimental:update --payload-json '{...}'+pnpm exec paperclipai instance settings:general+pnpm exec paperclipai instance settings:general:update --payload-json '{...}'+pnpm exec paperclipai instance settings:experimental+pnpm exec paperclipai instance settings:experimental:update --payload-json '{...}'```Experimental features are opt-in and are provided without compatibility guarantees. They may break, change, or be removed at any time. Use them at your own risk.@@ -148,5 +148,5 @@ Experimental features are opt-in and are provided without compatibility guarante## Heartbeat```sh-pnpm paperclipai heartbeat run --agent-id <agent-id> [--api-base http://localhost:3100]+pnpm exec paperclipai heartbeat run --agent-id <agent-id> [--api-base http://localhost:3100]```diff --git a/docs/cli/overview.md b/docs/cli/overview.mdindex f160832b8f..e580d5d4ba 100644--- a/docs/cli/overview.md+++ b/docs/cli/overview.md@@ -38,7 +38,7 @@ Store defaults to avoid repeating flags:```sh# Set defaults-pnpm paperclipai context set --api-base http://localhost:3100 --company-id <id>+pnpm exec paperclipai context set --api-base http://localhost:3100 --company-id <id># View current contextpnpm paperclipai context show@@ -53,18 +53,18 @@ pnpm paperclipai context use defaultTo avoid storing secrets in context, use an env var:```sh-pnpm paperclipai context set --api-key-env-var-name PAPERCLIP_API_KEY+pnpm exec paperclipai context set --api-key-env-var-name PAPERCLIP_API_KEYexport PAPERCLIP_API_KEY=...```Secret operations are available under `paperclipai secrets`:```sh-pnpm paperclipai secrets declarations --company-id <company-id> --kind secret-pnpm paperclipai secrets create --company-id <company-id> --name anthropic-api-key --value-env ANTHROPIC_API_KEY-pnpm paperclipai secrets link --company-id <company-id> --name prod-stripe-key --provider aws_secrets_manager --external-ref <provider-ref>-pnpm paperclipai secrets doctor --company-id <company-id>-pnpm paperclipai secrets migrate-inline-env --company-id <company-id> --apply+pnpm exec paperclipai secrets declarations --company-id <company-id> --kind secret+pnpm exec paperclipai secrets create --company-id <company-id> --name anthropic-api-key --value-env ANTHROPIC_API_KEY+pnpm exec paperclipai secrets link --company-id <company-id> --name prod-stripe-key --provider aws_secrets_manager --external-ref <provider-ref>+pnpm exec paperclipai secrets doctor --company-id <company-id>+pnpm exec paperclipai secrets migrate-inline-env --company-id <company-id> --apply```Context is stored at `~/.paperclip/context.json`.diff --git a/docs/cli/setup-commands.md b/docs/cli/setup-commands.mdindex f6284aba01..bf0dfca636 100644--- a/docs/cli/setup-commands.md+++ b/docs/cli/setup-commands.md@@ -104,7 +104,7 @@ This now includes bind-oriented deployment settings such as `PAPERCLIP_BIND` andAllow a private hostname for authenticated/private mode:```sh-pnpm paperclipai allowed-hostname my-tailscale-host+pnpm exec paperclipai allowed-hostname my-tailscale-host```## Local Storage Pathsdiff --git a/docs/deploy/deployment-modes.md b/docs/deploy/deployment-modes.mdindex 7d5e6032f6..b346d7f462 100644--- a/docs/deploy/deployment-modes.md+++ b/docs/deploy/deployment-modes.md@@ -42,7 +42,7 @@ pnpm paperclipai onboardAllow custom Tailscale hostnames:```sh-pnpm paperclipai allowed-hostname my-machine+pnpm exec paperclipai allowed-hostname my-machine```### `authenticated` + `public`diff --git a/docs/deploy/local-development.md b/docs/deploy/local-development.mdindex 950b572e03..e8c257601b 100644--- a/docs/deploy/local-development.md+++ b/docs/deploy/local-development.md@@ -64,7 +64,7 @@ pnpm dev --authenticated-privateAllow additional private hostnames:```sh-pnpm paperclipai allowed-hostname dotta-macbook-pro+pnpm exec paperclipai allowed-hostname dotta-macbook-pro```For full setup and troubleshooting, see [Tailscale Private Access](/deploy/tailscale-private-access).diff --git a/docs/deploy/secrets.md b/docs/deploy/secrets.mdindex e557086ebf..7fdb3f0c16 100644--- a/docs/deploy/secrets.md+++ b/docs/deploy/secrets.md@@ -203,7 +203,7 @@ Validate secrets config:```shpnpm paperclipai doctor-pnpm paperclipai secrets doctor --company-id <company-id>+pnpm exec paperclipai secrets doctor --company-id <company-id>```### Environment Overrides@@ -475,8 +475,8 @@ store.If you have existing agents with inline API keys in their config, migrate them to encrypted secret refs:```sh-pnpm paperclipai secrets migrate-inline-env --company-id <company-id>-pnpm paperclipai secrets migrate-inline-env --company-id <company-id> --apply+pnpm exec paperclipai secrets migrate-inline-env --company-id <company-id>+pnpm exec paperclipai secrets migrate-inline-env --company-id <company-id> --apply# low-level script for direct database maintenancepnpm secrets:migrate-inline-env # dry run@@ -493,7 +493,7 @@ Company exports include only environment declarations. They do not includesecret IDs, provider references, encrypted material, or plaintext values.```sh-pnpm paperclipai secrets declarations --company-id <company-id> --kind secret+pnpm exec paperclipai secrets declarations --company-id <company-id> --kind secret```Before importing a package into another instance, use those declarations todiff --git a/docs/deploy/tailscale-private-access.md b/docs/deploy/tailscale-private-access.mdindex bb40fa305a..3a86f9f28c 100644--- a/docs/deploy/tailscale-private-access.md+++ b/docs/deploy/tailscale-private-access.md@@ -58,7 +58,7 @@ http://my-macbook.tailnet.ts.net:3100If you access Paperclip with a custom private hostname, add it to the allowlist:```sh-pnpm paperclipai allowed-hostname my-macbook.tailnet.ts.net+pnpm exec paperclipai allowed-hostname my-macbook.tailnet.ts.net```## 5. Verify the server is reachablediff --git a/docs/feedback-voting.md b/docs/feedback-voting.mdindex 41b17201c8..4c3a56c047 100644--- a/docs/feedback-voting.md+++ b/docs/feedback-voting.md@@ -36,7 +36,7 @@ Shows a color-coded summary: vote counts, per-trace details with reasons, and expaperclipai feedback report# Point to a different server or company-pnpm paperclipai feedback report --api-base http://127.0.0.1:3000 --company-id <company-id>+pnpm exec paperclipai feedback report --api-base http://127.0.0.1:3000 --company-id <company-id># Include raw payload dumps in the reportpnpm paperclipai feedback report --payloads@@ -112,7 +112,7 @@ Exports are full by default. `traces/` keeps the Paperclip envelope, while `full```bash# Custom server and output directory-pnpm paperclipai feedback export --api-base http://127.0.0.1:3000 --company-id <company-id> --out ./my-export+pnpm exec paperclipai feedback export --api-base http://127.0.0.1:3000 --company-id <company-id> --out ./my-export```### Reading an exported tracediff --git a/docs/guides/board-operator/experimental-features.md b/docs/guides/board-operator/experimental-features.mdindex 20b4631d54..f6ebcf84fe 100644--- a/docs/guides/board-operator/experimental-features.md+++ b/docs/guides/board-operator/experimental-features.md@@ -23,7 +23,7 @@ The CLI exposes the same surface:```shpnpm paperclipai instance settings:experimental-pnpm paperclipai instance settings:experimental:update --payload-json '{...}'+pnpm exec paperclipai instance settings:experimental:update --payload-json '{...}'```Those commands change the same opt-in settings that the UI manages.diff --git a/docs/guides/openclaw-docker-setup.md b/docs/guides/openclaw-docker-setup.mdindex bf8d149690..c91fb722ba 100644--- a/docs/guides/openclaw-docker-setup.md+++ b/docs/guides/openclaw-docker-setup.md@@ -82,7 +82,7 @@ PAPERCLIP_COOKIE="your_session_cookie=..." pnpm smoke:openclaw-join- If Paperclip rejects the container-visible host with a hostname error, allow it from host:```bash-pnpm paperclipai allowed-hostname host.docker.internal+pnpm exec paperclipai allowed-hostname host.docker.internal```Then restart Paperclip and rerun the smoke script.@@ -90,7 +90,7 @@ Then restart Paperclip and rerun the smoke script.- Authenticated/private mode: ensure hostnames are in the allowed list when required:```bash-pnpm paperclipai allowed-hostname <host>+pnpm exec paperclipai allowed-hostname <host>```## Prerequisitesdiff --git a/server/src/__tests__/cli-invocation-safety.test.ts b/server/src/__tests__/cli-invocation-safety.test.tsnew file mode 100644index 0000000000..0b05feab47--- /dev/null+++ b/server/src/__tests__/cli-invocation-safety.test.ts@@ -0,0 +1,345 @@+import { readdirSync, readFileSync } from "node:fs";+import path from "node:path";+import { fileURLToPath } from "node:url";+import { describe, expect, it } from "vitest";+import { generateReadme } from "../services/company-export-readme.js";++// The Paperclip CLI is unsafe when an operator or agent runs it through+// `pnpm paperclipai <sub> <arg>` with a content-bearing argument. `pnpm` treats+// `paperclipai` as a `package.json` script and wraps the argument in a+// double-quoted `/bin/sh` string. The shell then runs command substitution (a+// backtick pair or `$( )`) and variable expansion (`$NAME`) before the CLI+// starts. `pnpm exec paperclipai` runs the installed binary directly. It passes+// the argument as an inert argv value and does not run a shell. The safe form+// and the unsafe form differ only by the `exec` keyword.+//+// This guard has two parts. First, it asserts that the runtime surfaces which+// build a CLI instruction from a non-fixed value emit the safe `pnpm exec` form.+// Second, it scans the guidance surfaces across the repository for any+// content-bearing `pnpm paperclipai` example that returned to the docs.++const here = path.dirname(fileURLToPath(import.meta.url));+const repoRoot = path.resolve(here, "../../..");++function read(relPath: string): string {+ return readFileSync(path.join(repoRoot, relPath), "utf8");+}++// ── Content-bearing detection ─────────────────────────────────────────────+//+// A `pnpm paperclipai` line is content-bearing when it carries an argument that+// an agent or operator can fill from untrusted or semi-trusted content: an+// issue body, a comment, Markdown, a pasted snippet, model output, a hostname+// from a request header, an import URL, an identifier, or a secret reference.++// Flags that carry free text, an identifier, a payload, a file, or a secret.+const CONTENT_FLAGS = [+ "--body",+ "--body-file",+ "--title",+ "--comment",+ "--message",+ "--description",+ "--reason",+ "--goal",+ "--alt",+ "--color",+ "--content",+ "--content-file",+ "--summary",+ "--note",+ "--text",+ "--name",+ "--slug",+ "--payload",+ "--payload-json",+ "--env-json",+ "--company-id",+ "--agent-id",+ "--claim-secret",+ "--api-key-env-var-name",+ "--out",+ "--file",+];++// Subcommands whose value is a hostname or an import source. A request header or+// an external URL can supply that value, so it is never fixed.+const CONTENT_SUBCOMMANDS = ["allowed-hostname", "company import"];++// Placeholders that name an untrusted value type. A bare local placeholder such+// as `<name>` or `<plugin-id>` on a local lifecycle command is not listed here.+const UNTRUSTED_PLACEHOLDERS = [+ "<token>",+ "<secret>",+ "<request-id>",+ "this-github-url-or-folder",+];++// A note or warning line names the unsafe form on purpose. Skip it so the+// security note itself does not trip the scan.+function isNoteLine(line: string): boolean {+ const lower = line.toLowerCase();+ return (+ line.includes("pnpm exec paperclipai") ||+ line.includes("npx paperclipai") ||+ lower.includes("do not use") ||+ lower.includes("acceptable only")+ );+}++function isContentBearing(line: string): boolean {+ const commandStart = line.indexOf("pnpm paperclipai");+ if (commandStart < 0) return false;+ if (isNoteLine(line)) return false;+ // Inspect only the command tail. Wrapping code before the command, such as a+ // `${pc.dim(...)}` template call in TypeScript, is not part of the argument.+ const command = line.slice(commandStart);+ if (command.includes("${")) return true;+ if (command.includes("url-or-folder>") || command.toLowerCase().includes("<url")) return true;+ if (UNTRUSTED_PLACEHOLDERS.some((token) => command.includes(token))) return true;+ if (CONTENT_SUBCOMMANDS.some((sub) => command.includes(sub))) return true;+ return CONTENT_FLAGS.some(+ (flag) => command.includes(`${flag} `) || command.includes(`${flag}=`),+ );+}++// ── Repository walk ───────────────────────────────────────────────────────+//+// The scan covers guidance the reader follows now: documentation, skills, and+// the runtime source that emits CLI instructions. It skips historical records+// and internal automation, because a reader does not copy a command from them:+// `doc/logs` holds past verification logs, `doc/plans` holds dated design+// plans, and `scripts` holds trusted automation with fixed arguments. It skips+// test files, because a test names the unsafe form to assert against it.++const SKIP_DIRS = new Set([+ "node_modules",+ ".git",+ "dist",+ "build",+ ".next",+ "coverage",+ ".paperclip",+ "tmp",+]);++const SKIP_PATH_PREFIXES = ["doc/logs/", "doc/plans/", "scripts/"];++const SCAN_EXTENSIONS = new Set([+ ".md",+ ".mdx",+ ".ts",+ ".tsx",+ ".js",+ ".jsx",+ ".sh",+ ".json",+]);++function isTestFile(relPath: string): boolean {+ return (+ relPath.includes("__tests__/") ||+ /\.(test|spec)\.[tj]sx?$/.test(relPath)+ );+}++function listGuidanceFiles(): string[] {+ const found: string[] = [];++ function walk(absDir: string, relDir: string): void {+ for (const entry of readdirSync(absDir, { withFileTypes: true })) {+ if (entry.isSymbolicLink()) continue;+ const relPath = relDir ? `${relDir}/${entry.name}` : entry.name;+ if (entry.isDirectory()) {+ if (SKIP_DIRS.has(entry.name)) continue;+ walk(path.join(absDir, entry.name), relPath);+ continue;+ }+ if (!SCAN_EXTENSIONS.has(path.extname(entry.name))) continue;+ if (isTestFile(relPath)) continue;+ if (SKIP_PATH_PREFIXES.some((prefix) => relPath.startsWith(prefix))) continue;+ found.push(relPath);+ }+ }++ walk(repoRoot, "");+ return found;+}++// ── Backslash line continuation ───────────────────────────────────────────+//+// A shell reads a backslash at the end of a line as a line join. So one+// command can spread its content-bearing arguments across many physical+// lines. The scan must see the whole command, not one physical line. If it+// checks each physical line alone, a `pnpm paperclipai` command whose unsafe+// argument sits on a later line passes undetected.+//+// `toLogicalLines` joins each backslash-continued physical line to the next+// one. It returns the joined text and the line number of the first physical+// line, so an offender report still points to the start of the command.++interface LogicalLine {+ text: string;+ lineNumber: number;+}++function toLogicalLines(source: string): LogicalLine[] {+ const physicalLines = source.split("\n");+ const logicalLines: LogicalLine[] = [];+ let buffer: string | null = null;+ let startLine = 0;+ physicalLines.forEach((physicalLine, index) => {+ const continues = /\\\s*$/.test(physicalLine);+ const body = physicalLine.replace(/\\\s*$/, "");+ if (buffer === null) {+ startLine = index + 1;+ buffer = body;+ } else {+ buffer += body;+ }+ if (!continues) {+ logicalLines.push({ text: buffer, lineNumber: startLine });+ buffer = null;+ }+ });+ if (buffer !== null) {+ logicalLines.push({ text: buffer, lineNumber: startLine });+ }+ return logicalLines;+}++function scanText(relPath: string, source: string): string[] {+ const offenders: string[] = [];+ for (const { text, lineNumber } of toLogicalLines(source)) {+ if (isContentBearing(text)) {+ offenders.push(`${relPath}:${lineNumber}: ${text.trim()}`);+ }+ }+ return offenders;+}++function scanForOffenders(): string[] {+ const offenders: string[] = [];+ for (const relPath of listGuidanceFiles()) {+ offenders.push(...scanText(relPath, read(relPath)));+ }+ return offenders;+}++describe("paperclipai CLI invocation safety", () => {+ it("keeps content-bearing pnpm paperclipai examples out of every guidance surface", () => {+ const offenders = scanForOffenders();+ expect(+ offenders,+ `Use \`pnpm exec paperclipai\` for content-bearing arguments:\n${offenders.join("\n")}`,+ ).toEqual([]);+ });++ // ── Direct assertions on the runtime-generated instruction surfaces ──────++ it("emits a static, non-interpolated safe form from the private-hostname guard messages", () => {+ const source = read("server/src/middleware/private-hostname-guard.ts");+ // The blocked-host and missing-host messages must never interpolate the+ // request Host header into the guidance command. An operator or an agent+ // can paste the guidance into a shell, and that outer shell evaluates a+ // metacharacter span in the host before any CLI receives argv. `pnpm exec`+ // does not stop the outer shell. Emit a static `<host>` placeholder only.+ expect(source).toContain("run pnpm exec paperclipai allowed-hostname <host>");+ expect(source).not.toContain("allowed-hostname ${hostname}");+ expect(source).not.toContain("pnpm paperclipai allowed-hostname");+ });++ it("emits a static, non-interpolated safe form from the onboarding access diagnostics", () => {+ const source = read("server/src/routes/access.ts");+ expect(source).not.toMatch(/pnpm paperclipai allowed-hostname/);+ expect(source).toContain("pnpm exec paperclipai allowed-hostname <host>");+ // The onboarding host comes from the request base URL, so a requester+ // controls it. The emitted command must carry a static `<host>` placeholder+ // and never interpolate that value.+ expect(source).not.toMatch(/allowed-hostname \$\{/);+ });++ it("emits the safe form from the agent onboarding prompt", () => {+ const source = read("ui/src/lib/agent-onboarding-prompt.ts");+ expect(source).not.toContain("pnpm paperclipai allowed-hostname");+ expect(source).toContain("pnpm exec paperclipai allowed-hostname <host>");+ });++ it("emits the safe form in the generated company-export README", () => {+ const readme = generateReadme(+ { agents: [], projects: [], skills: [], issues: [] } as never,+ { companyName: "Acme", companyDescription: null },+ );+ expect(readme).toContain("pnpm exec paperclipai company import this-github-url-or-folder");+ expect(readme).not.toContain("pnpm paperclipai company import");+ });++ it("emits the safe form in the company-export preview builder", () => {+ const source = read("ui/src/pages/CompanyExport.tsx");+ expect(source).not.toContain("pnpm paperclipai company import");+ expect(source).toContain("pnpm exec paperclipai company import");+ });++ // ── The safe-invocation note ─────────────────────────────────────────────++ it("documents the safe form in doc/CLI.md", () => {+ const cli = read("doc/CLI.md");+ expect(cli).toContain("Security: safe invocation for content-bearing arguments");+ expect(cli).toContain("pnpm exec paperclipai");+ expect(cli).toContain("inert `argv`");+ });++ it("documents the safe form in the agent-facing skill", () => {+ const skill = read("skills/paperclip/SKILL.md");+ expect(skill).toContain("CLI safety");+ expect(skill).toContain("pnpm exec paperclipai");+ expect(skill).toContain("Do not use `pnpm paperclipai`");+ });++ // ── Backslash line continuation ──────────────────────────────────────────++ it("flags a content-bearing pnpm paperclipai command split across continued lines", () => {+ const source = [+ "```sh",+ "pnpm paperclipai issue create \\",+ ' --company-id <company-id> \\',+ ' --title "$(cat /etc/passwd)"',+ "```",+ ].join("\n");+ const offenders = scanText("doc/EXAMPLE.md", source);+ expect(offenders).toHaveLength(1);+ // The report points to the first physical line of the command.+ expect(offenders[0]).toContain("doc/EXAMPLE.md:2:");+ expect(offenders[0]).toContain("--title");+ });++ it("flags a continued command whose only content-bearing flag sits on the last line", () => {+ const source = [+ "pnpm paperclipai worktree init \\",+ " --force \\",+ " --name PAP-000-example",+ ].join("\n");+ const offenders = scanText("doc/EXAMPLE.md", source);+ expect(offenders).toHaveLength(1);+ expect(offenders[0]).toContain("doc/EXAMPLE.md:1:");+ expect(offenders[0]).toContain("--name");+ });++ it("does not flag a continued npx paperclipai command", () => {+ const source = [+ "npx paperclipai issue create \\",+ " --company-id <company-id> \\",+ ' --title "Investigate checkout conflict"',+ ].join("\n");+ expect(scanText("doc/EXAMPLE.md", source)).toEqual([]);+ });++ it("does not flag a continued pnpm paperclipai command without content-bearing arguments", () => {+ const source = [+ "pnpm paperclipai worktree reseed \\",+ " --from current \\",+ " --seed-mode full",+ ].join("\n");+ expect(scanText("doc/EXAMPLE.md", source)).toEqual([]);+ });+});diff --git a/server/src/__tests__/private-hostname-guard.test.ts b/server/src/__tests__/private-hostname-guard.test.tsindex 96d7aeb9a4..ce280b5c44 100644--- a/server/src/__tests__/private-hostname-guard.test.ts+++ b/server/src/__tests__/private-hostname-guard.test.ts@@ -42,14 +42,17 @@ describe("privateHostnameGuard", () => {expect(res.status).toBe(200);});- it("blocks unknown hostnames with remediation command", async () => {+ it("blocks unknown hostnames with a static remediation command", async () => {const app = createApp({ enabled: true, allowedHostnames: ["some-other-host"] });const res = await request(app).get("/api/health").set("Host", `${unknownHostname}:3100`);expect(res.status).toBe(403);- expect(res.body?.error).toContain(`please run pnpm paperclipai allowed-hostname ${unknownHostname}`);+ // The remediation command carries a static `<host>` placeholder. It never+ // interpolates the request Host header into the command.+ expect(res.body?.error).toContain("run pnpm exec paperclipai allowed-hostname <host>");+ expect(res.body?.error).not.toContain(unknownHostname);});- it("blocks unknown hostnames on page routes with plain-text remediation command", async () => {+ it("blocks unknown hostnames on page routes with a static plain-text remediation command", async () => {const middleware = privateHostnameGuard({enabled: true,allowedHostnames: ["some-other-host"],@@ -73,7 +76,24 @@ describe("privateHostnameGuard", () => {expect(next).not.toHaveBeenCalled();expect(res.status).toHaveBeenCalledWith(403);expect(res.send).toHaveBeenCalledWith(- expect.stringContaining(`please run pnpm paperclipai allowed-hostname ${unknownHostname}`),+ expect.stringContaining("run pnpm exec paperclipai allowed-hostname <host>"),);+ expect(res.send).not.toHaveBeenCalledWith(expect.stringContaining(unknownHostname));}, 20_000);++ it("does not reflect a hostile Host header into the remediation command", async () => {+ // An unauthenticated requester can send an invalid Host header that holds+ // shell metacharacters. `extractHostname` falls back to the raw header when+ // URL parsing fails. The 403 guidance must not echo that value, so an+ // operator or an agent cannot paste an attacker-controlled span into a+ // shell. Use a harmless, nonexistent command name inside the span.+ const hostileHost = "evil$(echo marker)host";+ const app = createApp({ enabled: true, allowedHostnames: ["some-other-host"] });+ const res = await request(app).get("/api/health").set("Host", hostileHost);+ expect(res.status).toBe(403);+ expect(res.body?.error).toContain("run pnpm exec paperclipai allowed-hostname <host>");+ expect(res.body?.error).not.toContain("evil");+ expect(res.body?.error).not.toContain("$(");+ expect(res.body?.error).not.toContain("marker");+ });});diff --git a/server/src/adapters/hermes-gateway-doc.ts b/server/src/adapters/hermes-gateway-doc.tsindex 75538fce9e..fb32c9d565 100644--- a/server/src/adapters/hermes-gateway-doc.ts+++ b/server/src/adapters/hermes-gateway-doc.ts@@ -47,7 +47,7 @@ Network examples:- Local loopback on one host: agentDefaultsPayload.apiBaseUrl = "http://127.0.0.1:8642"; agentDefaultsPayload.paperclipApiUrl = "http://127.0.0.1:3100".- Local dashboard root or chat URL on one host: agentDefaultsPayload.apiBaseUrl = "http://127.0.0.1:9119" or "http://127.0.0.1:9119/chat"; Paperclip maps it to "http://127.0.0.1:9119/api".- LAN/private network: agentDefaultsPayload.apiBaseUrl = "http://192.168.1.25:8642"; agentDefaultsPayload.paperclipApiUrl = "http://192.168.1.10:3100". Use private IPs or hostnames reachable from both machines.-- Private overlay: agentDefaultsPayload.apiBaseUrl = "http://hermes-host.tailnet-name.ts.net:8642"; agentDefaultsPayload.paperclipApiUrl = "http://paperclip-host.tailnet-name.ts.net:3100". Add the Paperclip hostname with pnpm paperclipai allowed-hostname <host> when authenticated/private mode requires it.+- Private overlay: agentDefaultsPayload.apiBaseUrl = "http://hermes-host.tailnet-name.ts.net:8642"; agentDefaultsPayload.paperclipApiUrl = "http://paperclip-host.tailnet-name.ts.net:3100". Add the Paperclip hostname with pnpm exec paperclipai allowed-hostname <host> when authenticated/private mode requires it.- Docker: if Hermes runs on the host and Paperclip runs in Docker, use agentDefaultsPayload.apiBaseUrl = "http://host.docker.internal:8642". If Hermes runs in another container, use the Compose service DNS name such as "http://hermes:8642".- Reverse proxy/TLS: publish Hermes behind HTTPS and set agentDefaultsPayload.apiBaseUrl = "https://hermes-gateway.example"; set agentDefaultsPayload.paperclipApiUrl = "https://paperclip.example". Keep API_SERVER_KEY required at the origin or proxy.diff --git a/server/src/middleware/private-hostname-guard.ts b/server/src/middleware/private-hostname-guard.tsindex a5d743dcca..f64d92c62c 100644--- a/server/src/middleware/private-hostname-guard.ts+++ b/server/src/middleware/private-hostname-guard.ts@@ -42,12 +42,16 @@ export function resolvePrivateHostnameAllowSet(opts: { allowedHostnames: string[return allowSet;}-function blockedHostnameMessage(hostname: string): string {- return (- `Hostname '${hostname}' is not allowed for this Paperclip instance. ` +- `If you want to allow this hostname, please run pnpm paperclipai allowed-hostname ${hostname}`- );-}+// The hostname comes from the request Host header, so an unauthenticated+// requester controls it. Never put that value into the guidance command. An+// operator or an agent can paste the guidance into a shell, and that outer+// shell evaluates a backtick, `$( )`, or `$NAME` span in the host before any+// CLI receives argv. A direct-exec form such as `pnpm exec` does not stop the+// outer shell. Emit a static `<host>` placeholder and do not echo the raw request+// value. The operator supplies the real hostname.+const BLOCKED_HOSTNAME_MESSAGE =+ "This hostname is not allowed for this Paperclip instance. " ++ "If you want to allow a hostname, run pnpm exec paperclipai allowed-hostname <host>.";export function privateHostnameGuard(opts: {enabled: boolean;@@ -68,7 +72,7 @@ export function privateHostnameGuard(opts: {const wantsJson = req.path.startsWith("/api") || req.accepts(["json", "html", "text"]) === "json";if (!hostname) {- const error = "Missing Host header. If you want to allow a hostname, run pnpm paperclipai allowed-hostname <host>.";+ const error = "Missing Host header. If you want to allow a hostname, run pnpm exec paperclipai allowed-hostname <host>.";if (wantsJson) {res.status(403).json({ error });} else {@@ -82,7 +86,7 @@ export function privateHostnameGuard(opts: {return;}- const error = blockedHostnameMessage(hostname);+ const error = BLOCKED_HOSTNAME_MESSAGE;if (wantsJson) {res.status(403).json({ error });} else {diff --git a/server/src/routes/access.ts b/server/src/routes/access.tsindex ea1ce6a183..5b29d2dac0 100644--- a/server/src/routes/access.ts+++ b/server/src/routes/access.ts@@ -1642,7 +1642,13 @@ function buildOnboardingDiscoveryDiagnostics(input: {code: "openclaw_onboarding_private_host_not_allowed",level: "warn",message: `Onboarding host "${apiHost}" is not in allowed hostnames for authenticated/private mode.`,- hint: `Run pnpm paperclipai allowed-hostname ${apiHost}`+ // `apiHost` comes from the request base URL, so a requester controls it.+ // Never put that value into the guidance command. An operator or an agent+ // can paste the command into a shell, and that outer shell evaluates a+ // metacharacter span in the host before any CLI receives argv. A+ // direct-exec form such as `pnpm exec` does not stop the outer shell. Emit+ // a static `<host>` placeholder and keep the raw host in the message only.+ hint: `Run pnpm exec paperclipai allowed-hostname <host>`});}@@ -1776,7 +1782,7 @@ function buildInviteOnboardingManifest(guidance:opts.deploymentMode === "authenticated" &&opts.deploymentExposure === "private"- ? "If OpenClaw runs on another machine, ensure the Paperclip hostname is reachable and allowed via `pnpm paperclipai allowed-hostname <host>`."+ ? "If OpenClaw runs on another machine, ensure the Paperclip hostname is reachable and allowed via `pnpm exec paperclipai allowed-hostname <host>`.": "Ensure OpenClaw can reach this Paperclip API base URL for invite, claim, and skill bootstrap calls."},textInstructions: {@@ -1999,7 +2005,7 @@ export function buildInviteOnboardingTextDocument(If none are reachable: ask your human operator for a reachable hostname/address and help them update network configuration.For authenticated/private mode, they may need:- - pnpm paperclipai allowed-hostname <host>+ - pnpm exec paperclipai allowed-hostname <host>- then restart Paperclip and retry onboarding.`);}diff --git a/server/src/services/company-export-readme.ts b/server/src/services/company-export-readme.tsindex df8766e18b..f352828886 100644--- a/server/src/services/company-export-readme.ts+++ b/server/src/services/company-export-readme.ts@@ -157,7 +157,7 @@ export function generateReadme(lines.push("## Getting Started");lines.push("");lines.push("```bash");- lines.push("pnpm paperclipai company import this-github-url-or-folder");+ lines.push("pnpm exec paperclipai company import this-github-url-or-folder");lines.push("```");lines.push("");lines.push("See [Paperclip](https://paperclip.ing) for more information.");diff --git a/skills/paperclip/SKILL.md b/skills/paperclip/SKILL.mdindex cf1a97cd5f..3988713700 100644--- a/skills/paperclip/SKILL.md+++ b/skills/paperclip/SKILL.md@@ -23,6 +23,8 @@ Some adapters also inject `PAPERCLIP_WAKE_PAYLOAD_JSON` on comment-driven wakes.Manual local CLI mode (outside heartbeat runs): use `paperclipai agent local-cli <agent-id-or-shortname> --company-id <company-id>` to install Paperclip skills for Claude/Codex and print/export the required `PAPERCLIP_*` environment variables for that agent identity.+**CLI safety — use `pnpm exec paperclipai` for content-bearing arguments.** When you run the Paperclip CLI, use `pnpm exec paperclipai` for any argument that can hold untrusted content. Untrusted content includes issue text, comment bodies, Markdown, pasted snippets, and model output. `pnpm exec` runs the installed binary directly and passes the argument as an inert `argv` value. Do not use `pnpm paperclipai` for such an argument. The safe form and the unsafe form differ only by the `exec` keyword, so read the command with care. `pnpm paperclipai` is a `package.json` script; `pnpm` runs the argument through `/bin/sh` first. The shell then interprets a backtick pair, `$( )`, `$NAME`, and `; | & < >` before the CLI starts. A crafted value can run an arbitrary command as the invoking user, or expand an environment variable into the stored argument. `npx paperclipai` is also injection-safe; use it when no local install is present. See `doc/CLI.md` for the full safe/unsafe matrix.+**Run audit trail:** You MUST include `-H 'X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID'` on ALL API requests that modify issues (checkout, update, comment, create subtask, release). This links your actions to the current heartbeat run for traceability.## The Heartbeat Procedurediff --git a/ui/src/lib/agent-onboarding-prompt.ts b/ui/src/lib/agent-onboarding-prompt.tsindex 4d3f6f06fa..2bbdd5c792 100644--- a/ui/src/lib/agent-onboarding-prompt.ts+++ b/ui/src/lib/agent-onboarding-prompt.ts@@ -18,13 +18,13 @@ export function buildAgentOnboardingPrompt(input: AgentOnboardingPromptInput) {? `No candidate URLs are available. Ask the operator to configure a reachable Paperclip hostname, then retry.Suggested steps for the operator:- choose a hostname that resolves to the Paperclip host from your runtime-- run: pnpm paperclipai allowed-hostname <host>+- run: pnpm exec paperclipai allowed-hostname <host>- restart Paperclip- verify with: curl -fsS http://<host>:3100/api/health- regenerate this agent onboarding prompt`: `If none are reachable, ask the operator to add a reachable Paperclip hostname, restart, and retry.Suggested command for the operator:-- pnpm paperclipai allowed-hostname <host>+- pnpm exec paperclipai allowed-hostname <host>Then verify with: curl -fsS <base-url>/api/health`;const resolutionLine = resolutionTestUrldiff --git a/ui/src/pages/CompanyExport.tsx b/ui/src/pages/CompanyExport.tsxindex 27f82642f7..365a5721bc 100644--- a/ui/src/pages/CompanyExport.tsx+++ b/ui/src/pages/CompanyExport.tsx@@ -484,7 +484,7 @@ function generateReadmeFromSelection(lines.push("## Getting Started");lines.push("");lines.push("```bash");- lines.push("pnpm paperclipai company import this-github-url-or-folder");+ lines.push("pnpm exec paperclipai company import this-github-url-or-folder");lines.push("```");lines.push("");lines.push("See [Paperclip](https://paperclip.ing) for more information.");