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   # 0.1.0

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