Command-Line Interface

The Scopture desktop package includes the scopture-cli executable. It can open the desktop app, inspect local .duc files, and access remote drawings using your authenticated account.

Install with the Desktop AppCopy Anchor Link

Install Scopture desktop, then launch the app once. Scopture installs the CLI and renderer into its user command directory and adds it to your shell PATH. Open a new terminal after the first launch. The preparation screen installs the locked Python tools into user storage. Desktop updates reuse the environment when its profile is unchanged and reuse cached packages when dependencies change.

On installation and after a desktop update, Scopture also syncs its duc, scopture, and scopture-cli agent skills from the skill pack bundled at build time into ~/.agents/skills. Other skill folders are preserved. An unsuccessful sync is retried on the next launch.

scopture --version
scopture --help

Open and Inspect a DrawingCopy Anchor Link

Open a local file in the desktop app:

scopture ./assembly.duc

Inspection commands read the file directly and do not require a cloud account:

scopture drawing get ./assembly.duc --json
scopture elements list ./assembly.duc --element-type model --json
scopture files list ./assembly.duc --json
scopture cat ./assembly.duc

cat streams one element per line as NDJSON. Use --json for a structured response envelope or --raw for the unwrapped JSON value from other commands. JSON success and failure responses go to stdout; human errors go to stderr. Element lists return arrays and SQL reads return rows_count/rows on both local and remote targets. Use scopture <command> --help for that command’s arguments.

Use a Remote DrawingCopy Anchor Link

Sign in through the desktop app, then check whether the CLI can use its stored session:

scopture auth status
scopture drawing list --json
scopture drawing get <drawing-id> --json

Authentication resolves in this order: --token, the SCOPTURE_TOKEN environment variable, then the operating system credential store used by the desktop app. Remote commands retain drawing and integration permission checks. Cloud Python execution requires an entitled paid plan in the drawing’s organization.

Query or Run PythonCopy Anchor Link

scopture run-sql ./assembly.duc "SELECT id, element_type FROM elements LIMIT 10" --json
scopture run-python ./assembly.duc --file ./inspect_model.py --json

Use run-sql --mutate for an intended SQL write. Local Python uses the same managed Python 3.12 environment as the desktop app, with dependencies locked from the sandbox profile. The CLI can prepare it without opening the app; first setup needs an internet connection, and completed environments work offline. uv reuses its normal package cache while keeping Python and its environment in Scopture’s user storage. Host Python and user site-packages are excluded. SCOPTURE_PYTHON_PATH and SCOPTURE_PYTHON_WORKER_PATH are available only in development builds.

Remote drawing jobs also prefer the installed desktop sandbox; use --server to request the cloud worker explicitly. See Python Sandbox for embedded methods, engineering packages and execution limits.

Model scripts use the same emit_output(...) contract as the desktop and cloud runtimes. Human output includes Python stdout/stderr; use --json to inspect artifact envelopes. --model-output-kind none suppresses artifacts, including explicit emit_output declarations, while preserving prints and drawing updates.

Create and RenderCopy Anchor Link

scopture drawing create --name "Assembly" --out ./assembly.duc
scopture drawing create --name "Cloud assembly"
scopture render ./assembly.duc --width 1600 --height 1200 -o canvas.png
scopture render ./assembly.duc --viewport 100 200 800 600 --width 1600 --height 1200 -o viewport.png
scopture render <drawing-id> --element <model-id> --view top -o model.png
scopture render <drawing-id> --element <model-id> --view-config ./view.json -o model-custom.png

Omit --out on drawing create to create a remote drawing. Render targets accept local paths or remote IDs. --viewport selects scene coordinates; --width and --height set output pixels. Model view options require --element. The view JSON supports camera, display, material, clipping, and explode settings.

Whole-canvas snapshots reuse saved model thumbnails. Explicit model renders evaluate their geometry for the requested camera; missing canvas previews are generated with bounded concurrency and cached locally. Local CAD exports accept --element <model-id> for STEP, STL, IFC and the other supported geometry formats. active-3d-model also needs an explicit element when multiple models exist. diff accepts local paths and remote drawing IDs; remote comparisons download authorized snapshots into temporary storage. --server applies to remote Python targets.

STL exports accept optional tessellation settings on local and remote targets:

scopture export ./assembly.duc --element <model-id> --format stl --tolerance 0.2 --angular-tolerance 0.5 -o preview.stl

Larger settings produce fewer triangles and a coarser surface approximation. Angular tolerance is in radians. Generated STL exports default to linear setting 0.01 and angular setting 0.25; use --tolerance 0.001 --angular-tolerance 0.1 for the previous fine settings. These settings control tessellation, not the CAD source. A linked STL already contains triangles; use its original CAD source to control tessellation.

Issue LifecycleCopy Anchor Link

These commands accept a local .duc path or a remote drawing ID:

scopture issues create ./assembly.duc --title "Inspect mount" --content "Check fatigue" --json
scopture issues close ./assembly.duc <issue-id>
scopture issues reopen ./assembly.duc <issue-id>
scopture issues dismiss ./assembly.duc <issue-id> --reason "Duplicate"
scopture issues update ./assembly.duc <issue-id> --title "Inspect revised mount"

Status changes append timestamped entries to the Issue conversation. Reopening or closing preserves the last dismissal reason, while each dismissal event keeps its own reason. Remote Issue updates use the Issue service and its permission checks; SQL writes to drawing content do not update remote Issue records.