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: 
cargo +1.86 install --locked --git https://github.com/axiom-crypto/axiom-api-cli.git --tag v1.0.0 cargo-axiom
You can verify the installation afterwards by listing available commands using: 
cargo axiom --help
To authenticate with the Axiom Proving API, run 
cargo axiom register --api-key <API_KEY>
The API key can be passed in directly or by setting the AXIOM_API_KEY environment variable in a .env file. 
AXIOM_API_KEY=<API_KEY>
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: 
cargo axiom completions <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 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.
  • halo2_vk: Verification key for halo2 verifier.
The response will be a download URL because proving key files are large.

​
Building Programs

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

This command allows users to register programs to be proven on the Axiom Proving API. The requirements on the directory structure are:
  • It must be a git repository, and the required local files must be tracked by git
  • Both Cargo.toml and Cargo.lock must be present and tracked by git
  • The src/main.rs file (or any other main entry point) must be tracked by git
  • This command must be run in the guest program directory so we know which binary is the guest program.
  • There can only be one binary target under the guest program directory.
This command will first pre-fetch all dependencies and then upload dependencies and files tracked by git to the Axiom Proving API. If your program needs some additional files that are not tracked by git, you can specify the --include_dirs flag to include them. Note that the value of --include_dirs should be relative to the git repository root (despite the fact that the command is run in the guest program directory).

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

This command allows users to check on the status of the reproducible OpenVM build triggered by cargo axiom build.

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

Download the log files of the build process.

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

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

​
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.

​
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”).