CLI Reference

Implemented

The jigspec CLI executes and validates pipeline spec files. It is the primary way to run JigSpec pipelines today.

Installation

npm install -g @jigspec/cli
# or with pnpm
pnpm add -g @jigspec/cli

Verify:

jigspec --version   # 1.0.0 at time of writing

jigspec run

Execute a pipeline file.

jigspec run <file> [options]

Arguments

Argument	Description
<file>	Path to a .pipe.yaml pipeline file

Options

Flag	Description
--input <key=value...>	One or more key=value pairs as pipeline input
--input-file <path>	Path to a JSON file whose contents become the pipeline input
--json	Write the full result as JSON to stdout instead of the default progress display

Input sources

Input is resolved in priority order:

1. --input flags (highest priority)
2. --input-file JSON file
3. stdin — if stdin is not a TTY, it is read and parsed as JSON
4. Empty object {} (fallback)

Key=value flags

jigspec run pipeline.pipe.yaml --input topic="quantum computing" --input style="casual"

Each --input flag takes one key=value pair. Repeat the flag for multiple inputs.

JSON file

jigspec run pipeline.pipe.yaml --input-file input.json

Where input.json is:

{ "topic": "quantum computing", "style": "casual" }

stdin

Pipe JSON directly into the pipeline:

echo '{"topic": "quantum computing"}' | jigspec run pipeline.pipe.yaml

Or from a file:

cat input.json | jigspec run pipeline.pipe.yaml

stdin is only read when it is not a TTY, so interactive use is not affected.

JSON output

jigspec run pipeline.pipe.yaml --input topic="AI" --json

Writes a JSON object to stdout with these fields:

{
  "status": "completed",
  "run_id": "abc123",
  "workspace": "/tmp/jigspec-abc123",
  "outputs": { "text": "/tmp/jigspec-abc123/result.md" },
  "duration_ms": 4210
}

If the pipeline fails, status is "failed" and error contains the error message. Exit code is 1.

Exit codes

Code	Meaning
0	Pipeline completed successfully
1	Pipeline failed

Progress display

By default, jigspec run writes step progress to stderr as each step starts and completes. This keeps stdout clean for capturing pipeline output in scripts.

---

jigspec validate

Validate a pipeline file without executing it.

jigspec validate <file>

Parses and schema-validates the pipeline. Reports all errors and warnings, then exits.

Arguments

Argument	Description
<file>	Path to a .pipe.yaml pipeline file

Output

On success:

✓ pipeline.pipe.yaml is valid

On failure, one error per line on stderr:

error: steps[0].outputs: Required
error: steps[1].action: Invalid literal value, expected "ai"

Warnings (e.g., unresolved secrets) are printed on stderr but do not affect the exit code.

Exit codes

Code	Meaning
0	File is valid
1	File is invalid (schema errors)

Use validate in CI to catch spec errors before running pipelines in production:

jigspec validate pipeline.pipe.yaml && jigspec run pipeline.pipe.yaml --input-file input.json

---

jigspec app

Implemented

Open the JigSpec app — a single local process that hosts the run list, the pipeline editor, and the live execution viewer under one URL. This is the primary entry point for interactive work; reach for jigspec run when you want a headless, script-friendly execution.

jigspec app [file] [options]

Arguments

Argument	Description
[file]	Optional .pipe.yaml path. When present, the app opens directly on the editor with that file loaded (#/edit/<file>).

Options

Flag	Description
--run <id>	Open the viewer directly on a specific run ID (#/run/<id>). Mutually exclusive with a positional file.
--port <number>	Port to bind (default 4400).
--host <address>	Host to bind (default 127.0.0.1). Use 0.0.0.0 to expose on your LAN.
--no-open	Do not auto-open the system browser when the server starts.
--json	Write {"url":"...","port":N} as one JSON line to stdout. Also implies --no-open. Useful when scripting.

What gets routed where

The app is a single-page application with hash-based routing. The startup URL depends on your args:

• jigspec app → root URL #/ (run list)
• jigspec app pipeline.pipe.yaml → #/edit/pipeline.pipe.yaml (editor)
• jigspec app --run abc123 → #/run/abc123 (viewer for run abc123)

The same server exposes REST + SSE endpoints consumed by the app UI (run execution, file editing, registry search, bug reports). These endpoints are internal to the app and are not yet documented as a stable external API.

Example

Open the app on a specific file, exposed on your LAN:

jigspec app my-pipeline.pipe.yaml --host 0.0.0.0 --port 8080

Script-friendly mode (no browser, JSON stdout):

URL=$(jigspec app --json | jq -r .url)
echo "Server at $URL"

Graceful shutdown

The server listens for SIGINT (Ctrl+C) and SIGTERM and shuts down cleanly. Any in-flight pipeline runs continue in detached child processes so closing the server does not kill them mid-execution.