# Ranvier CLI
The Ranvier CLI provides schematic and trace tooling for the Ranvier Typed Decision Engine.
## Install
```bash
cargo install ranvier-cli
```
## Usage
```bash
ranvier --help
```
Create a new scaffold with macro-first baselines:
```bash
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:
```bash
ranvier schematic basic-schematic --output schematic.json
```
Compare schematic structure between two git refs:
```bash
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:
```bash
ranvier schematic policy check \
--example basic-schematic \
--base main \
--head HEAD \
--deny-node-removal
```
Run policy check using repository policy file (`.ranvier/policy.toml`):
```bash
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:
```bash
ranvier status build --file schematic.json --output ./dist/status
```
Generate a status page directly from an example:
```bash
ranvier status from-schematic basic-schematic --output ./dist/status
```
Generate trace projection artifacts from a schematic:
```bash
ranvier status projection-from-schematic basic-schematic \
--output ./dist/trace \
--circuit-version 0.1.0
```
Generate projection artifacts from a timeline capture:
```bash
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:
```bash
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`:
```powershell
pwsh ./cli/scripts/smoke_projection_from_example.ps1
```
Run projection drift check (`example -> timeline -> projection` equivalence):
```powershell
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
```bash
ranvier test --collection ./tests/api/orders.ranvier-bundle.json
```
### Flags
| `--collection` | `-c` | (required) | Path or glob to `.ranvier-bundle.json` collection files |
| `--env` | `-e` | | Environment variables file (`.env` or `.json`) |
| `--target` | `-t` | `http://localhost:3000` | Base URL of the target server |
| `--timeout` | | `30000` | Per-request timeout in milliseconds |
| `--output` | `-o` | | Write JUnit XML report to the given path |
| `--verbose` | `-v` | `false` | Print request/response details for each step |
| `--bail` | | `false` | Stop on first assertion failure |
| `--filter` | `-f` | | Run only requests whose name matches the given pattern |
| `--dry-run` | | `false` | Parse and validate collection without executing requests |
### CI Integration
```yaml
# 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
```
```yaml
# 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:
```bash
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`.