> ## 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.93";

export const AXIOM_CLI_VERSION = "v2.0.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 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:

<CodeBlock language="bash">
  {`cargo openvm build
    cargo axiom build --config-id <ID>`}
</CodeBlock>

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