# CLI Guide
The `northroot-cli` tool provides a command-line interface for demonstrating workflows, validating proofs, and benchmarking operations.
## Installation
The CLI is included with the library. Build it with:
```bash
cargo build --bin northroot-cli --release
```
Or run directly:
```bash
cargo run --bin northroot-cli -- <command>
```
## Commands
### `demo workflow`
Demonstrates the complete end-to-end PoSH → PoX workflow:
1. **Create Method Shape (PoSH)**: Creates a span shape and computes method shape hash
2. **Create Span Commitment (PoX)**: Creates a span commitment and computes its hash
3. **Sign Span Commitment**: Generates an ed25519 signature over the commitment
4. **Verify Signature**: Verifies the signature using the verifying key
5. **Create Trace**: Creates a trace with multiple spans
6. **Compute Trace Roots**: Computes trace set root, sequence root, and identity root
**Usage:**
```bash
cargo run --bin northroot-cli -- demo workflow
```
**Output:**
The command displays colored output showing each step of the workflow, including all computed hashes and verification results.
### `bench hash`
Benchmarks hash and canonicalization operations, reporting throughput in operations per second.
**Usage:**
```bash
cargo run --bin northroot-cli -- bench hash
```
**What it benchmarks:**
- SHA-256 computation (1KB input)
- Span shape canonicalization
- Span commitment hash computation
**Output:**
Reports iterations, elapsed time, and throughput for each operation.
### `validate <file>`
Validates a proof JSON file by:
- Detecting the proof type (PoSH Method Shape, PoX Span Commitment, Trace, or Trace Roots)
- Validating signature formats (if present)
- Computing and displaying hashes
- Reporting any validation errors
**Usage:**
```bash
cargo run --bin northroot-cli -- validate tests/golden/pox_span_commitment.json
```
**Supported file types:**
- Method Shape Manifest (PoSH)
- Span Commitment (PoX)
- Signed Span (PoX)
- Trace (PoX)
- Trace Roots (PoX)
**Output:**
Shows detected proof type, computed hashes, and validation results with colored indicators (✓ for success, ✗ for errors).
## Examples
### Validate a golden file
```bash
cargo run --bin northroot-cli -- validate tests/golden/posh_method_shape.json
```
### Run workflow demo
```bash
cargo run --bin northroot-cli -- demo workflow
```
### Quick performance check
```bash
cargo run --bin northroot-cli -- bench hash
```
## Integration with CI/CD
The CLI can be used in CI/CD pipelines for validation:
```bash
# Validate all golden files
for file in tests/golden/*.json; do
cargo run --bin northroot-cli -- validate "$file" || exit 1
done
```
## Troubleshooting
**Error: "Could not identify proof type"**
- Ensure the JSON file is valid JSON
- Check that the file matches one of the supported proof types
- Verify the schema version matches expected values
**Error: "Failed to read file"**
- Check that the file path is correct
- Ensure the file exists and is readable
**Performance warnings**
- Benchmarks are run with 10,000 iterations by default
- Results may vary based on system load and hardware