Nargo CLI reference

Nargo is the command-line interface for Noir. It handles project scaffolding, compilation, execution, testing, formatting, and integration with language tooling.

Installation

Install Nargo using noirup, the Noir version manager:

curl -L https://raw.githubusercontent.com/noir-lang/noirup/refs/heads/main/install | bash
noirup

Verify your installation:

nargo --version

Global flags

These flags are accepted by every subcommand.

Flag	Description
`--program-dir <PATH>`	Path to the Noir project directory. Defaults to `./`.
`--target-dir <PATH>`	Override the default `target` output directory.
`--package <NAME>`	Run the command on a specific named package in the workspace.
`--workspace`	Run the command on all packages in the workspace.
`--help`	Print help for the command.

Commands

nargo new

Create a new Noir project in a new directory.Syntax

nargo new <PATH> [OPTIONS]

Arguments

Argument	Description
`<PATH>`	The path where the new project will be created.

Options

Option	Description
`--name <NAME>`	Override the package name. Defaults to the directory name.
`--lib`	Use a library template instead of a binary.
`--bin`	Use a binary template (default).
`--contract`	Use a contract template.

Example

nargo new hello_world

This creates the following structure:

hello_world/
├── Nargo.toml
└── src/
    └── main.nr

The generated src/main.nr contains a minimal example:

fn main(x: Field, y: pub Field) {
    assert(x != y);
}

nargo init

Initialize a Noir project in the current directory. Equivalent to nargo new but targets the working directory.Syntax

nargo init [OPTIONS]

Options

Option	Description
`--name <NAME>`	Override the package name. Defaults to the current directory name.
`--lib`	Use a library template.
`--bin`	Use a binary template (default).
`--contract`	Use a contract template.

Example

mkdir my_project && cd my_project
nargo init

nargo init will not overwrite an existing Nargo.toml. If one already exists in the directory, the command will exit with an error.

nargo check

Type-check the program and generate Prover.toml and Verifier.toml input templates.Syntax

nargo check [OPTIONS]

Options

Option	Description
`--overwrite`	Force overwrite of existing `Prover.toml` and `Verifier.toml` files.

Example

nargo check

Running this inside a project generates a Prover.toml file with placeholder values for each of main’s inputs:

x = 0
y = 0

Fill in real values before executing:

x = "1"
y = "2"

nargo check only generates a Prover.toml for binary packages. Library and contract packages are skipped because they do not expose a single main entry point.

nargo compile

Compile the program to ACIR format and write the artifact to ./target/<package_name>.json.Syntax

nargo compile [OPTIONS]

OptionsAll standard compiler options are accepted (e.g. --deny-warnings, --silence-warnings).Example

nargo compile

The compiled JSON artifact is written to:

target/
└── hello_world.json

This artifact contains the ACIR circuit bytecode, the ABI, and debug information. It is the input consumed by nargo execute, nargo info, and the profiler.

nargo compile can be aliased as nargo build.

nargo execute

Compile (if needed) and execute the program, producing a witness file.Syntax

nargo execute [WITNESS_NAME] [OPTIONS]

Arguments

Argument	Description
`[WITNESS_NAME]`	Optional name for the output witness file. Defaults to the package name.

Options

Option	Description
`-p, --prover-name <NAME>`	Name of the TOML input file to use. Defaults to `Prover`.
`--overwrite-return`	Overwrite the `return` field in the prover file with the computed return value.
`--oracle-resolver <URL>`	JSON-RPC URL for resolving oracle calls.
`--oracle-file <PATH>`	Path to an oracle transcript file. Cannot be used with `--oracle-resolver`.

Example

nargo execute

Reads inputs from Prover.toml and writes the witness to:

target/
└── hello_world.gz

nargo execute my_witness

Writes the witness to target/my_witness.gz instead.

nargo execute automatically recompiles the program if sources have changed since the last compilation.

nargo prove

Generate a zero-knowledge proof for the program. Requires a proving backend such as Barretenberg.Syntax

nargo prove [OPTIONS]

Nargo does not bundle a proving backend. Proof generation is delegated to an external backend (e.g. bb from the Barretenberg package). See the quick start guide for backend setup instructions.

nargo verify

Verify a previously generated proof.Syntax

nargo verify [OPTIONS]

Like nargo prove, verification is delegated to the installed proving backend.

nargo test

Compile and run all functions annotated with #[test].Syntax

nargo test [TEST_NAMES...] [OPTIONS]

Arguments

Argument	Description
`[TEST_NAMES...]`	One or more substrings. Only tests whose names contain any of these strings will run.

Options

Option	Description
`--exact`	Only run tests whose names match the given pattern exactly.
`--list-tests`	Print all matching test names without running them.
`--no-run`	Compile tests without running them.
`--show-output`	Display output from `println` statements during tests.
`--test-threads <N>`	Number of threads to use for parallel test execution.
`-q, --quiet`	Display one character per test instead of one line.
`--format <FORMAT>`	Output format: `pretty` (default), `terse`, or `json`.
`--oracle-resolver <URL>`	JSON-RPC URL for resolving oracle calls.
`--no-fuzz`	Skip fuzz tests (tests with arguments).
`--only-fuzz`	Run only fuzz tests (tests with arguments).
`--corpus-dir <DIR>`	Load and store the fuzzer corpus from this directory.
`--minimized-corpus-dir <DIR>`	Perform corpus minimization and store results here.
`--fuzzing-failure-dir <DIR>`	Store failing fuzzer inputs here.
`--fuzz-timeout <SECONDS>`	Maximum time per fuzz test in seconds. Default: `1`.
`--fuzz-max-executions <N>`	Maximum executions per fuzz test. Default: `100000`.
`--fuzz-show-progress`	Print fuzzing progress to the console.

ExamplesRun all tests:

nargo test

Run tests whose names contain add:

nargo test add

Run only the test named test_add exactly:

nargo test test_add --exact

Example output

[hello_world] Testing 2 test(s)
[hello_world] test test_add ... ok
[hello_world] test test_overflow ... ok
[hello_world] 2 passed, 0 failed, 0 skipped

nargo fmt

Format all Noir source files in the workspace according to the standard style.Syntax

nargo fmt [OPTIONS]

Options

Option	Description
`--check`	Run in check mode: print a diff and exit with code 1 if any files would change. Does not modify files.

ExamplesFormat all files in the workspace:

nargo fmt

Check formatting without modifying files (useful in CI):

nargo fmt --check

nargo info

Display circuit size information: ACIR opcode count and function-level breakdown.Syntax

nargo info [OPTIONS]

Options

Option	Description
`-p, --prover-name <NAME>`	Name of the TOML input file. Defaults to `Prover`.
`--profile-execution`	Profile Brillig execution opcodes instead of ACIR opcodes. Forces unconstrained compilation mode.

Example

nargo info

Example output

+-------------+----------------------+--------------+----------------------+
| Package     | Function             | ACIR Opcodes | Brillig Opcodes      |
+-------------+----------------------+--------------+----------------------+
| hello_world | main                 | 1            | 0                    |
+-------------+----------------------+--------------+----------------------+

nargo debug

Launch the interactive REPL debugger for the program or a specific test function.Syntax

nargo debug [WITNESS_NAME] [OPTIONS]

Arguments

Argument	Description
`[WITNESS_NAME]`	Optional name for the output witness file if execution completes.

Options

Option	Description
`-p, --prover-name <NAME>`	Name of the TOML input file. Defaults to `Prover`.
`--package <NAME>`	The name of the package to debug.
`--test-name <NAME>`	Name or substring of a test function to debug instead of `main`.
`--acir-mode`	Force ACIR output, disabling debug instrumentation.
`--skip-instrumentation <BOOL>`	Disable variable debug instrumentation. Enabled automatically with `--acir-mode`.
`--oracle-resolver <URL>`	JSON-RPC URL for resolving oracle calls.

Example

nargo debug

nargo debug --test-name test_my_function

See the Debugger page for a full walkthrough of the REPL interface.

nargo lsp

Start the Noir Language Server, which provides IDE features to LSP-compatible editors.Syntax

nargo lsp

This command is normally launched automatically by editor extensions such as vscode-noir and should not need to be run manually.See the Language Server page for setup instructions.

nargo export

Compile and export all functions marked with the #[export] attribute from library packages.Syntax

nargo export [OPTIONS]

Exported artifacts are written to the export/ directory inside the workspace target directory. This command only processes library packages; binary packages are ignored.Example

nargo export

nargo fuzz

Run dedicated fuzzing harnesses — functions marked with #[test] that take arguments — as a standalone fuzzing session with more control than nargo test --only-fuzz.Syntax

nargo fuzz [FUZZING_HARNESS_NAME] [OPTIONS]

Arguments

Argument	Description
`[FUZZING_HARNESS_NAME]`	Optional name substring. Only harnesses whose names contain this string will run.

Options

Option	Description
`--exact`	Only run harnesses whose names match exactly.
`--list-all`	List all available harnesses without running them.
`--show-output`	Display `println` output during fuzzing.
`--num-threads <N>`	Number of threads to use. Default: `1`.
`--corpus-dir <DIR>`	Load and store the fuzzer corpus from this directory.
`--minimized-corpus-dir <DIR>`	Perform corpus minimization and store results here.
`--fuzzing-failure-dir <DIR>`	Store failing inputs here.
`--timeout <SECONDS>`	Maximum time per harness. Default: `0` (no limit).
`--max-executions <N>`	Maximum executions per harness. Default: `0` (no limit).
`--oracle-resolver <URL>`	JSON-RPC URL for resolving oracle calls.

Example

# List all fuzzing harnesses
nargo fuzz --list-all

# Run a specific harness with a 60-second timeout
nargo fuzz test_commutativity --timeout 60

nargo expand

Print the result of macro expansion for the current package. Useful when debugging comptime code or attribute-based macros.Syntax

nargo expand [OPTIONS]

The expanded source is printed to standard output. No compilation artifacts are written.Example

nargo expand

nargo doc

Generate HTML documentation for the current package from doc comments (///). Output is written to target/docs/.Syntax

nargo doc [OPTIONS]

Options

Option	Description
`--check`	Check for broken doc-comment links without producing output files. Exits with an error if broken links are found.

Example

# Generate documentation
nargo doc

# Check for broken links in doc comments
nargo doc --check

The generated HTML is written to <workspace_target>/docs/. Open index.html in a browser to view the documentation.

nargo doc is in active development. Its output format may change between releases.

nargo generate-completion-script

Generate a shell completion script for nargo.Syntax

nargo generate-completion-script <SHELL>

Arguments

Argument	Description
`<SHELL>`	One of: `bash`, `zsh`, `fish`, `powershell`, `elvish`.

Examples

nargo generate-completion-script zsh > ~/.zsh/completions/_nargo

nargo generate-completion-script bash > /usr/local/etc/bash_completion.d/nargo

nargo generate-completion-script fish > ~/.config/fish/completions/nargo.fish

Project structure

A standard Noir binary project created with nargo new has the following layout:

my_project/
├── Nargo.toml      # Package manifest: name, type, dependencies
├── Prover.toml     # Input values for the prover (generated by nargo check)
└── src/
    └── main.nr     # Entry point

The target/ directory is created on first compile and holds build artifacts:

target/
├── my_project.json     # Compiled ACIR artifact
└── my_project.gz       # Execution witness (after nargo execute)

Get Started

Language Guide

Standard Library

Tooling

Nargo CLI reference

Installation

Global flags

Commands

Project structure

​Installation

​Global flags

​Commands

​Project structure

Installation

Global flags

Commands

Project structure