Edge CLI Tools Reference

The Pyvorin Edge Toolkit

The Pyvorin Edge SDK ships with four command-line tools that cover the full lifecycle of an edge deployment: benchmarking performance, generating boilerplate, inspecting runtime state, and cryptographically signing bundles. This article is the definitive reference for every subcommand, every flag, and every exit code. Every example includes real output so you know exactly what to expect.

pyv-edge-benchmark

Located at tools/pyv-edge-benchmark, this CLI measures latency percentiles, throughput, memory usage, and — when Pyvorin is available — the reduction ratio between CPython and compiled execution.

Available Suites

• sensor_pipeline — Filter and average a list of sensor values.
• window_aggregation — Sliding window mean over an array.
• privacy_filter — Clamp and transform values.
• cloud_sync — Serialize and sum string lengths.
• full_stack — Combines all four workloads into a single pipeline.

Subcommands

run — Run a single benchmark suite under CPython

pyv-edge-benchmark run --suite sensor_pipeline --iterations 1000 --output result.json
  

{
  "command": "run",
  "suite": "sensor_pipeline",
  "iterations": 1000,
  "timestamp": "2024-05-30T14:22:10+00:00",
  "results": {
    "sensor_pipeline": {
      "latency_ms": {
        "p50": 0.0123,
        "p95": 0.0156,
        "p99": 0.0210
      },
      "throughput_ops_sec": 81234.56,
      "memory_peak_mb": 0.2345
    }
  }
}
  

compare — Compare CPython vs Pyvorin side-by-side

pyv-edge-benchmark compare --suite full_stack --iterations 500 --output compare.json
  

{
  "command": "compare",
  "suite": "full_stack",
  "iterations": 500,
  "timestamp": "2024-05-30T14:25:33+00:00",
  "results": {
    "full_stack": {
      "cpython": {
        "latency_ms": {"p50": 0.0456, "p95": 0.0523, "p99": 0.0612},
        "throughput_ops_sec": 10964.91,
        "memory_peak_mb": 0.3125
      },
      "pyvorin": {
        "latency_ms": {"p50": 0.0089, "p95": 0.0101, "p99": 0.0123},
        "throughput_ops_sec": 56179.77,
        "memory_peak_mb": 0.1562
      },
      "reduction_ratio": 0.8048,
      "backend_used": "native"
    }
  }
}
  

list — List available benchmark suites

pyv-edge-benchmark list
  

Available benchmark suites:
  - sensor_pipeline
  - window_aggregation
  - privacy_filter
  - cloud_sync
  - full_stack
  

report — Generate a markdown report from JSON results

pyv-edge-benchmark report --input compare.json --output report.md
  

# Pyvorin Edge Benchmark Report

**Command:** compare
**Suite:** full_stack
**Iterations:** 500
**Timestamp:** 2024-05-30T14:25:33+00:00

## full_stack

| Metric | CPython | Pyvorin |
|--------|---------|---------|
| p50 latency (ms) | 0.0456 | 0.0089 |
| p95 latency (ms) | 0.0523 | 0.0101 |
| p99 latency (ms) | 0.0612 | 0.0123 |
| throughput (ops/sec) | 10964.91 | 56179.77 |
| memory peak (MB) | 0.3125 | 0.1562 |
| reduction ratio | - | 0.8048 |
| backend | - | native |
  

Flag Reference

pyv-edge-generate

Located at tools/pyv-edge-generate, this CLI scaffolds configs, pipeline code, sensor definitions, privacy policies, and Dockerfiles.

Subcommands

config — Generate a config.toml template

pyv-edge-generate config --output ./config.toml
  

# Pyvorin Edge Configuration Template
# Generated by pyv-edge-generate

[edge]
name = "edge-node-01"
version = "1.0.0"
region = "us-east-1"

[ingest]
batch_size = 1000
flush_interval_ms = 5000

[privacy]
enable_filter = true
max_value = 100
redaction_mask = "****"

[sync]
endpoint = "https://api.pyvorin.com/v1/ingest"
retry_count = 3
timeout_seconds = 30

[telemetry]
enabled = true
sample_rate = 0.1
  

pipeline — Generate a pipeline.py boilerplate

pyv-edge-generate pipeline --output ./pipeline.py
  

# Pyvorin Edge Pipeline Template
# Generated by pyv-edge-generate

from typing import List, Dict, Any


def ingest(data: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
    """Ingest raw sensor records."""
    return data


def transform(records: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
    """Apply transformations and privacy filters."""
    out = []
    for r in records:
        val = r.get("value", 0)
        if val > 100:
            val = 100
        out.append({"id": r.get("id"), "value": val})
    return out


def aggregate(records: List[Dict[str, Any]]) -> Dict[str, Any]:
    """Compute aggregates."""
    total = sum(r["value"] for r in records)
    return {"count": len(records), "total": total}


def pipeline(data: List[Dict[str, Any]]) -> Dict[str, Any]:
    """Run full pipeline: ingest -> transform -> aggregate."""
    records = ingest(data)
    records = transform(records)
    return aggregate(records)


if __name__ == "__main__":
    sample = [{"id": i, "value": i * 10} for i in range(10)]
    print(pipeline(sample))
  

sensors — Generate a sensors.json manifest

pyv-edge-generate sensors --count 3 --output ./sensors.json
  

[
  {
    "id": "sensor-000",
    "type": "temperature",
    "location": "zone-A",
    "interval_ms": 1000
  },
  {
    "id": "sensor-001",
    "type": "temperature",
    "location": "zone-B",
    "interval_ms": 1000
  },
  {
    "id": "sensor-002",
    "type": "temperature",
    "location": "zone-C",
    "interval_ms": 1000
  }
]
  

policy — Generate a privacy policy JSON

pyv-edge-generate policy --output ./policy.json
  

{
  "version": "1.0.0",
  "created": "2024-05-30T14:30:00+00:00",
  "retention_days": 30,
  "fields": [
    {"name": "user_id", "action": "hash", "algorithm": "sha256"},
    {"name": "email", "action": "mask", "pattern": "****"},
    {"name": "ssn", "action": "redact"}
  ],
  "auditing": {
    "enabled": true,
    "log_level": "info"
  }
}
  

docker — Generate a Dockerfile

pyv-edge-generate docker --output ./Dockerfile
  

# Pyvorin Edge Deployment Dockerfile
# Generated by pyv-edge-generate

FROM python:3.11-slim

WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY . .

# Health check
HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
  CMD python -c "print('ok')" || exit 1

# Run edge pipeline
CMD ["python", "-m", "edge.pipeline"]
  

Flag Reference

pyv-edge-inspect

Located at tools/pyv-edge-inspect, this CLI inspects bundle manifests, ABI contracts, configuration files, SQLite databases, sync queues, and privacy audit chains. Every subcommand supports --json for machine-readable output.

Subcommands

manifest — Inspect a bundle manifest

pyv-edge-inspect manifest ./bundles/main/manifest.json
  

Manifest: ./bundles/main/manifest.json
Keys: version, created, files, signature, public_key
Files: 12
+-------------------+------------------------------------------------------------------+
| File              | Hash                                                             |
+-------------------+------------------------------------------------------------------+
| pipeline.py       | a3f7b2d1e8c9a4b5...                                              |
| policy.json       | 8e2c4f6a1b3d5e7c...                                              |
| sensors.json      | 9d1e3f5a7b2c4d6e...                                              |
+-------------------+------------------------------------------------------------------+
  

abi — Show ABI symbols from a shared object

pyv-edge-inspect abi ./modules/sensor_driver.so --json
  

{
  "path": "./modules/sensor_driver.so",
  "symbol_count": 4,
  "symbols": [
    {"address": "0000000000001149", "type": "FUNC", "name": "init_driver"},
    {"address": "00000000000011a3", "type": "FUNC", "name": "read_sample"},
    {"address": "0000000000001207", "type": "FUNC", "name": "close_driver"},
    {"address": "0000000000004000", "type": "OBJECT", "name": "driver_state"}
  ]
}
  

config — Validate and flatten a config file

pyv-edge-inspect config ./config.toml
  

Config: ./config.toml
+--------------------------+---------------+
| Key                      | Value         |
+--------------------------+---------------+
| edge.name                | edge-node-01  |
| edge.version             | 1.0.0         |
| edge.region              | us-east-1     |
| ingest.batch_size        | 1000          |
| ingest.flush_interval_ms | 5000          |
| privacy.enable_filter    | True          |
| sync.endpoint            | https://...   |
+--------------------------+---------------+
  

db — Inspect an SQLite database

pyv-edge-inspect db /var/lib/pyvorin/edge_store.db --table readings
  

path: /var/lib/pyvorin/edge_store.db
table: readings
row_count: 15234

Schema:
+------+--------------+---------+--------+---------+----+
| cid  | name         | type    | notnull| default | pk |
+------+--------------+---------+--------+---------+----+
| 0    | id           | INTEGER | 0      | None    | 1  |
| 1    | sensor_name  | TEXT    | 0      | None    | 0  |
| 2    | timestamp    | REAL    | 0      | None    | 0  |
| 3    | value        | REAL    | 0      | None    | 0  |
| 4    | unit         | TEXT    | 0      | None    | 0  |
| 5    | metadata_json| TEXT    | 0      | None    | 0  |
+------+--------------+---------+--------+---------+----+
  

queue — Show cloud sync queue statistics

pyv-edge-inspect queue /var/lib/pyvorin/sync_queue.db --json
  

{
  "path": "/var/lib/pyvorin/sync_queue.db",
  "queues": [
    {
      "table": "sync_queue",
      "row_count": 847,
      "status_counts": {}
    }
  ]
}
  

audit — Show privacy audit chain summary

pyv-edge-inspect audit /var/lib/pyvorin/edge_store.db
  

path: /var/lib/pyvorin/edge_store.db
+------------------+-----------+
| Table            | Row Count |
+------------------+-----------+
| privacy_audit    | 1240      |
+------------------+-----------+
  

Flag Reference

pyv-edge-sign

Located at tools/pyv-edge-sign, this CLI signs and verifies Edge bundles using Ed25519 signatures and SHA-256 file hashes. It is the command-line interface to the same signing logic used by BundleSigner and BundleVerifier.

Subcommands

create-key — Generate an Ed25519 key pair

pyv-edge-sign create-key --output ./keys
  

Keys written to ./keys
  

Produces:

• ./keys/private.pem — PKCS#8 PEM private key
• ./keys/public.pem — SubjectPublicKeyInfo PEM public key

sign — Sign a bundle directory

pyv-edge-sign sign \
  --bundle ./bundles/main \
  --key ./keys/private.pem \
  --output ./bundles/main/manifest.json
  

Manifest written to ./bundles/main/manifest.json
  

The manifest contains:

{
  "version": "1.0",
  "created": "2024-05-30T14:35:00+00:00",
  "files": {
    "pipeline.py": "a3f7b2d1e8c9a4b5...",
    "policy.json": "8e2c4f6a1b3d5e7c..."
  },
  "signature": "base64-ed25519-sig...",
  "public_key": "base64-public-key..."
}
  

verify — Verify a signed bundle

pyv-edge-sign verify \
  --bundle ./bundles/main \
  --manifest ./bundles/main/manifest.json
  

Bundle verified successfully
  

If verification fails, the tool prints the specific file mismatch and exits with code 1:

Error: bundle contents do not match manifest
  mismatch: pipeline.py
  

check — Check bundle integrity without signature verification

pyv-edge-sign check --bundle ./bundles/main
  

a3f7b2d1e8c9a4b5...  pipeline.py
8e2c4f6a1b3d5e7c...  policy.json
9d1e3f5a7b2c4d6e...  sensors.json
  

This is useful for CI pipelines that want to assert that a bundle's contents match a known manifest without having the private key available.

Flag Reference

Exit Codes

Combining Tools in CI/CD

A production CI pipeline typically chains these tools together. Here is a complete example using a GitHub Actions workflow:

# .github/workflows/edge-release.yml
name: Build and Sign Edge Bundle

on:
  push:
    tags: ["v*"]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install Edge SDK
        run: pip install -e .

      - name: Generate bundle
        run: |
          pyv-edge-generate config --output bundle/config.toml
          pyv-edge-generate pipeline --output bundle/pipeline.py
          pyv-edge-generate sensors --count 10 --output bundle/sensors.json
          pyv-edge-generate policy --output bundle/policy.json

      - name: Run benchmarks
        run: |
          pyv-edge-benchmark compare --suite full_stack --iterations 1000 \
            --output benchmark.json

      - name: Sign bundle
        env:
          SIGNING_KEY: ${{ secrets.EDGE_SIGNING_KEY }}
        run: |
          echo "$SIGNING_KEY" > /tmp/signing_key.pem
          pyv-edge-sign sign \
            --bundle ./bundle \
            --key /tmp/signing_key.pem \
            --output ./bundle/manifest.json
          shred -u /tmp/signing_key.pem

      - name: Verify signature
        run: |
          pyv-edge-sign verify \
            --bundle ./bundle \
            --manifest ./bundle/manifest.json

      - name: Inspect manifest
        run: pyv-edge-inspect manifest ./bundle/manifest.json

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: edge-bundle-${{ github.ref_name }}
          path: bundle/
  

Operational Best Practices

• Pin tool versions. The CLI tools are part of the Edge SDK. Pin the SDK version in requirements.txt so that CI and production use identical command semantics.
• Use --json for automation. All pyv-edge-inspect subcommands support --json. Pipe the output to jq in shell scripts for reliable parsing.
• Benchmark before every release. A regression in pyv-edge-benchmark compare is an early warning that a code change has introduced a performance cliff.
• Sign after every build. The manifest must be generated from the exact files that will be deployed. Do not reuse manifests across builds.
• Inspect before deploy. Run pyv-edge-inspect manifest and pyv-edge-sign verify as the final step before OTA distribution. This catches build-system bugs that might omit files.

Summary

The Pyvorin Edge CLI toolkit covers the entire deployment lifecycle. pyv-edge-benchmark measures and compares performance. pyv-edge-generate scaffolds configs, pipelines, sensors, policies, and Dockerfiles. pyv-edge-inspect diagnoses manifests, ABIs, databases, queues, and audit chains. pyv-edge-sign cryptographically signs and verifies bundles using Ed25519. Together they provide a reproducible, automatable, and verifiable workflow from development to production — all without leaving the terminal.