# Use Paper CLI > Operates Paper Desktop through the paper Rust CLI when native MCP access is unavailable. Use when an agent needs to inspect, create, edit, comment on, capture, export, or otherwise work with Paper design files from shell commands. - Skill: `lassejlv/use-paper-cli` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add lassejlv/use-paper-cli` - Raw SKILL.md: https://api.skillmd.com/api/skills/lassejlv/use-paper-cli/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: lassejlv (https://skillmd.com/u/lassejlv) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/lassejlv/use-paper-cli --- # Use Paper CLI Use `paper` as a generic, schema-driven bridge to Paper Desktop's live MCP server. Paper's live tool catalog and schemas are authoritative; never rely on a remembered argument shape. ## Preconditions 1. Check whether the CLI is installed: ```sh command -v paper ``` 2. If it is missing, report that clearly. Do not silently install software. Suggested installation from this repository: ```sh cargo install --git https://github.com/lassejlv/paper-cli --locked ``` 3. Paper Desktop must be running. A Paper file must be open for design tools. 4. Verify connectivity before doing work: ```sh paper status --short ``` The default endpoint is `http://127.0.0.1:29979/mcp`. Use `--url` or `PAPER_MCP_URL` only when the user has configured another endpoint. ## Core rule: discover, then call The CLI intentionally does not mirror Paper's tool catalog. Discover tools and read the exact live schema before each unfamiliar or consequential call: ```sh paper tools --names paper schema paper call '' ``` Do not guess parameter names, accepted values, or response shapes. Re-read a schema after a Paper update or after a validation error. Use the generic commands as the foundation: - `paper call` invokes any advertised Paper tool. - `paper schema` reads one live tool definition. - `paper request` sends another MCP request after initialization. - `paper notify` sends an MCP notification after initialization. Use convenience commands only where they fit exactly: - `paper status --short` - `paper context --short [--file-id ]` - `paper files [--limit 50] [--names]` - `paper open [--page-id ]` - `paper screenshot --output [--scale 1] [--file-id ] [--force]` ## Standard workflow ### 1. Establish file context ```sh paper status --short paper files paper context --short paper call get_basic_info --text paper call get_selection --text ``` Use `paper files`, not `--names`, when file IDs are needed. If several files are open, target one explicitly: ```sh paper open --page-id ``` Pass `fileId` to tools that support it when ambiguity is possible. Do not assume the most recently active file is the intended one. ### 2. Inspect before mutation Start with read-only tools. Read schemas before invoking hierarchy, style, JSX, font, token, comment, screenshot, or export tools: ```sh paper schema get_node_info paper schema get_tree_summary paper schema get_computed_styles paper schema get_screenshot ``` Resolve the target from `get_selection` or an explicit user-provided node. Do not choose a similarly named node when multiple nodes fit. ### 3. Choose the output mode **Structured JSON — default** Use when automation needs the complete MCP result, including annotations, structured content, images, or embedded resources: ```sh paper call get_selection paper --compact call get_selection ``` **Text** Use only when the response is text-only: ```sh paper call get_basic_info --text ``` The CLI rejects `--text` when any non-text content is present. Do not work around this protection or print base64 into the terminal. **Image file** Use `--output` when exactly one image is expected: ```sh paper call get_screenshot '{"nodeId":""}' --output captures/screen.jpg paper screenshot --active-artboard --output captures/artboard.jpg paper screenshot --selected --output captures/selection.png paper screenshot --artboard "Dashboard — Desktop" --output captures/dashboard.jpg paper screenshot --output captures/screen.jpg --scale 1 ``` Screenshot convenience targets are mutually exclusive: - `--selected` requires exactly one selected node. - `--active-artboard` prefers the single selected node's artboard and otherwise requires exactly one artboard on the active page. - `--artboard ""` requires one exact full-name match. - Use a positional node ID when a known node that is not naturally selected or named as an artboard is the intended target. The CLI reports ambiguity with human-readable names and never chooses the first match. Use `--file-id` when resolving against a specific open file. The extension must match the returned MIME type. Omit the extension when the CLI should infer it. Parent directories are created automatically. Never add `--force` unless replacing that exact file is intended. ### 4. Supply arguments safely Use inline JSON for small inputs: ```sh paper call '{"key":"value"}' ``` Use a file for long HTML, style updates, token batches, or other complex input: ```sh paper call @arguments.json ``` Use stdin when another command produces the arguments: ```sh printf '%s' '{"key":"value"}' | paper call - ``` Arguments for `paper call` must be a JSON object. Keep stdout available for machine-readable results; diagnostics and failures are written to stderr. ### 5. Make focused changes When the user authorizes design changes: 1. Read the mutation tool's current schema. 2. Respect tool annotations such as `readOnlyHint` and `destructiveHint`. 3. Before typographic styling, call `get_font_family_info`. 4. Prefer targeted text/style/move/duplicate operations over rewriting a large subtree. 5. Keep each `write_html` call to one coherent visual group. 6. Preserve unrelated nodes and existing design tokens. 7. Verify returned node information rather than trusting remembered node IDs. Before deleting a node because its parent appears wrong, call `get_node_info` and verify the relationship. ### 6. Verify and finish After meaningful changes: 1. Re-read the changed node or subtree. 2. Capture a screenshot at scale 1 for layout review; use scale 2 only for fine typography or small details. 3. Confirm the actual state matches the request. 4. Call `finish_working_on_nodes` when creation or editing is complete: ```sh paper schema finish_working_on_nodes paper call finish_working_on_nodes '{}' ``` If the live schema requires arguments, follow it instead of the example. ## Upgrade the CLI and skill Only when the user explicitly asks to update Paper CLI, run: ```sh paper upgrade ``` This updates the globally installed `use-paper-cli` skill through `npx skills@latest`, then runs the repository's checksum-verifying installer in the directory containing the current `paper` executable. It does not require Paper Desktop or Cargo. It requires `npx`, internet access, an existing global skill installation, and either a POSIX shell on macOS/Linux or Windows PowerShell. On Windows, the result reports the CLI update as scheduled because the installer waits for the running `paper.exe` to exit before replacing it; installer progress then appears in the same terminal. Treat a nonzero exit as a partial or failed upgrade and report the failed component and retry guidance shown by the CLI. ## Safety rules - Paper tools act on the active file unless a supported `fileId` is supplied. - Read-only inspection does not authorize mutation. - Ask before destructive or unrelated mutations unless the request already authorizes them. - `paper open` changes Paper's active context; use it deliberately. - `--force` overwrites a local output file and must be explicit. - Do not use `paper-gen://` unless the user explicitly requested image generation and the relevant Paper guide has been loaded. - Do not expose raw node IDs in the final user-facing response. - Never report completion from a successful exit code alone; inspect the final Paper state. ## Error handling - Connection failure: confirm Paper Desktop is running and a file is open, then retry `paper status --short`. - Unknown tool: run `paper tools --names`; the catalog may have changed. - Invalid arguments: run `paper schema ` again and rebuild the JSON. - `--text` rejection: omit `--text` for structured JSON or use `--output` for one image. - MIME/extension mismatch: use a compatible extension or omit it for inference. - Existing output file: choose another path or use `--force` only after confirming replacement. - Multiple returned images: keep structured JSON and handle each image deliberately; `--output` writes exactly one image. ## Completion report State: - The Paper file and page used, without exposing raw node IDs. - What was inspected or changed. - Which Paper tools or convenience commands were used. - How the final state was verified. - Any unresolved ambiguity, unsupported output, or pending destructive action. ## Detailed examples Read [examples.md](examples.md) for copy-paste workflows covering file selection, design inspection, screenshots, exports, mutations, comments, and failure recovery.