CLI reference ​

This page covers command-line entry points published by the JavaScript and Python client packages. Repository npm scripts are development tasks and are not package CLI commands.

For the server setup and endpoint behavior behind these commands, see the REST API guide. To see complete macro workflows, run the package examples; exported library types are listed in the TypeScript and Python references.

JavaScript package ​

Install @constructorfleet/sketchforge3d (requires Node.js >=20). Its published binaries are registered in packages/sketchforge-client/package.json.

sketchforge-macro ​

Run a macro file against the SketchForge REST API. Use SKETCHFORGE_API_TOKEN for authentication; SKETCHFORGE_URL defaults to http://127.0.0.1:3000. A macro may target an existing project with SKETCHFORGE_PROJECT_ID or --project.

text
sketchforge-macro <macro-file> [--param=value ...] [--project=<id>] [--json]

Environment:
  SKETCHFORGE_API_TOKEN   required; the server's API token
  SKETCHFORGE_URL         default http://127.0.0.1:3000
  SKETCHFORGE_PROJECT_ID  the project for a macro declaring project: "target"

Direct project and file commands ​

The same executable can list, create, and delete projects, export a selected project, and import an STL, OBJ, or SVG file:

text
sketchforge-macro projects list
sketchforge-macro projects create <name>
sketchforge-macro projects delete <project-id>
sketchforge-macro export --format <fmt> --out <file> [--project <id>]
sketchforge-macro import <file> [--project <id>]

Export uses --project or SKETCHFORGE_PROJECT_ID. Import writes to the selected project when supplied; otherwise it creates a project named after the input file.

sketchforge-mcp ​

Starts the package's MCP server on stdio using JSON-RPC. Configure it as an MCP server (for example, npx -y -p @constructorfleet/sketchforge3d sketchforge-mcp); it does not expose a separate shell command interface or a --help option. Local project access uses SKETCHFORGE_PROJECTS_DIR; remote REST calls require SKETCHFORGE_API_TOKEN. Tool behavior and configuration are documented in the package README.

Python package ​

Install the sketchforge3d distribution from PyPI. The project metadata publishes sketchforge-macro as its console script. The same runner is available as python -m sketchforge3d and python -m sketchforge3d.macro.

Macro runner ​

text
usage: python -m sketchforge3d.macro [-h] [--describe] [--project PROJECT_ID]
                                     [--json]
                                     file

Run a SketchForge macro file against the server named by the environment.

positional arguments:
  file                  the macro file to run

options:
  -h, --help            show this help message and exit
  --describe            show macro metadata without running it
  --project PROJECT_ID  the project for a target macro
  --json                print the run report as JSON

Environment: SKETCHFORGE_API_TOKEN (required), SKETCHFORGE_URL (default
http://127.0.0.1:3000), SKETCHFORGE_PROJECT_ID (for a target macro).

The Python runner uses the same environment variables and project selection behavior as the JavaScript macro runner. See the Python package guide for examples and parameter rules.

Documentation version: 1.30.0 · Repository revision: 1cb9fee8dff4d394684c229dd67a21da539d167f · View source