CLI

scan is the command-line tool for SCAN documents — validate a file locally (in CI, pre-commit, wherever) or export it to SVG/PNG/JSON without opening the board.

Package: @spherescan/cli (Apache-2.0), part of the open-source scan-js toolkit. It is not the Sphere product platform — it has no login, no cloud save, and no Library.

Install

npm install -g @spherescan/cli

Or run it without installing:

npx @spherescan/cli validate architecture.scan.yaml

Once installed, the binary is scan.

Synopsis

scan <command> [options]
scan -h | --help

Running scan with no command, or with -h/--help, prints usage. -h/--help exits 0; a bare scan with no arguments exits 1.

Commands

scan validate <file.yaml>

Parses the file against the SCAN schema (Zod), then runs semantic validation (dangling references, duplicate IDs, and similar structural checks).

scan validate architecture.scan.yaml

On success, prints a one-line summary and exits 0:

OK  scan=0.1 system=order-platform elements=12

elements is the total count of components, channels, external systems, agents, and repositories in the document.

On schema failure, prints the parser error and exits 1:

INVALID  schema: <parse error message>

On semantic failure, prints each issue with its severity, error code, and document path, then exits 1:

INVALID  1 error(s)
  [error] unknown-connection-endpoint @ connections[0].from: Connection from "does-not-exist" does not exist

If the file doesn't exist, validate does not print a clean error — it throws an uncaught ENOENT and dumps a Node stack trace, exiting 1. Check the path exists before calling it in a script if you want a clean failure mode.

scan export svg <file.yaml> [-o <out.svg>]

Renders the document as SVG. Without -o, writes to stdout; with -o, writes to that file. Exits 0 on success.

scan export svg architecture.scan.yaml -o out.svg

scan export json <file.yaml> [-o <out.json>]

Serializes the parsed, validated model to JSON. Without -o, writes to stdout; with -o, writes to that file.

scan export json architecture.scan.yaml -o out.json

scan export png <file.yaml>

Not implemented in the Node CLI — always exits 1:

PNG export from CLI is not available in Node. Use: scan export svg <file> -o out.svg

Render PNG via the @spherescan/viewer package in a browser context instead, or convert the SVG output with an external tool.

Exit codes

Code	Meaning
0	Command succeeded, or -h/--help was shown
1	Validation failed, an unknown/missing command or file argument, export png, or an unhandled error (e.g. file not found)

Local workspace build

From a scan-js checkout, without installing the published package:

node packages/cli/dist/cli.js validate packages/model/fixtures/order-platform.yaml

Any scan <command> above works the same way, substituting node packages/cli/dist/cli.js <command> for scan <command>.