npm package: @flowspine/cli
Description: Flowspine CLI for build/validate/export/watch workflows (beta, not production-ready)
Latest version: 0.1.1-beta.20260407.1

﻿# @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

```bash
pnpm add -D @flowspine/cli@beta
```

Run commands with:

```bash
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

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

Example:

```bash
pnpm exec flowspine new demo
```

This generates a starter Flowspine process file.

---

### Build catalog

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

Examples:

```bash
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

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

Examples:

```bash
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

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

Examples:

```bash
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

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

Example:

```bash
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

```bash
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

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

### CI-style validation

```bash
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.