{"id":77823,"plugin_id":"plugin_asdk_app_6a2aa7768fe881919ad20644669ca2fe","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-11-03T06:11:29.898Z","digest":"1bd47177d3da733396048887c81267848de2bbcd2e35a20ade30c318e659da46","against":null,"payload":{"description":"Inspect, query, mutate, diff, render, and export Scopture/DUC (`.duc`) drawings from the terminal with the `scopture` CLI. Use whenever the user has a local `.duc` file or remote drawing and wants to see what's in it, find or filter elements, run read-only or mutative SQL, mutate drawing state or elements via the Python sandbox, compare two versions, render a preview image, extract embedded STEP/IFC files, export to STEP/DXF, review a drawing's charter or issues, or open it in the desktop app, even if they never mention the CLI. For understanding Scopture canvas standards specifically use the `scopture` skill; for writing `ducpy` code or adjacent logic to the `.duc` use the `duc` skill.","included_files":[],"name":"scopture-cli","skill_md_contents":"---\nname: scopture-cli\ndescription: \"Inspect, query, mutate, diff, render, and export Scopture/DUC (`.duc`) drawings from the terminal with the `scopture` CLI. Use whenever the user has a local `.duc` file or remote drawing and wants to see what's in it, find or filter elements, run read-only or mutative SQL, mutate drawing state or elements via the Python sandbox, compare two versions, render a preview image, extract embedded STEP/IFC files, export to STEP/DXF, review a drawing's charter or issues, or open it in the desktop app, even if they never mention the CLI. For understanding Scopture canvas standards specifically use the `scopture` skill; for writing `ducpy` code or adjacent logic to the `.duc` use the `duc` skill.\"\nmetadata:\n  version: \"1.2.4\"\n---\n# Scopture CLI\n\nThe `scopture` CLI ships with the Scopture desktop app. It works on local `.duc` files (gzip-compressed SQLite) and on remote drawings. It is built for shell pipelines: it inspects, queries, mutates, diffs, renders, and exports.\n\n## Before you start\n\n1. Run `scopture --version`. If it isn't found, tell the user to install the Scopture app via `https://site.scopture.com/download`, and offer the `duc` skill as a way to read the file without the CLI.\n2. Run `scopture <command> --help` before using any flag not shown below. Flags change; `--help` is authoritative.\n3. Pick an output mode: `--raw` for piping into `jq`/`grep`/`head`, `--json` when you need an explicit `{\"success\": true, \"data\": ...}` envelope.\n\n## Side effects\n\n- **Read-only:** `ls`, `cat`, `elements`, `run-sql` (default read-only), `diff`, `files list`, `charter get`, `issues list`, `drawing get`, `auth status`, `ps`, `desktop status`.\n- **Mutates drawing state:**\n  - `run-python`: executes Python scripts in the sandbox. If `update_drawing(patch)` is called, modifies drawing elements and atomically re-compresses local `.duc` files or commits remote drawing changes.\n  - `run-sql --mutate`: executes mutative SQL statements directly, persisting changes to local `.duc` files or remote drawings.\n- **Writes a file:** `render`, `export`, `files extract`. Direct output with `-o` to a scratch or outputs directory, never over the user's source drawing.\n- **Changes the user's screen:** `scopture <file>`, `open`, `desktop focus`. Run these only when the user asks to open or show something. For inspection and background scripts, use the headless commands.\n\n## Inspect\n\nDrawings can hold thousands of elements. Never print a full `cat` into the conversation; start with `ls` for the shape of the drawing, then narrow.\n\n```bash\nscopture ls model.duc                          # tabular overview\nscopture cat model.duc | grep -i motor | head  # NDJSON stream, one element per line\nscopture elements list model.duc --element-type model --search \"bracket\"\nscopture elements get model.duc <element-id>   # full geometry and parametric code\n```\n\n## Query & Mutate SQL (`run-sql`)\n\nDiscover the schema before writing queries rather than guessing column names:\n\n```bash\n# Read-only query (default)\nscopture run-sql model.duc \"SELECT name FROM sqlite_master WHERE type='table'\"\nscopture run-sql model.duc \"SELECT id, element_type, label FROM elements LIMIT 10\"\ncat query.sql | scopture run-sql model.duc - --raw | jq .   # query from stdin\n\n# Mutative SQL (--mutate flag)\nscopture run-sql model.duc \"UPDATE elements SET label = 'Front Bracket' WHERE id = 'elem-1'\" --mutate\nscopture run-sql model.duc \"INSERT INTO layers (id, name, is_visible) VALUES ('layer-mfg', 'Manufacturing', 1)\" --mutate\n```\n\n> [!NOTE]\n> On local `.duc` files, `--mutate` executes in read-write mode, flushes WAL, and atomically re-compresses the `.duc` file.\n> On remote drawings, `--mutate` commits the SQL transaction to the drawing. For remote read-only queries with multiple databases, see `duc` skill for the `{db}` placeholder.\n\n## Drawing State & Element Mutation via Python (`run-python`)\n\nTo create or update drawing state (elements, 2D geometry, parametric 3D models, layers, blocks, or global state), use `scopture run-python`.\n\nThis command runs scripts in Scopture's **drawing-level Python runtime environment**, using the managed desktop sandbox when available, including for remote drawing IDs. Use `--server` to request cloud execution. Both workers derive from the shared sandbox project; authorization still applies. See [Python Sandbox](https://site.scopture.com/docs/automation/python-sandbox) for embedded methods, engineering capabilities, output kinds and network/process restrictions:\n\n```bash\n# Execute inline Python script against the drawing\nscopture run-python model.duc \"update_drawing({'elements': [{'id': 'box-1', 'element_type': 'rectangle', 'x': 100, 'y': 150, 'width': 200, 'height': 80}]})\"\n\n# Run a Python script from a file\nscopture run-python model.duc --file ./create_parametric_bracket.py\n\n# Pipe Python script via STDIN\ncat mutate.py | scopture run-python model.duc -\n```\n\n> [!TIP]\n> **Cross-Skill References**\n> - **Canvas Patch & Styling Rules**: For patch semantics (`ADD`/`UPDATE`/`DELETE`), injected sandbox helpers, scientific libraries, and visual design standards, consult the **`scopture`** skill (and its bundled `./docs/` folder).\n> - **Programmatic Modeling & `.duc` Architecture**: For `ducpy` fluent builders, relational tables, and SQLite schema guidance, consult the **`duc`** skill (and its bundled `./docs/` and `./docs-ducpy` folders).\n\n## Diff, render, export\n\n```bash\nscopture diff baseline.duc modified.duc       # + added, - removed, ~ modified\nscopture render model.duc -o preview.png\nscopture render model.duc -o element.png --element <element-id> --width 1920 --height 1080\nscopture export model.duc --format step -o ./part.step   # also: --format dxf\nscopture files list model.duc\nscopture files extract model.duc <file-id> -o ./extracted_part.step\n```\n\nAfter rendering, open the image and look at it before describing the result to the user.\n\n## Remote drawings\n\nThe target can be a local path or a remote drawing UUID/slug. The CLI reuses the desktop app's login (OS credential store), so there is no separate sign-in.\n\n```bash\nscopture ls                          # no target: lists accessible remote drawings\nscopture drawing get <drawing-id>\nscopture auth status\n```\n\n## Review\n\n```bash\nscopture charter get model.duc       # requirements (MUST/SHOULD), constraints, decisions\nscopture issues list model.duc       # open/closed issues and reviewer threads\n```\n\n## Common workflows\n\n- **Find an element and show it:** `cat | grep` to locate it, take its ID, `elements get` to inspect it, `render --element` to see it, then view the PNG.\n- **Mutate elements or add parametric models:** Write a small Python script using `update_drawing(...)`, run `scopture run-python model.duc --file script.py`, then `render` to verify.\n- **What changed between two versions:** `diff`, then summarize the added/removed/modified counts and call out the notable elements. Render both if the change is visual.\n- **Review briefing:** `charter get` + `issues list` + `diff` against the previous version.\n\n## Exit codes\n\n| Code | Meaning | What to do |\n|---|---|---|\n| 0 | Success | |\n| 2 | Authentication failure | Run `scopture auth status`; ask the user to sign in through the desktop app |\n| 3 | Target, element, or file not found | Run `scopture ls` to confirm the target and IDs |\n| 4 | Invalid arguments or query syntax | Check `--help`; for SQL, re-check table and column names |\n| 5 | Render error | Retry with a specific `--element` or a smaller size |\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}