Ranvier CLI

The Ranvier CLI provides schematic and trace tooling for the Ranvier Typed Decision Engine.

Install

cargo install ranvier-cli

Usage

ranvier --help

Create a new scaffold with macro-first baselines:

ranvier new my-api --template api

ranvier new my-worker --template worker

ranvier new my-scheduler --template scheduler

Common Commands

Generate a schematic JSON from a workspace example:

ranvier schematic basic-schematic --output schematic.json

Compare schematic structure between two git refs:

ranvier schematic diff \

  --example basic-schematic \

  --base main \

  --head HEAD

Diff report now includes transition-level change sets:

1. added/removed transitions
2. modified transition signatures
3. Bus capability policy changes (bus_allow/bus_deny)
4. schema version metadata (base_schema_version, head_schema_version)

Schema compatibility policy:

• schema_version is embedded in exported Schematic JSON.
• schematic diff requires matching base/head schema_version values.
• CLI accepts only supported schema major versions (current major derived from 1.0).

Enforce schematic policy rules against diff result:

ranvier schematic policy check \

  --example basic-schematic \

  --base main \

  --head HEAD \

  --deny-node-removal

Run policy check using repository policy file (.ranvier/policy.toml):

ranvier schematic policy check \

  --example basic-schematic \

  --base main \

  --head HEAD \

  --workspace ./ranvier \

  --policy-file ./.ranvier/policy.toml

Build a status page HTML from a schematic JSON file:

ranvier status build --file schematic.json --output ./dist/status

Generate a status page directly from an example:

ranvier status from-schematic basic-schematic --output ./dist/status

Generate trace projection artifacts from a schematic:

ranvier status projection-from-schematic basic-schematic \

  --output ./dist/trace \

  --circuit-version 0.1.0

Generate projection artifacts from a timeline capture:

ranvier status projection-from-timeline ./dist/sample.timeline.json \

  --output ./dist/trace \

  --service "Ranvier Service" \

  --circuit-id order_api \

  --circuit-version 0.1.0

Generate projection artifacts directly from an example:

ranvier status projection-from-example order-processing-demo \

  --output ./dist/trace-order \

  --service "Ranvier Service" \

  --circuit-id order_processing \

  --circuit-version 0.1.0

Run the repository smoke check for projection-from-example:

pwsh ./cli/scripts/smoke_projection_from_example.ps1

Run projection drift check (example -> timeline -> projection equivalence):

pwsh ./cli/scripts/projection_drift_check.ps1

ranvier test — Headless Collection Runner

Run API collections from the CLI with assertion evaluation, capture chaining, and CI-friendly output.

Usage

ranvier test --collection ./tests/api/orders.ranvier-bundle.json

Flags

CI Integration

# GitHub Actions example
- name: Run API tests
  run: |

    ranvier test \
      --collection "./tests/api/**/*.ranvier-bundle.json" \
      --env ./tests/api/.env.ci \
      --target http://localhost:3000 \
      --output ./test-results/api-junit.xml \
      --bail

# Upload JUnit results
- name: Publish test results
  uses: dorny/test-reporter@v1
  if: always()
  with:
    name: API Tests
    path: ./test-results/api-junit.xml
    reporter: java-junit

Glob support allows running multiple collections in one invocation:

ranvier test -c "./tests/**/*.ranvier-bundle.json" --output results.xml

Capture chaining lets later requests reference values extracted from earlier responses using {{capture.field}} syntax in request templates.

Notes

• The CLI expects example names from the workspace when used in repository mode.
• Projection artifacts feed the inspector endpoints /trace/public and /trace/internal.
• Policy file format uses [schematic] section; repository baseline is ranvier/.ranvier/policy.toml.example.
• GitHub Actions PR comment template is available at .github/workflows/templates/schematic-diff-policy-pr-comment.yml.