> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axiom.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Axiom CLI

> Accessing the Axiom Proving API via CLI

export const CARGO_TOOLCHAIN = "1.90";

export const AXIOM_CLI_VERSION = "v1.1.0";

We provide a Cargo-based CLI paralleling the
[OpenVM CLI](https://docs.openvm.dev/book/writing-apps/overview) 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:

<CodeBlock language="bash">
  {`cargo +${CARGO_TOOLCHAIN} install --locked --git https://github.com/axiom-crypto/axiom-api-cli.git --tag ${AXIOM_CLI_VERSION} cargo-axiom`}
</CodeBlock>

You can verify the installation afterwards by listing available commands using:

```bash theme={null}
cargo axiom --help
```

To authenticate with the Axiom Proving API, run

```bash theme={null}
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:

```bash theme={null}
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).

Set the OpenVM Rust toolchain explicitly using `--openvm-rust-toolchain <VERSION>` to request a particular nightly release. Only nightly identifiers are accepted (for example `nightly-2025-02-14`). If you omit the flag, the builder defaults to `nightly-2025-02-14` (Rust 1.86 nightly).

### `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](https://docs.openvm.dev/book/writing-apps/overview#inputs) 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").

## Uploading Pre-built Programs

### `cargo axiom upload-exe --config-id <ID>`

Upload a locally built guest program (ELF and VMEXE pair) to the Axiom Proving API. This workflow is currently limited to approved organizations.

Run `cargo openvm build` before invoking this command so the guest workspace contains matching `target/openvm/release/<bin>.elf` and `.vmexe` artifacts. When multiple binaries exist, provide `--bin-name <BIN>` to specify which pair to upload. Optional flags such as `--project-id`, `--project-name`, `--program-name`, and `--default-num-gpus` mirror the options available during reproducible builds.

The CLI automatically reads the ELF and VMEXE files from the current directory, uploads both artifacts, and returns the program identifier along with a console link when available.