CLI Commands

The Bonsol CLI is a command-line interface for creating, building, deploying, and interacting with verifiable programs on Solana.

General Usage

Most Bonsol commands accept the following global arguments:

  • -cor --config: Path to the config file

  • -kor --keypair: Path to the keypair file

  • -uor --rpc-url: URL for the Solana RPC

If these arguments aren't provided, Bonsol will use the default Solana config located in ~/.config/solana/. For example:

bonsol -k ./keypair.json -u http://localhost:8899 [COMMAND]

Commands

init: Creating a New Bonsol Program

Initialize a new Bonsol project with the following command:

bonsol init --project-name <PROJECT_NAME> [--dir <DIR>]

Options:

  • -n, --project-name <PROJECT_NAME>: Name of your new project (required)

  • -d, --dir <DIR>: Directory where the project will be created

This command creates a new Bonsol program structure in the specified directory.

build: Building a Bonsol ZK Program

Build your zero-knowledge program using:

build --zk-program-path <ZK_PROGRAM_PATH>

Options:

  • -z, --zk-program-path <ZK_PROGRAM_PATH>: Path to a ZK program folder containing a Cargo.toml (required)

This command builds your ZK program and creates a manifest.jsonfile in the program directory, containing all necessary information for deployment. Example manifest.json:

{
  "name": "simple",
  "binaryPath": "images/simple/target/riscv-guest/riscv32im-risc0-zkvm-elf/docker/simple/simple",
  "imageId": "20b9db715f989e3f57842787badafae101ce0b16202491bac1a3aebf573da0ba",
  "inputOrder": [
    "Public",
    "Private"
  ],
  "signature": "3mdQ6RUV5Bw9f1oUJhfif4GqVQpE8Udcu7ZR5NjDeyEx5ls2aRxD74DC5v1d251q6c9Q4m523a5a1h0nOO5f+s",
  "size": 266608
}

deploy: Deploying a Bonsol ZK Program

After building your ZK program, you can deploy it using various storage options:

bonsol deploy <COMMAND>

Commands:

  • s3: Deploy using an AWS S3 bucket

  • url: Deploy with a custom URL (e.g. localhost)

S3 Deployment

First, create an S3 bucket (skip this if you already have one):

aws s3api create-bucket \
    --bucket <BUCKET_NAME> \
    --region <REGION> \
    --create-bucket-configuration LocationConstraint=<REGION>

Then deploy your ZK program to your S3 bucket:

bonsol deploy s3 \
    --bucket <BUCKET_NAME> \
    --access-key <ACCESS_KEY> \
    --secret-key <SECRET_KEY> \
    --region <REGION> \
    --manifest-path <PATH_TO_MANIFEST> \
    --storage-account s3://<BUCKET_NAME>
URL

The bonsol deploy url command allows you to deploy your program by either uploading your binary to a URL endpoint or using an existing binary at a URL.

Usage

bonsol deploy url --url <URL> --manifest-path <MANIFEST_PATH> [OPTIONS]

Required Arguments

  • --url <URL>

  • The base URL endpoint for your binary

  • Example: http://localhost:8080

  • The actual binary will be stored at <URL>/<program-name>-<image-id>

  • --manifest-path <MANIFEST_PATH>

  • Path to your program's manifest file (manifest.json)

  • Example: images/simple/manifest.json

Optional Arguments

  • --no-post

  • By default, the command uploads your binary to the URL

  • With this flag, it instead verifies that the correct binary already exists at the URL

  • Useful when your binary is already hosted and you just want to deploy it to Solana

  • --auto-confirm or -y

  • Skip the confirmation prompt for Solana deployment

  • Use with caution as deployments cost real money

Examples

  1. Upload and deploy a new binary:

bonsol deploy url \
    --url http://localhost:8080 \
    --manifest-path images/simple/manifest.json

  1. Deploy using an existing binary (verifies the binary first):

bonsol deploy url \
    --url http://localhost:8080 \
    --manifest-path images/simple/manifest.json \
    --no-post

How It Works

  1. The command constructs the full URL by appending your program name and image ID:

   <base-url>/<program-name>-<image-id>

For example: http://localhost:8080/simple2-ec93e0a9592a2f00c177a7fce6ff191019740ff83f589e334153126c02f5772e

  1. Without --no-post (default):

  • POSTs your binary to this URL

  • Proceeds with Solana deployment after successful upload

  1. With --no-post:

  • Attempts to GET the binary from this URL

  • Verifies it matches your local binary

  • Only proceeds with Solana deployment if verification succeeds

Common Errors

  1. "Binary does not match":

   Error: The binary uploaded does not match the local binary at path '...'

  • This occurs when using --no-post and either:

    • No binary exists at the URL

    • The binary at the URL is different from your local binary

  1. "Failed to connect":

  • Check that your URL endpoint is accessible

  • Ensure you have the correct permissions

Notes

  • The command always requires a local binary for verification, even when using --no-post

  • Deployments to Solana are immutable and cost real money

  • The URL endpoint must support both POST and GET operations

execute: Requesting Execution

Request execution of your ZK program:

bonsol execute [OPTIONS]

Options:

The execution request file should be a JSON file with the following structure:

  • -f, --execution-request-file <EXECUTION_REQUEST_FILE>: Path to execution request JSON file

  • -p,--program-id <PROGRAM_ID>: Program ID

  • -e, --execution-id <EXECUTION_ID>: Execution ID

  • -x, --expiry <EXPIRY>: Expiry for the execution

  • -m, --tip <TIP>: Tip amount for execution

  • -i, --input-file <INPUT_FILE>: Override inputs in execution request file

  • -w, --wait: Wait for execution to be proven

  • -t, --timeout <TIMEOUT>: Timeout in seconds

The execution request file should be a JSON file with the following structure:

{
  "imageId": "20b9db715f989e3f57842787badafae101ce0b16202491bac1a3aebf573da0ba",
  "executionId": "9878798-987987-987987-987987",
  "tip": 100,
  "maxBlockHeight": 100,
  "inputs": [
    {
      "inputType": "Public",
      "data": "<base64 encoded data>"
    }
  ],
  "callbackConfig": {
    "programId": "your program id",
    "instructionPrefix": [0, 1, 2, 3],
    "extraAccounts": [
      {
        "address": "",
        "role": "writable"
      }
    ]
  },
  "executionConfig": {
    "verifyInputHash": true,
    "forwardOutput": true,
    "inputHash": "<hex encoded sha256 hash of the input data>"
  }
}

If you pass the --wait flag, the CLI will wait for execution completion and display the result:

Execution 9878798-987987-987987-987987 completed successfully

prove: Local Proving with the CLI

Perform local proving against a deployed program:

bonsol prove --execution-id <EXECUTION_ID> [OPTIONS]

Options:

  • -m, --manifest-path <MANIFEST_PATH>: Path to the manifest file

  • -p, --program-id <PROGRAM_ID>: Program ID

  • -i <INPUT_FILE>: Input file

  • -e, --execution-id <EXECUTION_ID>: Execution ID (required)

  • -o <OUTPUT_LOCATION>: Output location for the proof

You can provide inputs in a JSON file:

{
  "imageId": "20b9db715f989e3f57842787badafae101ce0b16202491bac1a3aebf573da0ba",
  "inputs": [
    {
      "inputType": "PrivateLocal",
      "data": "<base64 encoded data>"
    }
  ]
}

Or pipe inputs directly:

echo '"{"attestation":"test"}" "nottest"' | bonsol prove -e <execution_id> -m images/simple/manifest.json

If proving succeeds, the CLI will save a serialized RISC-0 receipt file named <execution_id>.bin in the current directory or the specified output location.

💡 Note: Only private local inputs are supported for the prove command.\

PreviousQuickstartNextSetup a local environment

Last updated