> For the complete documentation index, see [llms.txt](https://docs.bonsol.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bonsol.org/cli-commands.md). # CLI Commands ## General Usage Most Bonsol commands accept the following global arguments: * `-c`or `--config`: Path to the config file * `-k`or `--keypair`: Path to the keypair file * `-u`or `--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: ```bash 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: ```bash bonsol init --project-name [--dir ] ``` Options: * `-n`, `--project-name `: Name of your new project (required) * `-d`, `--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: ```bash build --zk-program-path ``` Options: * `-z`, `--zk-program-path `: Path to a ZK program folder containing a Cargo.toml (required) This command builds your ZK program and creates a `manifest.json`file in the program directory, containing all necessary information for deployment. Example `manifest.json`: ```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: ```bash bonsol deploy ``` 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): ```bash aws s3api create-bucket \ --bucket \ --region \ --create-bucket-configuration LocationConstraint= ``` Then deploy your ZK program to your S3 bucket: ```bash bonsol deploy s3 \ --bucket \ --access-key \ --secret-key \ --region \ --manifest-path \ --storage-account s3:// ```
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 ```warp-runnable-command bonsol deploy url --url --manifest-path [OPTIONS] ``` #### Required Arguments * `--url ` * The base URL endpoint for your binary * Example: `http://localhost:8080` * The actual binary will be stored at `/-` * `--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: ```warp-runnable-command bonsol deploy url \ --url http://localhost:8080 \ --manifest-path images/simple/manifest.json ``` 2. Deploy using an existing binary (verifies the binary first): ```warp-runnable-command 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: ```warp-runnable-command /- ``` For example: `http://localhost:8080/simple2-ec93e0a9592a2f00c177a7fce6ff191019740ff83f589e334153126c02f5772e` 2. Without `--no-post` (default): * POSTs your binary to this URL * Proceeds with Solana deployment after successful upload 3. 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": ```warp-runnable-command 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 2. "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: ```bash bonsol execute [OPTIONS] ``` Options: The execution request file should be a JSON file with the following structure: * `-f`, `--execution-request-file `: Path to execution request JSON file * `-p`,`--program-id `: Program ID * `-e`, `--execution-id `: Execution ID * `-x`, `--expiry `: Expiry for the execution * `-m`, `--tip `: Tip amount for execution * `-i`, `--input-file `: Override inputs in execution request file * `-w`, `--wait`: Wait for execution to be proven * `-t`, `--timeout `: Timeout in seconds The execution request file should be a JSON file with the following structure: ```json { "imageId": "20b9db715f989e3f57842787badafae101ce0b16202491bac1a3aebf573da0ba", "executionId": "9878798-987987-987987-987987", "tip": 100, "maxBlockHeight": 100, "inputs": [ { "inputType": "Public", "data": "" } ], "callbackConfig": { "programId": "your program id", "instructionPrefix": [0, 1, 2, 3], "extraAccounts": [ { "address": "", "role": "writable" } ] }, "executionConfig": { "verifyInputHash": true, "forwardOutput": true, "inputHash": "" } } ``` 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: ```bash bonsol prove --execution-id [OPTIONS] ``` Options: * `-m`, `--manifest-path `: Path to the manifest file * `-p`, `--program-id `: Program ID * `-i `: Input file * `-e`, `--execution-id `: Execution ID (required) * `-o `: Output location for the proof You can provide inputs in a JSON file: ```json { "imageId": "20b9db715f989e3f57842787badafae101ce0b16202491bac1a3aebf573da0ba", "inputs": [ { "inputType": "PrivateLocal", "data": "" } ] } ``` Or pipe inputs directly: ```bash echo '"{"attestation":"test"}" "nottest"' | bonsol prove -e -m images/simple/manifest.json ``` If proving succeeds, the CLI will save a serialized RISC-0 receipt file named `.bin` in the current directory or the specified output location. :bulb: Note: Only private local inputs are supported for the prove command.\\ --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.bonsol.org/cli-commands.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.