Skip to main content
We provide a Cargo-based CLI paralleling the OpenVM CLI to make it easier to work with the Axiom Proving API while developing and deploying a guest program.

​
Installation and Authentication

Build from source using the following command: You can verify the installation afterwards by listing available commands using:
To authenticate with the Axiom Proving API, run
The API key can be passed in directly or by setting the AXIOM_API_KEY environment variable in a .env file.
Note that cargo axiom register should be run in the directory containing the .env file. Throughout the CLI, --config-id is optional and defaults to the system default config id.

​
Shell Completions

The Axiom CLI supports autocompletion for all commands and options. To set up completions for your shell:
Supported shells: bash, zsh, fish, elvish, powershell The command will generate a completion file and provide installation instructions specific to your shell. After installation, restart your shell or source your shell’s configuration file, then test by typing cargo axiom and pressing TAB.

​
Initializing a Project

​
cargo axiom init <PROJECT_NAME>

This command initializes a new OpenVM project with the given name containing a starter Rust guest program.

​
Downloading VM Configs

​
cargo axiom config download-keys --config-id <ID> --type <TYPE>

This command allows users to download proving keys for different VM configurations. At present, only a single ID is supported, and the possible options for TYPE are:
  • app_pk: Application proving key.
  • agg_pk: Aggregation proving key.
  • halo2_pk: Proving key for halo2 verifier.
  • app_vk: Application verification key.
  • agg_vk: Aggregation verification key.
The response will be a download URL because proving key files are large.

​
Building Programs

​
cargo axiom build --config-id <ID>

This command registers a program to be proven on the Axiom Proving API by uploading a locally built ELF and VMEXE pair. Build the guest locally, then upload: The requirements are:
  • This command must be run in the guest program directory so we know which binary is the guest program.
  • Cargo.toml must be present.
  • cargo openvm build must have produced OpenVM v2 output in the default location. The transpiled VMEXE is written to openvm/release/<bin>.vmexe, a sibling of target/, and the raw ELF to target/<openvm-target>/release/<bin>. A custom CARGO_TARGET_DIR or a workspace-level target directory is not currently supported.
  • When the crate has multiple binaries, pass --bin <BIN> to select which pair to upload.
The command waits for processing to finish by default. Pass --detach to return as soon as the upload completes.

​
cargo axiom build status --program-id <ID>

This command allows users to check on the status of the program registered by cargo axiom build. Pass --wait to poll until the program is ready.

​
cargo axiom build download --program-id <ID> --artifact <TYPE>

This command allows users to download the program artifacts for the given program ID. The accepted values for TYPE are: exe, elf, source, app_exe_commit and all.

​
cargo axiom build list

List the programs that are accessible by the API key.

​
Generating Proofs

​
cargo axiom prove --program-id <ID> --type <TYPE> --input <INPUT>

This command allows users to request proofs of type TYPE for the registered program with ID with input INPUT. The possible options for TYPE are:
  • stark: The final STARK proof generated by OpenVM.
  • evm: The halo2 proof ready for EVM verification.
The INPUT field needs to either be a single hex string or a file path to a JSON file that contains the key input and an array of hex strings. If your hex string represents a single number, it should be written in little-endian format (as this is what OpenVM expects). In addition, if you need multiple input streams, only the file path option is supported. Each hex string (either in the JSON file or as direct input) is either:
  • A hex string of bytes prefixed with 0x01
  • A hex string of native field elements (represented as concatenated u32 in little endian encoding) prefixed with 0x02
See the OpenVM documentation for more details. Pass --deferred-proof <PATH> to supply a previously generated proof to a deferral job. Repeat the flag to supply more than one.

​
cargo axiom prove status --proof-id <ID>

This command allows users to check on the status of proof generation for proof ID.

​
cargo axiom prove logs --proof-id <ID>

This command allows users to download proof logs.

​
cargo axiom prove download --proof-id <ID> --type <TYPE> --output <FILE>

This command allows users to download proof artifacts from a proving job identified by ID. The command TYPE identifies the artifact type and FILE identifies the output directory. The possible options for TYPE are:
  • stark: The final STARK proof generated by OpenVM.
  • evm: The halo2 proof ready for EVM verification.

​
cargo axiom prove list --program-id <ID>

List the proofs that are run for the given program ID.

​
Executing Programs

​
cargo axiom run --program-id <ID> --input <INPUT>

This command allows users to execute a program with the given ID and input INPUT.

​
cargo axiom run status --execution-id <ID>

This command allows users to check the status of an execution request identified by ID.

​
Verifying Proofs

As a convenience, the CLI provides verification of OpenVM proofs (for both STARK and EVM).

​
cargo axiom verify evm --config-id <ID> --proof <FILE>

The VM configuration is identified by ID and the proof should be in FILE.

​
cargo axiom verify stark --program-id <ID> --proof <FILE>

The program is identified by ID and the proof should be in FILE.

​
cargo axiom verify status --verify-id <ID> --proof-type <TYPE>

This command allows users to check the status of a verification request identified by ID and a proof type TYPE (either “evm” or “stark”).