Update to Scopture
Snapshot Nov 20, 2026 · 00:11 UTC · version 1.3.0
Collection source: downloaded plugin package.
Instructions updated for scopture-cli
Full description — Now says: test, mutate, diff, render, and export Scopture/DUC (`.duc`) drawings from the terminal with the `scopture` CLI. Use whenever the user has a local `.duc`...
Observed in instructions or declared skills. Runtime behavior has not been tested.
Up to 3 plugins free · no card required.
All fields and original values.
Full description
Nov 3, 2026 · 06:11 UTC
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-o...
Nov 20, 2026 · 00:11 UTC
test, 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 ...
Skill instructions
Nov 3, 2026 · 06:11 UTC
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-o...
Nov 20, 2026 · 00:11 UTC
test, 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 ...
Compare saved observations
Download comparison JSONSKILL.md text changes
− removed · + added
--- before +++ after @@ -1,8 +1,8 @@ --- name: scopture-cli -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." +description: "Inspect, query, test, 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, test Python code or mutate drawing state/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." metadata: - version: "1.2.4" + version: "1.3.0" --- # Scopture CLI @@ -16,9 +16,11 @@ ## Side effects -- **Read-only:** `ls`, `cat`, `elements`, `run-sql` (default read-only), `diff`, `files list`, `charter get`, `issues list`, `drawing get`, `auth status`, `ps`, `desktop status`. +- **Read-only:** `ls`, `cat`, `elements`, `run-sql` (default read-only), `run-python` (read-only by default; only mutates if `update_drawing(...)` is called), `diff`, `files list`, `charter get`, `issues list`, `drawing get`, `auth status`, `ps`, `desktop status`. - **Mutates drawing state:** - - `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. + - `charter rename <target> <name>`: changes the stored drawing name (charter title) locally or remotely. For a local `.duc`, the disk filename stays the same; remote renames require drawing edit access. + - `update-drawing <drawing-id> <patch.json|->`: submits complete records as an incremental remote patch. Existing IDs replace records, new IDs add records, and omitted records remain. Use `--no-wait` to return the job ID immediately. + - `run-python` (only when `update_drawing(patch)` is called): modifies drawing elements and atomically re-compresses local `.duc` files or commits remote drawing changes. Without calling `update_drawing(...)`, it is completely read-only and safe for testing scripts. - `run-sql --mutate`: executes mutative SQL statements directly, persisting changes to local `.duc` files or remote drawings. - **Writes a file:** `render`, `export`, `files extract`. Direct output with `-o` to a scratch or outputs directory, never over the user's source drawing. - **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. @@ -51,22 +53,27 @@ > [!NOTE] > On local `.duc` files, `--mutate` executes in read-write mode, flushes WAL, and atomically re-compresses the `.duc` file. -> 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. +> On remote drawings, the CLI runs SQL locally and commits authorized writes through the drawing service. Add `--server` to use cloud compute. For remote read-only queries with multiple databases, see `duc` skill for the `{db}` placeholder. -## Drawing State & Element Mutation via Python (`run-python`) +## Python Sandbox: Testing & State Mutation (`run-python`) -To create or update drawing state (elements, 2D geometry, parametric 3D models, layers, blocks, or global state), use `scopture run-python`. +Use `run-python` to test code; it has the full engineering stack. Don't set up a local Python environment. -This 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: +`run-python` is **read-only by default**. It only modifies the drawing if the script explicitly calls `update_drawing(patch)`. Use it to test logic, inspect elements, run calculations, or create/update drawing state (elements, 2D geometry, parametric 3D models, layers, blocks, or global state). + +This command runs scripts in Scopture's **drawing-level Python runtime environment**, starting its own worker from the managed local profile while the desktop app is closed. Local files work offline after setup. Remote drawing IDs still need a session and a connection. Add `--server` to `run-python` or `run-sql` to opt into cloud compute on a remote drawing. See [Python Sandbox](../scopture/docs/automation/python-sandbox.md) for embedded methods, engineering capabilities, output kinds and network/process restrictions: ```bash -# Execute inline Python script against the drawing +# Test code or inspect elements safely (read-only, does not alter the drawing) +scopture run-python model.duc "from ducpy import ElementsClass; print('Testing logic against drawing...')" +scopture run-python model.duc --file ./test_calculations.py +scopture run-python model.duc --file ./inspect_model.py --json + +# Mutate drawing state (only modifies drawing when update_drawing(...) is called) scopture run-python model.duc "update_drawing({'elements': [{'id': 'box-1', 'element_type': 'rectangle', 'x': 100, 'y': 150, 'width': 200, 'height': 80}]})" -# Run a Python script from a file +# Run a mutative Python script from a file or STDIN scopture run-python model.duc --file ./create_parametric_bracket.py - -# Pipe Python script via STDIN cat mutate.py | scopture run-python model.duc - ``` @@ -81,6 +88,7 @@ scopture diff baseline.duc modified.duc # + added, - removed, ~ modified scopture render model.duc -o preview.png scopture render model.duc -o element.png --element <element-id> --width 1920 --height 1080 +scopture render model.duc --element <model-id> --view-config ./view.json -o section.png # section cut via clipping planes (without modifying model) scopture export model.duc --format step -o ./part.step # also: --format dxf scopture files list model.duc scopture files extract model.duc <file-id> -o ./extracted_part.step @@ -107,8 +115,10 @@ ## Common workflows +- **Test or run Python code:** Run `scopture run-python model.duc --file script.py` (or inline). Use `run-python` directly instead of creating a local virtual environment or installing packages—it has the full engineering stack (`ezdxf`, `matplotlib`, `ducpy`, `build123d`, etc.) and is read-only unless `update_drawing(...)` is called. +- **Section views & cutaways:** Never modify CAD geometry with boolean cuts for section views. Instead, pass `--view-config` with clipping planes to `scopture render` (or configure `viewerState` on the model element) to render dynamic cross-sections non-destructively. See the **`duc`** skill for design standards. - **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. -- **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. +- **Mutate elements or add parametric models:** Submit complete remote records with `update-drawing`. For scripted patches and local files, call `update_drawing(...)` inside `run-python`. The open desktop drawing reconciles edits to its local file. If a job is pending, resume with `scopture check-job <job-id> --wait-ms 10000`; do not resubmit or switch to SQL. Render the completed change to verify. - **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. - **Review briefing:** `charter get` + `issues list` + `diff` against the previous version.
Full technical diff · 2 changed fields
changed /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."
"Inspect, query, test, 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, test Python code or mutate drawing state/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."
changed /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""---\nname: scopture-cli\ndescription: \"Inspect, query, test, 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, test Python code or mutate drawing state/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.3.0\"\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), `run-python` (read-only by default; only mutates if `update_drawing(...)` is called), `diff`, `files list`, `charter get`, `issues list`, `drawing get`, `auth status`, `ps`, `desktop status`.\n- **Mutates drawing state:**\n - `charter rename <target> <name>`: changes the stored drawing name (charter title) locally or remotely. For a local `.duc`, the disk filename stays the same; remote renames require drawing edit access.\n - `update-drawing <drawing-id> <patch.json|->`: submits complete records as an incremental remote patch. Existing IDs replace records, new IDs add records, and omitted records remain. Use `--no-wait` to return the job ID immediately.\n - `run-python` (only when `update_drawing(patch)` is called): modifies drawing elements and atomically re-compresses local `.duc` files or commits remote drawing changes. Without calling `update_drawing(...)`, it is completely read-only and safe for testing scripts.\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, the CLI runs SQL locally and commits authorized writes through the drawing service. Add `--server` to use cloud compute. For remote read-only queries with multiple databases, see `duc` skill for the `{db}` placeholder.\n\n## Python Sandbox: Testing & State Mutation (`run-python`)\n\nUse `run-python` to test code; it has the full engineering stack. Don't set up a local Python environment.\n\n`run-python` is **read-only by default**. It only modifies the drawing if the script explicitly calls `update_drawing(patch)`. Use it to test logic, inspect elements, run calculations, or create/update drawing state (elements, 2D geometry, parametric 3D models, layers, blocks, or global state).\n\nThis command runs scripts in Scopture's **drawing-level Python runtime environment**, starting its own worker from the managed local profile while the desktop app is closed. Local files work offline after setup. Remote drawing IDs still need a session and a connection. Add `--server` to `run-python` or `run-sql` to opt into cloud compute on a remote drawing. See [Python Sandbox](../scopture/docs/automation/python-sandbox.md) for embedded methods, engineering capabilities, output kinds and network/process restrictions:\n\n```bash\n# Test code or inspect elements safely (read-only, does not alter the drawing)\nscopture run-python model.duc \"from ducpy import ElementsClass; print('Testing logic against drawing...')\"\nscopture run-python model.duc --file ./test_calculations.py\nscopture run-python model.duc --file ./inspect_model.py --json\n\n# Mutate drawing state (only modifies drawing when update_drawing(...) is called)\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 mutative Python script from a file or STDIN\nscopture run-python model.duc --file ./create_parametric_bracket.py\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 render model.duc --element <model-id> --view-config ./view.json -o section.png # section cut via clipping planes (without modifying model)\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- **Test or run Python code:** Run `scopture run-python model.duc --file script.py` (or inline). Use `run-python` directly instead of creating a local virtual environment or installing packages—it has the full engineering stack (`ezdxf`, `matplotlib`, `ducpy`, `build123d`, etc.) and is read-only unless `update_drawing(...)` is called.\n- **Section views & cutaways:** Never modify CAD geometry with boolean cuts for section views. Instead, pass `--view-config` with clipping planes to `scopture render` (or configure `viewerState` on the model element) to render dynamic cross-sections non-destructively. See the **`duc`** skill for design standards.\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:** Submit complete remote records with `update-drawing`. For scripted patches and local files, call `update_drawing(...)` inside `run-python`. The open desktop drawing reconciles edits to its local file. If a job is pending, resume with `scopture check-job <job-id> --wait-ms 10000`; do not resubmit or switch to SQL. Render the completed change 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"Full snapshot data
{
"description": "Inspect, query, test, 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, test Python code or mutate drawing state/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, test, 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, test Python code or mutate drawing state/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.3.0\"\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), `run-python` (read-only by default; only mutates if `update_drawing(...)` is called), `diff`, `files list`, `charter get`, `issues list`, `drawing get`, `auth status`, `ps`, `desktop status`.\n- **Mutates drawing state:**\n - `charter rename <target> <name>`: changes the stored drawing name (charter title) locally or remotely. For a local `.duc`, the disk filename stays the same; remote renames require drawing edit access.\n - `update-drawing <drawing-id> <patch.json|->`: submits complete records as an incremental remote patch. Existing IDs replace records, new IDs add records, and omitted records remain. Use `--no-wait` to return the job ID immediately.\n - `run-python` (only when `update_drawing(patch)` is called): modifies drawing elements and atomically re-compresses local `.duc` files or commits remote drawing changes. Without calling `update_drawing(...)`, it is completely read-only and safe for testing scripts.\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, the CLI runs SQL locally and commits authorized writes through the drawing service. Add `--server` to use cloud compute. For remote read-only queries with multiple databases, see `duc` skill for the `{db}` placeholder.\n\n## Python Sandbox: Testing & State Mutation (`run-python`)\n\nUse `run-python` to test code; it has the full engineering stack. Don't set up a local Python environment.\n\n`run-python` is **read-only by default**. It only modifies the drawing if the script explicitly calls `update_drawing(patch)`. Use it to test logic, inspect elements, run calculations, or create/update drawing state (elements, 2D geometry, parametric 3D models, layers, blocks, or global state).\n\nThis command runs scripts in Scopture's **drawing-level Python runtime environment**, starting its own worker from the managed local profile while the desktop app is closed. Local files work offline after setup. Remote drawing IDs still need a session and a connection. Add `--server` to `run-python` or `run-sql` to opt into cloud compute on a remote drawing. See [Python Sandbox](../scopture/docs/automation/python-sandbox.md) for embedded methods, engineering capabilities, output kinds and network/process restrictions:\n\n```bash\n# Test code or inspect elements safely (read-only, does not alter the drawing)\nscopture run-python model.duc \"from ducpy import ElementsClass; print('Testing logic against drawing...')\"\nscopture run-python model.duc --file ./test_calculations.py\nscopture run-python model.duc --file ./inspect_model.py --json\n\n# Mutate drawing state (only modifies drawing when update_drawing(...) is called)\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 mutative Python script from a file or STDIN\nscopture run-python model.duc --file ./create_parametric_bracket.py\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 render model.duc --element <model-id> --view-config ./view.json -o section.png # section cut via clipping planes (without modifying model)\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- **Test or run Python code:** Run `scopture run-python model.duc --file script.py` (or inline). Use `run-python` directly instead of creating a local virtual environment or installing packages—it has the full engineering stack (`ezdxf`, `matplotlib`, `ducpy`, `build123d`, etc.) and is read-only unless `update_drawing(...)` is called.\n- **Section views & cutaways:** Never modify CAD geometry with boolean cuts for section views. Instead, pass `--view-config` with clipping planes to `scopture render` (or configure `viewerState` on the model element) to render dynamic cross-sections non-destructively. See the **`duc`** skill for design standards.\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:** Submit complete remote records with `update-drawing`. For scripted patches and local files, call `update_drawing(...)` inside `run-python`. The open desktop drawing reconciles edits to its local file. If a job is pending, resume with `scopture check-job <job-id> --wait-ms 10000`; do not resubmit or switch to SQL. Render the completed change 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"
}SHA-256 of public snapshot: c0ae782518055c108725a12a2b1defa4274b400c8ea58f9f5438829df9df6a15