Pyvorin CLI Reference

pyvorin-native 1.0.9 ships two command-line surfaces, and the difference between them trips people up exactly once. The pyvorin console script — the binary on your PATH — exposes three licensing commands only. The full compiler toolchain is reached through python -m pyvorin, which exposes twenty-three subcommands. Both are documented below, every flag captured from --help output on the installed build and, where it mattered, from actually running the command.

If you script against these commands, read the exit-code notes as carefully as the flags. They are the automation contract.

The console script: pyvorin

The installed binary's complete help output:

usage: pyvorin [-h] {activate,status,check} ...

Pyvorin compiler toolchain

positional arguments:
  {activate,status,check}
    activate            Activate a Pyvorin license key
    status              Show the local license summary
    check               Run the hard license gate

Three commands, no global options beyond -h:

The product CLI: python -m pyvorin

Invoking python -m pyvorin loads the larger product CLI. Its subcommand list, verbatim from --help:

usage: pyvorin [-h] [--version]
  {version,doctor,run,bench,explain,support,compile,config,activate,
   licence-status,license-status,report,assess,hotspot,simd-info,build,
   inspect,login,logout,jobs,artifacts,cache,test,workloads} ...

The global --version flag prints a version banner. One quirk, honestly reported: on our installed 1.0.9 package the banner reads pyvorin 1.0.5, lagging the package version. The authoritative version is the package metadata and pyvorin.__version__, which report 1.0.9.

Environment and configuration

doctor checks the machine and reports [PASS], [WARN] or [FAIL] lines covering Python version, llvmlite, gcc, the runtime shared libraries, NumPy, optional dataframe libraries, the C compiler, AVX2 support, memory, disk, cache directory and licence state. Flags: --json for machine-readable output, --metrics/-m to append OpenMetrics text. On our host it flagged a licence warning and a missing columnar kernel — exactly the kind of pre-flight honesty you want from a doctor command.

config prints the compiler's default configuration — dozens of named optimisation toggles with their defaults, from enable_loop_fusion: True to enable_parallelism: False — with --json for the machine-readable form. simd-info lists the registered SIMD kernels; on our AVX2 host it reported 81 kernels across float, integer and string-batch operations, with --json available.

activate and licence-status (alias license-status) mirror the console script's licensing functions inside the product CLI. licence-status takes no options and prints a human summary; ours reported the tier, expiry, an activation URL and the matching pyvorin activate hint.

Compile, run and benchmark

run compiles a file and executes it: python -m pyvorin run file.py. Options: --function NAME/-f to target a specific function (auto-detected if omitted), --script-mode to run the file as __main__ with sys.argv passthrough, --compare to time the same loop against CPython and report a speedup, --runs N/-n (default 10), --warmup N/-w (default 3), --json, and --metrics/-m for OpenMetrics output. The optimisation flags --vectorize/--no-vectorize, --parallel/--no-parallel, --pgo/--no-pgo and --fast-math/--no-fast-math each exist in paired form.

bench runs the comparison benchmark: python -m pyvorin bench file.py [--function NAME] [--json] [--runs N] [--warmup N] [--script-mode] [--metrics], plus the same paired optimisation flags. The --json report is the automation surface: top-level correct and ground_truth, a report block with per-function status, compile_time_ms, fallback_used, fallback_reason, drift_detected, overflow_count, deopt_count and cpython_oracle_status, and a timing block with min, mean, median and p95. One verified constraint: the entrypoint must run without arguments, or bench exits with Ground-truth execution failed: … missing N required positional arguments. Use --function to select a zero-argument callable.

compile compiles without benchmarking: python -m pyvorin compile file.py. Options: -f/--function (all functions if omitted), --partial to allow partial compilation, --report PATH (also --output/-o) to write the JSON report to a file instead of stdout, --include-source, --explain-fallback, --fail-on-fallback, --backend {native,auto}, --json, -v. Exit codes, measured: 0 when every function compiled and validated; 1 when any function FAILED; 2 under --fail-on-fallback when any function fell back or compiled without runtime validation. A file of argument-taking functions can therefore exit 2 under the gate while a plain compile exits 0 with Runtime validation not performed noted per function — the gate treats an unverified compile with the same suspicion as a declined one.

explain reports why each function compiles or not, in the same per-function vocabulary, with --strict (exit non-zero if any function fails), --json and --metrics. On a small numeric file it printed Status: COMPILED_FULL, Oracle: passed, the optimisation passes applied with timings, and Public claim allowed: True.

Analysis commands

support shows per-function support tiers for a file: a table of function, status and unsupported-feature count, with -v for the per-feature reasons and --json for machine output. inspect produces a compatibility report with a summary line — on our test file it reported Native eligible: 1/1, Fallback required: 0/1, Failed: 0/1, Risk level: NONE — and --ir/--full to dump generated LLVM IR. assess runs the ETL compatibility assessment with a verdict (COMPATIBLE on our test) and per-finding category, line, message and severity. hotspot scores hot-loop kernel candidates; it scored our single-loop test function 48.00 with an escape-analysis field.

Account, server-side and utility commands

The remaining subcommands fall into three groups, and two of them deserve blunt descriptions.

Account commands. login [--email EMAIL] [--password PASSWORD] authenticates against the platform API and stores the token in a local config file; logout revokes it and deletes the file. These are the only product-CLI commands that handle account credentials.

Server-side job surfaces. jobs [--limit N] and artifacts [--artifact-id ID] [--output PATH] [--limit N] both require a prior login; without one they print [ERROR] Not logged in. Run: pyvorin login and exit 1. With a session, they list and download jobs and artefacts from the platform API. Be clear about what these are not: the native package compiles locally and creates no server-side records, so on a pure pyvorin-native installation these commands have nothing local to show. They exist for account-held artefact management, not for observing your own compilation.

Utility commands. cache status|clear manages the local compile cache — status prints the directory, file count and size (ours: 158 files, 1.20 MB under ~/.pyvorin_cache); clear removes it. report [run_id] [--json] prints, and tries to open, the dashboard report URL at app.pyvorin.com; it makes no compilation decision. test looks for a correctness harness at ./scripts/run_correctness.py relative to the current directory; the harness does not ship with the wheel, so on an installed package it prints Correctness harness not found yet. and exits 1 — the real correctness surface is the oracle inside compile and bench, documented on the correctness validation page. workloads is the internal workload-registry utility (list, run, build, compare, inspect) used to manage benchmark suites; its registry is empty on a fresh install and it is not part of day-to-day use. Finally build is deprecated: invoking it prints [ERROR] The 'build' subcommand is deprecated. Use 'pyvorin run' or 'pyvorin bench' instead.

Exit codes as an interface

The contract worth scripting against, all measured on the installed build:

A worked session, end to end

Putting the pieces together, here is the sequence we ran against the installed build while writing this reference — a complete verify-compile-measure pass on one small file:

# 1. Confirm the environment
python -m pyvorin doctor

# 2. Check every function in the file
python -m pyvorin support example.py
# add      COMPILED_PARTIAL   1

# 3. Compile with a saved report
python -m pyvorin compile example.py --report report.json
# add      COMPILED_FULL   260 ms | Runtime validation not performed: ...

# 4. Measure against CPython with correctness checked
python -m pyvorin bench example.py --json
# "correct": true, "ground_truth": ..., timing block

Each step reads naturally on its own, and together they form the shortest honest path from "is this machine ready" to "here is a validated timing". The exit code of step 3 is the CI signal; the JSON of step 4 is the record; step 2 is the explanation when either of the others surprises you.

Conventions that hold across commands

Four patterns repeat through the product CLI and are worth learning once. First, --json exists on every command that produces a report — support, inspect, assess, bench, compile, explain, doctor, simd-info, config, licence-status — and where a command prints a human table, the JSON form carries the same fields in stable names. Second, optimisation flags come in paired positive and negative forms (--vectorize/--no-vectorize and the same for parallel, PGO and fast-math), so scripts can pin the exact configuration they were validated against rather than inheriting defaults. Third, --metrics/-m appends OpenMetrics text to the commands that support it, for collectors. Fourth, the file argument is always a positional path to a .py file, and -f selects a function within it — the same two-slot pattern everywhere, which keeps composed shell pipelines readable.

Which surface to script against

One piece of judgement the reference cannot give you, so we will: script against python -m pyvorin with --json everywhere it exists, and reserve the pyvorin console script for licensing. The JSON reports are versioned field sets you can assert on; the human tables are not. In CI we pin --fail-on-fallback on files already claimed as native and a plain compile on files still migrating, because an exit-2 storm on unvalidated helpers teaches teams to ignore the gate. Whatever you choose, assert on exit codes first and parse reports second — the codes are the stable interface, and the reports are the detail behind them.

Where to go next

• Quick start — install, activate and compile your first function end to end.
• Error handling and diagnostics — the failure taxonomy behind the exit codes in the table above.
• Troubleshooting — fixes for the error messages these commands emit.
• Alerting and webhooks — turning these CLI signals into cron and CI checks.

Last reviewed 6 July 2026 against pyvorin-native 1.0.9 installed at /root/pvfinal. Every help block, flag list, output sample and exit code on this page was captured from real runs on 13 September 2026; commands we deliberately did not execute (login, cache clear, artifact download) are described from their captured help text and installed source.