@flowspine/cli

Command-line interface for Flowspine project workflows.

Use this package when you need operational tasks such as:

• scaffold a new Flowspine project
• build a catalog from process files
• validate extracted process graphs
• export graph output
• watch files during development

This package is the standard workflow layer over @flowspine/core and @flowspine/extractor.

Do not use it as a runtime engine.

The CLI works with process catalogs and repository workflows.
It does not execute full process graphs.

Installation

pnpm add -D @flowspine/cli@beta

Run commands with:

pnpm exec flowspine

You can also expose it through package scripts.

Mental Model

Typical Flowspine workflow:

1. define processes with @flowspine/core
2. build a catalog with @flowspine/cli
3. validate the catalog
4. export graphs if needed

Use CLI when the task is operational:

• build
• validate
• export
• scaffold
• watch

If the task is about:

• process meaning or step logic → use @flowspine/core
• custom static analysis in code → use @flowspine/extractor

Commands

Create a new project scaffold

flowspine new <name> [--dir <path>]

Example:

pnpm exec flowspine new demo

This generates a starter Flowspine process file.

Build catalog

flowspine build [--glob <pattern>] [--out <path>]

Examples:

pnpm exec flowspine build
pnpm exec flowspine build --glob "processes/**/*.ts" --out ".flowspine/catalog.json"

Use this to scan process files and generate a catalog JSON file.

Validate catalog

flowspine validate [--input <path>] [--strict] [--warnings-as-errors] [--format text|json]

Examples:

pnpm exec flowspine validate
pnpm exec flowspine validate --input ".flowspine/catalog.json"
pnpm exec flowspine validate --input ".flowspine/catalog.json" --format json
pnpm exec flowspine validate --input ".flowspine/catalog.json" --strict

Validation checks include:

• duplicate process IDs
• missing start/end nodes
• broken edge references
• unreachable nodes
• nodes with no path to end
• extractor diagnostics as warnings
• weak branch fanout as warnings

Use --strict when warnings should fail the validation flow.

Use --warnings-as-errors when your workflow treats warnings as blocking.

Export graph output

flowspine export [--input <path>] [--format json|mermaid] [--out <path>]

Examples:

pnpm exec flowspine export --input ".flowspine/catalog.json" --format json
pnpm exec flowspine export --input ".flowspine/catalog.json" --format mermaid --out ".flowspine/catalog.mmd"

Use this when you need a machine-readable export or a Mermaid diagram.

Watch process files

flowspine watch [--glob] [--out] [--debounce] [--polling] [--poll-interval] [--no-await-write-finish] [--no-validate] [--strict] [--warnings-as-errors]

Example:

pnpm exec flowspine watch --glob "processes/**/*.ts" --out ".flowspine/catalog.json"

Use watch mode during active development to rebuild and optionally validate automatically.

Common Workflow

Local development

pnpm exec flowspine build --glob "processes/**/*.ts" --out ".flowspine/catalog.json"
pnpm exec flowspine validate --input ".flowspine/catalog.json"
pnpm exec flowspine export --input ".flowspine/catalog.json" --format mermaid --out ".flowspine/catalog.mmd"

Continuous watch

pnpm exec flowspine watch --glob "processes/**/*.ts" --out ".flowspine/catalog.json"

CI-style validation

pnpm exec flowspine build --glob "processes/**/*.ts" --out ".flowspine/catalog.json"
pnpm exec flowspine validate --input ".flowspine/catalog.json" --strict --warnings-as-errors

What Validation Actually Protects

The CLI helps detect structural problems before they spread into tooling or diagrams.

Examples:

• process graph contains unreachable nodes
• a branch does not split meaningfully
• an edge points to a missing node
• extracted catalog contains duplicate process IDs

This is why the CLI is usually the right default for repository-level Flowspine workflows.

When To Use Other Packages

Use @flowspine/core when you need to:

• define process structure
• define step contracts
• implement handler logic
• run individual steps

Use @flowspine/extractor when you need to:

• build custom programmatic analysis
• embed extraction into your own scripts/tools
• inspect extraction behavior directly

Related Packages

• @flowspine/core
• @flowspine/extractor

License

Apache 2.0

Copyright

Copyright (c) 2026 Flowspine contributors.