docs(bb): add initial cli reference by marciw-aztec · Pull Request #17244 · AztecProtocol/aztec-packages

marciw-aztec · 2025-09-23T20:33:12Z

redo of #17215 on a clean branch

This PR adds documentation for the bb CLI, based on help output from v0.87.0.

Changes:

New file: bb-cli-reference.md
Covers bb commands and options, with examples
Adds consistent formatting and usage patterns
Includes significant edits to original help text, mostly for clarity and conciseness

Notes for reviewers:

includes Claude-generated context and examples that need technical review 🤖
includes an Installation section. not sure we want to keep it?

Addresses https://linear.app/aztec-labs/issue/ECODR-145/add-bb-cli-docs-to-barretenberg-docs (TODOs tracked there)

marciw-aztec · 2025-09-23T20:41:49Z

@critesjosh feel free to add reviewers 🙏

iAmMichaelConnor · 2025-09-24T08:03:38Z

barretenberg/docs/versioned_docs/version-v0.87.0/bb-cli-reference.md

+curl -L https://raw.githubusercontent.com/AztecProtocol/aztec-packages/master/barretenberg/bbup/install | bash
+bbup
+```
+


For more bbup commands, see: https://github.com/AztecProtocol/aztec-packages/tree/next/barretenberg/bbup

iAmMichaelConnor

Hi! I'm probably not the best person to review this, unfortunately. I've been away from barretenberg for ~3 years. I've hastily written lots of questions that jumped out to me as someone who doesn't understand the latest bb stuff. But I was short on time.
This would benefit from being reviewed by someone on Luke's team, as they wrote and maintain this code.

iAmMichaelConnor · 2025-09-24T08:06:21Z

barretenberg/docs/versioned_docs/version-v0.87.0/bb-cli-reference.md

+sidebar_position: 1000000
+---
+
+# Barretenberg CLI Reference


I was going to suggest perhaps this could live in a section within the barretenberg readme: https://github.com/AztecProtocol/aztec-packages/blob/master/barretenberg/README.md#usage <-- that's the master branch, and you can see an incomplete "usage" section.

But then I switched to the next branch (which is where development happens) and there is no "Usage" section anymore https://github.com/AztecProtocol/aztec-packages/blob/next/barretenberg/README.md. Not sure what the team's plan is.

Our team has not paid enough attention here; I'm willing to spend some time here. Thanks for the suggestions Mike

iAmMichaelConnor · 2025-09-24T08:09:26Z

barretenberg/docs/versioned_docs/version-v0.87.0/bb-cli-reference.md

+[Barretenberg](https://github.com/AztecProtocol/barretenberg) is Aztec's cryptography backend. This page covers `bb`, the command-line interface for Barretenberg.
+
+Usage: `bb [OPTIONS] [SUBCOMMAND]`
+


Suggested change

If you'd rather look directly at the code, you can jump here: https://github.com/AztecProtocol/aztec-packages/blob/next/barretenberg/cpp/src/barretenberg/bb/cli.cpp (Note: the `next` branch is for ongoing development, and might not exactly reflect released versions).

Not sure exactly where on this page this should go, but early on seems sensible. It's where I'd want to go if I got stuck.

iAmMichaelConnor · 2025-09-24T08:13:45Z

barretenberg/docs/versioned_docs/version-v0.87.0/bb-cli-reference.md

+
+#### Options
+
+- `-s, --scheme [BB_SCHEME]` -  The type of proof to be constructed. Specifies a proving system, an accumulation scheme, or a type of circuit to be constructed and proven for some implicit scheme. Options: `{client_ivc`, `avm`, `ultra_honk}`


Consider making these suboptions a consistent format to others in this list: i.e. an indented list of bullet points.

Any AVM mentions should reference an AVM stub document that explains that for now the AVM is not user-facing and used with our yarn packages, maybe

iAmMichaelConnor · 2025-09-24T08:14:05Z

barretenberg/docs/versioned_docs/version-v0.87.0/bb-cli-reference.md

+  - `bytes_and_fields` - Both `bytes` and `fields`.
+  - `fields_msgpack` - MessagePack buffer of `Fr` elements.
+- `--write_vk` - Writes the circuit's verification key.
+- `--zk` - Uses a zero-knowledge version of the specified `--scheme`, if available.


Does it throw if not available? Hopefully it does.

I'm not actually sure what 'if available' means here, but there's some combinations that don't make sense and likely should error out. the most problematic right now is --ipa_accumulation that single handedly makes other options ignored and is the bundle of rollup defaults. that one is awkward

iAmMichaelConnor · 2025-09-24T08:14:37Z

barretenberg/docs/versioned_docs/version-v0.87.0/bb-cli-reference.md

+  - `fields` - String representation of array of field elements.
+  - `bytes_and_fields` - Both `bytes` and `fields`.
+  - `fields_msgpack` - MessagePack buffer of `Fr` elements.
+- `--write_vk` - Writes the circuit's verification key.


Does it write it to a separate file? What name does it give the file?

its written to /vk. This is written as 32 byte field chunks, except if using the keccak oracle then it is optimized for solidity consumption

iAmMichaelConnor · 2025-09-24T08:21:05Z

barretenberg/docs/versioned_docs/version-v0.87.0/bb-cli-reference.md

+- `-c, --crs_path` - Path to  Common Reference String (CRS) directory. CRS files will be downloaded automatically as needed.
+- `--version` - Prints the version string.
+
+## Subcommands


What's the expected workflow? In what order would a dev typically run these commands? It seems like usage of Noir is implied. What kind of Noir commands do I need to run, in order to generate the files needed for some of the below commands?

I can either help figuring this out, or just handle this ask

iAmMichaelConnor · 2025-09-24T08:22:23Z

barretenberg/docs/versioned_docs/version-v0.87.0/bb-cli-reference.md

+- `-b, --bytecode_path` - Path to ACIR bytecode generated by Noir.
+- `-w, --witness_path` - Path to partial witness generated by Noir.


What kind of files are these? What are their file extensions? What's the default name of the file?

for posterity (possibly for myself if I do a pass):

bytecode can be a json with a 'bytecode' key (e.g. Noir ABI json), with serialized ACIR gzip-compressed then encoded in base64

or a gzip-compressed file of serialized ACIR

Witnesses can be

a gzip-compressed file of serialized witness data (output by Noir)

iAmMichaelConnor · 2025-09-24T08:23:19Z

barretenberg/docs/versioned_docs/version-v0.87.0/bb-cli-reference.md

+- `--ipa_accumulation` - Accumulates/aggregates Inner Product Argument (IPA) claims.
+- `--init_kzg_accumulator` - Initializes pairing point accumulator.
+- `--honk_recursion` - Informs the prover that this circuit will be recursively verified with UltraHonk (`1`) or with UltraRollupHonk (`2`). Ensures that a pairing point accumulator is added to the public inputs of the proof. (For UltraRollupHonk, an IPA claim is also added.)
+- `--recursive` - Enables recursive verification and KZG features.


I'm not sure what this means

Recursive and honk recursion shouldnt be a part of --help, I wonder how this got picked up? I nuked them, quite confused how they got into the source material or prompt or whatever

iAmMichaelConnor · 2025-09-24T08:24:54Z

barretenberg/docs/versioned_docs/version-v0.87.0/bb-cli-reference.md

+  - `starknet` - For Starknet smart contract verification (use with Garaga library).
+- `--zk` - Uses a zero-knowledge version of the specified `--scheme`, if available.
+- `--ipa_accumulation` - Accumulates/aggregates Inner Product Argument (IPA) claims.
+- `--init_kzg_accumulator` - Initializes pairing point accumulator.


Probably needs a more detailed explanation of what this means

This is probably best explained in use cases and show the prover and verifier commands for both use cases. the AVM and starknet use cases should explain that one is beyond scope, another is in experimental dev and not turned on by default

iAmMichaelConnor · 2025-09-24T08:25:15Z

barretenberg/docs/versioned_docs/version-v0.87.0/bb-cli-reference.md

+  - `keccak` - For Ethereum smart contract verification (uses EVM precompile).
+  - `starknet` - For Starknet smart contract verification (use with Garaga library).
+- `--zk` - Uses a zero-knowledge version of the specified `--scheme`, if available.
+- `--ipa_accumulation` - Accumulates/aggregates Inner Product Argument (IPA) claims.


Probably needs a more detailed explanation of what this means

marciw-aztec · 2025-09-24T12:19:23Z

Thanks for giving it a look, @iAmMichaelConnor. Will follow up separately -- I wasn't really thinking you'd do a substantive review but more wanted to use this to chat through edits/tone/etc. 🙂

But I appreciate your comments; will address them in a future iteration but they will no doubt make this all clearer!

ludamad · 2025-09-24T14:24:33Z

Hey guys, feel free to leave this with TODO notes for more context heavy stuff and I'm happy to work through it (the integration with the rest of the docs is the part I'd have a bit of trouble with, so thanks for doing that). If desired of course I can give all the context too. Thanks for your helpful notes @iAmMichaelConnor .

ludamad · 2025-09-25T17:09:09Z

I DM'd Marci - I will take on a second pass of this

BEGIN_COMMIT_OVERRIDE fix: secp256k1 ecdsa mul - fix handling of point at infinity (#16679) fix: secp256k1 ecdsa mul handling of stagger point additions (#16685) chore: biggroup audit of lookup and rom tables (#16895) fix(bb): oversight that disabled batch commits (#17278) docs(bb): add initial cli reference (#17244) chore!: cycle group #6 (#17174) fix: mac bb publish (#17276) END_COMMIT_OVERRIDE

Add bb cli reference

75682b9

marciw-aztec mentioned this pull request Sep 23, 2025

docs: Add bb cli reference #17215

Closed

marciw-aztec requested a review from critesjosh September 23, 2025 20:41

marciw-aztec marked this pull request as ready for review September 23, 2025 20:41

marciw-aztec requested a review from iAmMichaelConnor September 23, 2025 20:45

iAmMichaelConnor reviewed Sep 24, 2025

View reviewed changes

critesjosh requested a review from ludamad September 24, 2025 13:08

ludamad changed the base branch from next to merge-train/barretenberg September 25, 2025 17:07

ludamad changed the title ~~docs: Add bb cli reference, take 2~~ docs(bb): add initial cli reference Sep 25, 2025

ludamad merged commit ca03b42 into merge-train/barretenberg Sep 25, 2025
18 checks passed

ludamad deleted the mw/bb-cli-docs-clean branch September 25, 2025 17:08

AztecBot mentioned this pull request Sep 25, 2025

feat: merge-train/barretenberg #17293

Merged

mralj pushed a commit that referenced this pull request Oct 13, 2025

docs(bb): add initial cli reference (#17244)

b38fd26

ludamad pushed a commit that referenced this pull request Dec 16, 2025

docs(bb): add initial cli reference (#17244)

ec24bb7

		[Barretenberg](https://github.com/AztecProtocol/barretenberg) is Aztec's cryptography backend. This page covers `bb`, the command-line interface for Barretenberg.

		Usage: `bb [OPTIONS] [SUBCOMMAND]`


	If you'd rather look directly at the code, you can jump here: https://github.com/AztecProtocol/aztec-packages/blob/next/barretenberg/cpp/src/barretenberg/bb/cli.cpp (Note: the `next` branch is for ongoing development, and might not exactly reflect released versions).


		#### Options

		- `-s, --scheme [BB_SCHEME]` - The type of proof to be constructed. Specifies a proving system, an accumulation scheme, or a type of circuit to be constructed and proven for some implicit scheme. Options: `{client_ivc`, `avm`, `ultra_honk}`

		- `-b, --bytecode_path` - Path to ACIR bytecode generated by Noir.
		- `-w, --witness_path` - Path to partial witness generated by Noir.

Conversation

marciw-aztec commented Sep 23, 2025

Uh oh!

marciw-aztec commented Sep 23, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

iAmMichaelConnor left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ludamad Sep 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

marciw-aztec commented Sep 24, 2025

Uh oh!

ludamad commented Sep 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

ludamad commented Sep 25, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ludamad Sep 24, 2025 •

edited

Loading

ludamad commented Sep 24, 2025 •

edited

Loading