--- name: pp-paperclip description: "Printing Press CLI for Paperclip. REST API for the Paperclip AI agent management platform" author: "Hunter Veltri" license: "Apache-2.0" argument-hint: " [args] | install cli|mcp" allowed-tools: "Read Bash" metadata: openclaw: requires: bins: - paperclip-pp-cli --- # Paperclip — Printing Press CLI ## Prerequisites: Install the CLI This skill drives the `paperclip-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first: 1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows: ```bash npx -y @mvanhorn/printing-press-library install paperclip --cli-only ``` 2. Verify: `paperclip-pp-cli --version` 3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill. If the `npx` install fails before this CLI has a public-library category, install Node or use the category-specific Go fallback after publish. If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds. REST API for the Paperclip AI agent management platform ## Command Reference **adapters** — Manage adapters - `paperclip-pp-cli adapters create` — Install an adapter - `paperclip-pp-cli adapters delete` — Delete an adapter - `paperclip-pp-cli adapters get` — Get adapter registration details - `paperclip-pp-cli adapters list` — List all adapters - `paperclip-pp-cli adapters update` — Enable or disable an adapter **admin** — Manage admin - `paperclip-pp-cli admin create` — Demote a user from instance admin - `paperclip-pp-cli admin create-users` — Promote a user to instance admin - `paperclip-pp-cli admin get` — Get company access for a user (admin) - `paperclip-pp-cli admin list` — List all users (admin) - `paperclip-pp-cli admin update` — Set company access for a user (admin) **agents** — Manage agents - `paperclip-pp-cli agents delete` — Delete an agent - `paperclip-pp-cli agents get` — Get an agent - `paperclip-pp-cli agents list` — Get the current agent - `paperclip-pp-cli agents list-me` — Get current agent inbox (lite) - `paperclip-pp-cli agents list-me-2` — Get current agent assigned inbox items - `paperclip-pp-cli agents update` — Update an agent **approvals** — Manage approvals - `paperclip-pp-cli approvals ` — Get an approval **assets** — Manage assets **attachments** — Manage attachments - `paperclip-pp-cli attachments ` — Delete an attachment **auth** — Manage auth - `paperclip-pp-cli auth list` — Get current session - `paperclip-pp-cli auth list-profile` — Get current user profile - `paperclip-pp-cli auth update` — Update current user profile **board** — Manage board - `paperclip-pp-cli board` — Stream a board-level chat response (requires enableConferenceRoomChat) **board-api-keys** — Manage board api keys - `paperclip-pp-cli board-api-keys create` — Create a named board API key - `paperclip-pp-cli board-api-keys delete` — Revoke a board API key - `paperclip-pp-cli board-api-keys list` — List board API keys **board-claim** — Manage board claim - `paperclip-pp-cli board-claim ` — Get board claim details by token **bootstrap** — Manage bootstrap - `paperclip-pp-cli bootstrap` — Claim first instance admin from a browser session **cli-auth** — Manage cli auth - `paperclip-pp-cli cli-auth create` — Create a CLI auth challenge - `paperclip-pp-cli cli-auth create-cliauth` — Revoke current CLI auth session - `paperclip-pp-cli cli-auth create-cliauth-2` — Approve a CLI auth challenge - `paperclip-pp-cli cli-auth create-cliauth-3` — Cancel a CLI auth challenge - `paperclip-pp-cli cli-auth get` — Get a CLI auth challenge - `paperclip-pp-cli cli-auth list` — Get current CLI auth session **cloud-upstreams** — Manage cloud upstreams - `paperclip-pp-cli cloud-upstreams create` — Finish a cloud upstream connection - `paperclip-pp-cli cloud-upstreams create-cloudupstreams` — Start a cloud upstream connection - `paperclip-pp-cli cloud-upstreams list` — List cloud upstream connections **companies** — Manage companies - `paperclip-pp-cli companies create` — Create a company - `paperclip-pp-cli companies create-import` — Apply a company import (legacy route) - `paperclip-pp-cli companies create-import-2` — Preview a company import (legacy route) - `paperclip-pp-cli companies delete` — Delete a company - `paperclip-pp-cli companies get` — Get a company - `paperclip-pp-cli companies get-import` — Get company import job status - `paperclip-pp-cli companies list` — List companies - `paperclip-pp-cli companies list-issues` — Legacy — returns error directing to correct issues path - `paperclip-pp-cli companies list-stats` — Company stats - `paperclip-pp-cli companies update` — Update a company **environment-custom-image-setup-sessions** — Manage environment custom image setup sessions - `paperclip-pp-cli environment-custom-image-setup-sessions ` — Get and refresh an environment customImage setup session **environment-leases** — Manage environment leases - `paperclip-pp-cli environment-leases ` — Get an environment lease **environments** — Manage environments - `paperclip-pp-cli environments delete` — Delete an environment - `paperclip-pp-cli environments get` — Get an environment - `paperclip-pp-cli environments update` — Update an environment **execution-workspaces** — Manage execution workspaces - `paperclip-pp-cli execution-workspaces get` — Get an execution workspace - `paperclip-pp-cli execution-workspaces update` — Update an execution workspace **feedback-traces** — Manage feedback traces - `paperclip-pp-cli feedback-traces ` — Get a feedback trace **goals** — Manage goals - `paperclip-pp-cli goals delete` — Delete a goal - `paperclip-pp-cli goals get` — Get a goal - `paperclip-pp-cli goals update` — Update a goal **health** — Manage health - `paperclip-pp-cli health create` — Request a managed dev-server restart - `paperclip-pp-cli health list` — Health check **heartbeat-runs** — Manage heartbeat runs - `paperclip-pp-cli heartbeat-runs ` — Get a heartbeat run **instance** — Manage instance - `paperclip-pp-cli instance create` — Trigger a database backup - `paperclip-pp-cli instance create-settings` — Preview issue graph liveness auto-recovery - `paperclip-pp-cli instance create-settings-2` — Run issue graph liveness auto-recovery - `paperclip-pp-cli instance list` — List scheduler heartbeats - `paperclip-pp-cli instance list-settings` — Get instance settings - `paperclip-pp-cli instance list-settings-2` — Get experimental instance settings - `paperclip-pp-cli instance list-settings-3` — Get general instance settings - `paperclip-pp-cli instance update` — Update instance settings - `paperclip-pp-cli instance update-settings` — Update experimental instance settings - `paperclip-pp-cli instance update-settings-2` — Update general instance settings **invites** — Manage invites - `paperclip-pp-cli invites ` — Get an invite by token **issues** — Manage issues - `paperclip-pp-cli issues delete` — Delete an issue - `paperclip-pp-cli issues get` — Get an issue - `paperclip-pp-cli issues list` — Legacy — returns error directing to /api/companies/{companyId}/issues - `paperclip-pp-cli issues update` — Update an issue **join-requests** — Manage join requests **labels** — Manage labels - `paperclip-pp-cli labels ` — Delete a label **llms** — Manage llms - `paperclip-pp-cli llms get` — Get agent configuration for a specific adapter type - `paperclip-pp-cli llms list` — Get agent configuration as plain text (for LLM context) - `paperclip-pp-cli llms list-agenticonstxt` — Get agent icon names as plain text **openapi-json** — Manage openapi json - `paperclip-pp-cli openapi-json` — Get the generated OpenAPI document **plugins** — Manage plugins - `paperclip-pp-cli plugins create` — Install a plugin - `paperclip-pp-cli plugins create-tools` — Execute a plugin tool - `paperclip-pp-cli plugins delete` — Delete a plugin - `paperclip-pp-cli plugins get` — Get a plugin - `paperclip-pp-cli plugins list` — List installed plugins - `paperclip-pp-cli plugins list-examples` — List example plugins - `paperclip-pp-cli plugins list-tools` — List plugin tools - `paperclip-pp-cli plugins list-uicontributions` — List plugin UI contributions **projects** — Manage projects - `paperclip-pp-cli projects delete` — Delete a project - `paperclip-pp-cli projects get` — Get a project - `paperclip-pp-cli projects update` — Update a project **routine-triggers** — Manage routine triggers - `paperclip-pp-cli routine-triggers create` — Fire a public routine trigger - `paperclip-pp-cli routine-triggers delete` — Delete a routine trigger - `paperclip-pp-cli routine-triggers update` — Update a routine trigger **routines** — Manage routines - `paperclip-pp-cli routines get` — Get a routine - `paperclip-pp-cli routines update` — Update a routine **secret-provider-configs** — Manage secret provider configs - `paperclip-pp-cli secret-provider-configs delete` — Delete a secret provider configuration - `paperclip-pp-cli secret-provider-configs get` — Get a secret provider configuration - `paperclip-pp-cli secret-provider-configs update` — Update a secret provider configuration **secrets** — Manage secrets - `paperclip-pp-cli secrets delete` — Delete a secret - `paperclip-pp-cli secrets update` — Update a secret **sidebar-preferences** — Manage sidebar preferences - `paperclip-pp-cli sidebar-preferences list` — Get current user sidebar preferences - `paperclip-pp-cli sidebar-preferences update` — Update current user sidebar preferences **skills** — Manage skills - `paperclip-pp-cli skills get` — Get a skill by name - `paperclip-pp-cli skills get-catalog` — Get a catalog skill - `paperclip-pp-cli skills get-catalog-2` — List catalog skill files - `paperclip-pp-cli skills list` — List available skills - `paperclip-pp-cli skills list-catalog` — List catalog skills - `paperclip-pp-cli skills list-index` — Get skills index **teams** — Manage teams - `paperclip-pp-cli teams get` — Get catalog team - `paperclip-pp-cli teams get-catalog` — Get catalog team file - `paperclip-pp-cli teams list` — List catalog teams **work-products** — Manage work products - `paperclip-pp-cli work-products delete` — Delete a work product - `paperclip-pp-cli work-products update` — Update a work product **workspace-operations** — Manage workspace operations ### Finding the right command When you know what you want to do but not which command does it, ask the CLI directly: ```bash paperclip-pp-cli which "" ``` `which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code `0` means at least one match; exit code `2` means no confident match — fall back to `--help` or use a narrower query. ## Auth Setup Configure one of Paperclip's supported authentication modes: - `PAPERCLIP_SESSION_COOKIE` for a browser session (`board-session`) - `PAPERCLIP_API_KEY` for a board API key (`board-api-key`) - `PAPERCLIP_AGENT_TOKEN` for an agent bearer token (`agent-bearer`) The CLI auto-detects the mode from the credential. Set `PAPERCLIP_AUTH_MODE` to `board-session`, `board-api-key`, `agent-bearer`, or `none` to choose explicitly. Run `paperclip-pp-cli doctor` to verify setup. ## Agent Mode Add `--agent` to any command. Expands to: `--json --compact --no-input --no-color --yes`. - **Pipeable** — JSON on stdout, errors on stderr - **Filterable** — `--select` keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs: ```bash paperclip-pp-cli adapters list --agent --select id,name,status ``` - **Previewable** — `--dry-run` shows the request without sending - **Offline-friendly** — sync/search commands can use the local SQLite store when available - **Non-interactive** — never prompts, every input is a flag - **Explicit retries** — use `--idempotent` only when an already-existing create should count as success, and use `--ignore-missing` only when a missing delete target should count as success ### Response envelope Commands that read from the local store or the API wrap output in a provenance envelope: ```json { "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."}, "results": } ``` Parse `.results` for data and `.meta.source` to know whether it's live or local. A human-readable `N results (live)` summary is printed to stderr only when stdout is a terminal AND no machine-format flag (`--json`, `--csv`, `--compact`, `--quiet`, `--plain`, `--select`) is set — piped/agent consumers and explicit-format runs get pure JSON on stdout. ## Paths and state Agents should treat the CLI's path resolver as part of the runtime contract: - Use `--home ` for one invocation, or set `PAPERCLIP_HOME=` to relocate all four path kinds under one root. - Use per-kind env vars only when a specific kind must diverge: `PAPERCLIP_CONFIG_DIR`, `PAPERCLIP_DATA_DIR`, `PAPERCLIP_STATE_DIR`, `PAPERCLIP_CACHE_DIR`. - Resolution order is per-kind env var, `--home`, `PAPERCLIP_HOME`, XDG (`XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME`), then platform defaults. - `config` contains settings like `config.toml` and profiles. `data` contains `credentials.toml`, `data.db`, cookies, and auth sidecars. `state` contains persisted queries, jobs, and `teach.log`. `cache` contains regenerable HTTP/cache files. - Stored secrets live in `credentials.toml` under the data dir. Existing legacy `config.toml` secrets are read for compatibility and leave `config.toml` on the first auth write. - Run `paperclip-pp-cli doctor --fail-on warn` to surface path and credential-location warnings. `agent-context` exposes a schema v4 `paths` block for agents that need the resolved dirs. - For MCP, pass relocation through the MCP host config. The MCP binary does not inherit CLI flags: ```json { "mcpServers": { "paperclip": { "command": "paperclip-pp-mcp", "env": { "PAPERCLIP_HOME": "/srv/paperclip" } } } } ``` Fleet precedence: an inherited per-kind env var overrides an explicit `--home` for that kind. Use `PAPERCLIP_HOME` or per-kind vars as durable fleet levers, and use `--home` only for a single invocation. Relocation is not reversible by unsetting env vars; move files manually before clearing `PAPERCLIP_HOME`, or `doctor` will not find credentials left under the former root. ## Automatic learning This CLI ships a self-capturing learning loop. The CLI does its own bookkeeping: every invocation is journaled locally, a failed flag followed by a corrected retry auto-derives a `flag_alias` candidate, and a `teach` on a query family without a playbook auto-synthesizes a `playbook_candidate` from the session's journal. Your job is judgment only: `recall` first, act on surfaced candidates, `teach` the final answer, `playbook amend` when you observe a correction. You never record failures by hand. ### Step 1: `recall` before any discovery Before list/search/drill commands on a new user question, run: ```bash paperclip-pp-cli recall "" --agent ``` The response envelope: ```json { "query": "...", "normalized": "", "query_entities": ["..."], "found": true | false, "match_score": 0.0, "results": [ { "resource_id": "...", "resource_type": "...", "venue": "...", "confidence": 2, "entity_match": "exact|partial|unknown", "source": "taught|preseed|pattern", "warnings": ["..."] } ], "mismatches": [ /* only when --debug-mismatches */ ], "warnings": [ /* top-level */ ], "candidates": [ { "id": 12, "class": "flag_alias | playbook_candidate", "summary": "...", "sightings": 3, "last_seen": "...", "rationale": "...", "next_action": ["", "paperclip-pp-cli learnings confirm 12"] } ], "playbook": { "query_family": "...", "playbook": { "steps": [ { "cmd": "", "purpose": "..." } ], "entity_slots": ["$ENTITY"], "expected_tool_calls": 3 }, "slots_resolved": { "$ENTITY": { "token": "", "canonical": "" } }, "notes": "" }, "notes": "" } ``` Empty-store short-circuit: if the store has no learnings, playbooks, or candidates yet (recall finds nothing and `learnings list` and `learnings candidates` are both empty), skip recall for the rest of this session instead of taxing every query; resume recall-first once something has been taught. ### Step 2: decision tree Read `candidates`, `playbook`, `notes`, `results[0]`, and warnings in that order: ``` if Candidates present (warnings include "candidates_present"): -> candidates are try-then-confirm, never facts. Follow each candidate's two-step next_action verbatim: run the trial command first, then run `learnings confirm ` only after the trial verified the behavior. Reject a wrong candidate with `learnings reject `. -> NEVER re-teach something recall surfaced as a candidate; confirm or reject that candidate instead of teaching a duplicate. -> candidates ride alongside playbooks and resource hits, not instead of them; continue with the branches below after acting on them. if Playbook present: -> READ Playbook.notes verbatim FIRST (workarounds + gotchas the CLI surface doesn't expose) -> replay Playbook.steps in order, substituting Playbook.slots_resolved entries for the entity slot tokens. If a step's slot is unresolved, fall back to discovery for that step only. -> the Playbook's expected_tool_calls is a budget; if you find yourself running materially more, record the divergence via `paperclip-pp-cli playbook amend` at end-of-session. elif Notes present (no Playbook): -> read Notes verbatim before any discovery step; they carry known gotchas for this query family even when no structured choreography exists yet. elif Found AND Results[0].EntityMatch == "exact" AND Results[0].Confidence >= 2: -> skip discovery; fetch live data for Results[*].ResourceID in parallel elif Found AND Results[0].EntityMatch == "partial": -> candidate hint, NOT a hit; read the resource title to validate before trusting elif (any row in Mismatches[] when --debug-mismatches was passed): -> treat as cold start; the stored learning is for a different entity (different canonical resolved from query_entities) else: // Found == false, no playbook, no notes -> cold start; run discovery normally; teach the answer afterward (Step 4). If the family has no playbook yet, that teach auto-synthesizes a playbook candidate from this session's journal - you do not need to record one by hand. ``` Playbook and Notes are orthogonal to the per-resource path. A recall response can carry both a Playbook AND a `Results[]` hit - use both: the Playbook tells you which choreography to run; the resource hits short-circuit specific steps. Default to skipping `mismatches`; pass `--debug-mismatches` only when investigating cold-start