Cannon | CLI Docs

Beta

Explore Deploy Learn

Search packages, etc.

Overview Guides CLI Cannonfiles

Installation

Basic Commands

run build verify publish

Advanced Commands

alter fetch pin unpublish register publishers inspect prune trace decode test interact setup clean plugin list plugin add plugin remove

Command-Line Interface Documentation

Cannon’s command-line interface (CLI) allows users to deploy, upgrade, and configure protocols using cannonfiles with the build command, publish the resulting packages, run packages locally, and more. Find the code for the CLI on GitHub.

Installation

Install Foundry if you haven’t already. Then, run one of the following commands in your terminal to install (or upgrade) Cannon:

npm i -g @usecannon/cli

Now you can use all of the following commands your terminal with cannon <command>. You can also use the CLI without installing it using npx: npx @usecannon/cli <command>. If no command is specified, the CLI will execute the run command. The Hardhat plug-in exposes some of the commands as Hardhat tasks.

Basic Commands

`run`#

Utility for instantly loading cannon packages in standalone contexts

cannon run [global options] ...[<name>[:<semver>] ...[<key>=<value>]]

Argument	Description
`<packageRefs...>`	List of packages to load, optionally with custom settings for each one

Option	Description
`-n --provider-url [url]`	RPC endpoint to fork off of
`--build`	Specify to rebuild generated artifacts with latest, even if no changed settings have been defined.
`--upgrade-from [cannon-package:0.0.1]`	Specify a package to use as a new base for the deployment.
`--registry-priority <registry>`	Change the default registry to read from first. Default: onchain
`--preset <preset>`	Load an alternate setting preset
`--logs`	Show RPC logs instead of an interactive prompt
`--fund-addresses <fundAddresses...>`	Pass a list of addresses to receive a balance of 10,000 ETH
`--impersonate <address>`	Impersonate all calls from the given signer instead of a real wallet. Only works with --fork (default: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266")
`--mnemonic <phrase>`	Use the specified mnemonic to initialize a chain of signers while running
`--private-key [key]`	Specify a comma separated list of private keys which may be needed to sign a transaction
`--non-interactive`	Do not prompt for any user input. Useful for scripts and CI processes.

Cannon uses an Anvil node to execute this command. The following options can also be passed through to the Anvil process:

Option	Description
`-p --port <number>`	Port which the JSON-RPC server will be exposed. (default: "0")
`-c --chain-id <number>`	The chain id to run against
`--compute-units-per-second [number]`	Sets the number of assumed available compute units per second for this fork provider.
`--fork-url [url]`	Fetch state over a remote endpoint instead of starting from an empty state.
`--fork-block-number [number]`	Fetch state from a specific block number over a remote endpoint.
`--fork-chain-id [number]`	Specify chain id to skip fetching it from remote endpoint.
`--fork-retry-backoff [number]`	Initial retry backoff on encountering errors.
`--no-rate-limit`	Disables rate limiting for this node's provider.
`--no-storage-caching`	Explicitly disables the use of RPC caching. All storage slots are read entirely from the endpoint.
`--retries [number]`	Number of retry requests for spurious networks (timed out requests).
`--timeout [number]`	Timeout in ms for requests sent to remote JSON-RPC server in forking mode.
`--block-base-fee-per-gas [number]`	The base fee in a block.
`--code-size-limit [number]`	EIP-170: Contract code size limit in bytes. Useful to increase this because of tests.
`--disable-block-gas-limit`	Disable the call.gas_limit <= block.gas_limit constraint.
`--gas-limit [number]`	The block gas limit.
`--gas-price [number]`	The gas price.
`--accounts [number]`	Number of dev accounts to generate and configure.
`--balance [number]`	The balance of every dev account in Ether.
`--derivation-path [path]`	Sets the derivation path of the child key to be derived.
`--mnemonic [phrase]`	BIP39 mnemonic phrase used for generating accounts.
`--steps-tracing`	Enable steps tracing used for debug calls returning geth-style traces.
`--timestamp [number]`	The timestamp of the genesis block.
`--allow-origin [string]`	Set the Access-Control-Allow-Origin response header (CORS).
`--block-time [number]`	Block time in seconds for interval mining.
`--config-out [path]`	Writes output of anvil as json to user-specified file.
`--dump-state [path]`	Dump the state of chain on exit to the given file.
`--hardfork [type]`	The EVM hardfork to use.
`--host [string]`	The host the server will listen on.
`--init [path]`	Initialize the genesis block with the given genesis.json file.
`--ipc [path]`	Launch an ipc server at the given path or default path = /tmp/anvil.ipc.
`--load-state [path]`	Initialize the chain from a previously saved state snapshot.
`--no-cors`	Disable CORS.
`--no-mining`	Disable auto and interval mining, and mine on demand instead.
`--order [string]`	How transactions are sorted in the mempool.
`--prune-history [value]`	Don't keep full chain history. If a number argument is specified, at most this number of states is kept in memory.
`--state-interval [number]`	Interval in seconds at which the status is to be dumped to disk.
`--state [path]`	Alias for both loadState and dumpState. Initializes the chain with the state stored at the file, if it exists, and dumps the chain's state on exit.
`--transaction-block-keeper [number]`	Number of blocks with transactions to keep in memory.

`build`#

Build a package from a Cannonfile

cannon build [options] [cannonfile] [settings...]

Argument	Description
`[cannonfile]`	Path to a cannonfile (default: "cannonfile.toml")
`[settings...]`	Custom settings for building the cannonfile

Option	Description
`-n --provider-url [url]`	RPC endpoint to execute the deployment on
`-c --chain-id <number>`	The chain id to run against
`-p --preset <preset>`	(DEPRECATED) The preset label for storing the build with the given settings. Declare a preset in your cannonfile instead.
`--dry-run`	Simulate building on a local fork rather than deploying on the real network
`--keep-alive`	After completing build, leave RPC open and switch into run mode. Has no effect on live network deployment.
`--private-key [key]`	Specify a comma separated list of private keys which may be needed to sign a transaction
`--wipe`	Clear the existing deployment state and start this deploy from scratch.
`--upgrade-from [cannon-package:0.0.1]`	Specify a package to use as a new base for the deployment.
`--registry-priority <registry>`	Change the default registry to read from first. Default: onchain
`--gas-price <gasPrice>`	Specify a gas price to use for the deployment
`--max-gas-fee <maxGasFee>`	Specify max fee per gas (EIP-1559) for deployment
`--max-priority-gas-fee <maxpriorityGasFee>`	Specify max fee per gas (EIP-1559) for deployment
`--skip-compile`	Skip the compilation step and use the existing artifacts
`--write-script <writeScript>`	(Experimental) Path to write all the actions taken as a script that can be later executed
`--write-script-format <writeScriptFormat>`	(Experimental) Format in which to write the actions script (Options: json, ethers) (default: "ethers")
`-q --quiet`	Suppress extra logging

Cannon uses an Anvil node to execute this command. The following options can also be passed through to the Anvil process:

Option	Description
`-p --port <number>`	Port which the JSON-RPC server will be exposed. (default: "0")
`-c --chain-id <number>`	The chain id to run against
`--compute-units-per-second [number]`	Sets the number of assumed available compute units per second for this fork provider.
`--fork-url [url]`	Fetch state over a remote endpoint instead of starting from an empty state.
`--fork-block-number [number]`	Fetch state from a specific block number over a remote endpoint.
`--fork-chain-id [number]`	Specify chain id to skip fetching it from remote endpoint.
`--fork-retry-backoff [number]`	Initial retry backoff on encountering errors.
`--no-rate-limit`	Disables rate limiting for this node's provider.
`--no-storage-caching`	Explicitly disables the use of RPC caching. All storage slots are read entirely from the endpoint.
`--retries [number]`	Number of retry requests for spurious networks (timed out requests).
`--timeout [number]`	Timeout in ms for requests sent to remote JSON-RPC server in forking mode.
`--block-base-fee-per-gas [number]`	The base fee in a block.
`--code-size-limit [number]`	EIP-170: Contract code size limit in bytes. Useful to increase this because of tests.
`--disable-block-gas-limit`	Disable the call.gas_limit <= block.gas_limit constraint.
`--gas-limit [number]`	The block gas limit.
`--gas-price [number]`	The gas price.
`--accounts [number]`	Number of dev accounts to generate and configure.
`--balance [number]`	The balance of every dev account in Ether.
`--derivation-path [path]`	Sets the derivation path of the child key to be derived.
`--mnemonic [phrase]`	BIP39 mnemonic phrase used for generating accounts.
`--steps-tracing`	Enable steps tracing used for debug calls returning geth-style traces.
`--timestamp [number]`	The timestamp of the genesis block.
`--allow-origin [string]`	Set the Access-Control-Allow-Origin response header (CORS).
`--block-time [number]`	Block time in seconds for interval mining.
`--config-out [path]`	Writes output of anvil as json to user-specified file.
`--dump-state [path]`	Dump the state of chain on exit to the given file.
`--hardfork [type]`	The EVM hardfork to use.
`--host [string]`	The host the server will listen on.
`--init [path]`	Initialize the genesis block with the given genesis.json file.
`--ipc [path]`	Launch an ipc server at the given path or default path = /tmp/anvil.ipc.
`--load-state [path]`	Initialize the chain from a previously saved state snapshot.
`--no-cors`	Disable CORS.
`--no-mining`	Disable auto and interval mining, and mine on demand instead.
`--order [string]`	How transactions are sorted in the mempool.
`--prune-history [value]`	Don't keep full chain history. If a number argument is specified, at most this number of states is kept in memory.
`--state-interval [number]`	Interval in seconds at which the status is to be dumped to disk.
`--state [path]`	Alias for both loadState and dumpState. Initializes the chain with the state stored at the file, if it exists, and dumps the chain's state on exit.
`--transaction-block-keeper [number]`	Number of blocks with transactions to keep in memory.

`verify`#

Verify a package on Etherscan

cannon verify [options] <packageRef>

Argument	Description
`<packageRef>`	Name, version and preset of the Cannon package to verify (name:version@preset)

Option	Description
`-a --api-key <apiKey>`	Etherscan API key
`-c --chain-id <chainId>`	Chain ID of deployment to verify (default: "1")
`-p --preset <preset>`	(DEPRECATED) Preset of the deployment to verify

`publish`#

Publish a Cannon package to the registry

cannon publish [options] <packageRef>

Argument	Description
`<packageRef>`	Name, version and preset of the Cannon package to publish (name:version@preset)

Option	Description
`-n --registry-provider-url [url]`	RPC endpoint to publish to
`--registry-chain-id <number>`	Registry chain id to publish to
`--registry-address <address>`	Registry address to publish to
`--private-key <key>`	Private key to use for publishing the registry package
`--chain-id <number>`	The chain ID of the package to publish
`--preset <preset>`	The preset of the packages to publish
`-t --tags <tags>`	Comma separated list of labels for your package
`--gas-limit <gasLimit>`	The maximum units of gas spent for the registration transaction
`--value <value>`	Value in wei to send with the transaction
`--max-fee-per-gas <maxFeePerGas>`	The maximum value (in gwei) for the base fee when submitting the registry transaction
`--max-priority-fee-per-gas <maxPriorityFeePerGas>`	The maximum value (in gwei) for the miner tip when submitting the registry transaction
`-q --quiet`	Only output final JSON object at the end, no human readable output
`--include-provisioned`	(DEPRECATED) Includes provisioned packages when publishing to the registry
`--exclude-cloned`	Excludes cloned packages when publishing to the registry
`--skip-confirm`	Skip confirmation and package selection prompts

Advanced Commands

`alter`#

Change a cannon package outside of the regular build process.

cannon alter [options] <packageRef> <command> [options...]

Argument	Description
`<packageRef>`	Name, version and preset of the Cannon package to alter (name:version@preset)
`<command>`	Alteration command to execute. Current options: set-url, set-contract-address, mark-complete, mark-incomplete
`[options...]`	Additional options for your alteration command

Option	Description
`-c --chain-id <chainId>`	Chain ID of deployment to alter
`-n --provider-url [url]`	RPC endpoint to alter to
`-p --preset <preset>`	(DEPRECATED) Preset of the deployment to alter

`fetch`#

Fetch cannon package data from an IPFS hash and store it in the local registry.

cannon fetch [options] <packageRef> <ipfsHash>

Argument	Description
`<packageRef>`	Name, version and preset of the Cannon package to fetch from (name:version@preset)
`<ipfsHash>`	IPFS hash to fetch deployment data from

Option	Description
`-c --chain-id <chainId>`	Chain ID of deployment to fetch
`--meta-hash <metaHash>`	IPFS hash to fetch deployment metadata from

`pin`#

Upload cannon pacakge data to a remote registry by IPFS hash

cannon pin <ipfsHash>

Argument	Description
`<ipfsHash>`	IPFS hash to write deployment data for

`unpublish`#

Unpublish a Cannon package to the registry

cannon unpublish [options] <packageRef>

Argument	Description
`<packageRef>`	Name, version and preset of the Cannon package to unpublish (name:version@preset)

Option	Description
`-n --registry-provider-url [url]`	RPC endpoint to unpublish to
`--registry-chain-id <number>`	Registry chain id to unpublish to
`--registry-address <address>`	Registry address to unpublish to
`--private-key <key>`	Private key of the package owner
`--chain-id <number>`	The chain ID of the package to unpublish
`-t --tags <tags>`	Comma separated list of labels for your package
`--gas-limit <gasLimit>`	The maximum units of gas spent for the registration transaction
`--value <value>`	Value in wei to send with the transaction
`--max-fee-per-gas <maxFeePerGas>`	The maximum value (in gwei) for the base fee when submitting the registry transaction
`--max-priority-fee-per-gas <maxPriorityFeePerGas>`	The maximum value (in gwei) for the miner tip when submitting the registry transaction

`register`#

cannon register [options] <packageRef>

Argument	Description
`<packageRef>`	Name, version and preset of the Cannon package to publish (name:version@preset)

Option	Description
`-n --registry-provider-url [url]`	RPC endpoint to register your package to
`-c --registry-chain-id <chainId>`	Chain ID of the package to register
`--private-key <key>`	Private key to use for publishing the registry package
`--gas-limit <gasLimit>`	The maximum units of gas spent for the registration transaction
`--value <value>`	Value in wei to send with the transaction (defaults to registerFee)
`--max-fee-per-gas <maxFeePerGas>`	The maximum value (in gwei) for the base fee when submitting the registry transaction
`--max-priority-fee-per-gas <maxPriorityFeePerGas>`	The maximum value (in gwei) for the miner tip when submitting the registry transaction

`publishers`#

Add a new publisher to your Cannon package

cannon publishers [options] <packageRef>

Argument	Description
`<packageRef>`	Name, version and preset of the Cannon package (name:version@preset)

Option	Description
`-a --add <address>`	Specify a comma separated list of addresses to add as publishers
`-r --remove <address>`	Specify a comma separated list of addresses to add as publishers
`-n --registry-provider-url [url]`	RPC endpoint to add a publisher to your package
`-c --registry-chain-id <chainId>`	Chain ID of the package to add a publisher to
`--private-key <key>`	Private key of the package owner
`--gas-limit <gasLimit>`	The maximum units of gas spent for the registration transaction
`--value <value>`	Value in wei to send with the transaction (defaults to registerFee)
`--max-fee-per-gas <maxFeePerGas>`	The maximum value (in gwei) for the base fee when submitting the registry transaction
`--max-priority-fee-per-gas <maxPriorityFeePerGas>`	The maximum value (in gwei) for the miner tip when submitting the registry transaction

`inspect`#

Inspect the details of a Cannon package

cannon inspect [options] <packageRef>

Argument	Description
`<packageRef>`	Name, version and preset of the Cannon package to inspect (name:version@preset)

Option	Description
`-c --chain-id <chainId>`	Chain ID of the variant to inspect (default: "13370")
`-p --preset <preset>`	(DEPRECATED) Preset of the variant to inspect
`-j --json`	Output as JSON
`-w --write-deployments <writeDeployments>`	Path to write the deployments data (address and ABIs), like "./deployments"
`-q --quiet`	Suppress extra logging
`-s --sources`	Show contract sources

`prune`#

Clean cannon storage of excessive/transient build files older than a certain age

cannon prune [options]

Option	Description
`--filter-package <packageRef>`	Only keep deployments in local storage which match the given package name. Default: do not filter
`--filter-variant <variant>`	Only keep deployments which match the specifiec variant(s). Default: do not filter
`--keep-age <seconds>`	Number of seconds old a package must be before it should be deleted (default: "2592000")
`--dry-run`	Print out information about prune without committing
`-y --yes`	Skip confirmation prompt

`trace`#

Get a full stack trace for a transaction hash or explicit transaction call

cannon trace [options] <packageRef> <transactionHash OR bytes32Data>

Argument	Description
`<packageRef>`	Name, version and preset of the package to trace (name:version@preset)
`<transactionHash OR bytes32Data>`	base 16 encoded transaction data to input to a function call, or transaction hash

Option	Description
`-c --chain-id <chainId>`	Chain ID of the variant to trace
`-f --from <source>`	Caller for the transaction to trace
`-t --to <target>`	Contract which should be called
`-v --value <value>`	Amonut of gas token to send in the traced call
`-b --block-number <value>`	The block to simulate when the call is on
`-p --preset <preset>`	(DEPRECATED) Preset of the variant to trace
`-n --provider-url [url]`	RPC endpoint to fork off of
`-j --json`	Output as JSON

`decode`#

decode transaction data using the ABIs of the given Cannon package

cannon decode [options] <packageRef> <bytes32Data...>

Argument	Description
`<packageRef>`	Name, version and preset of the package to decode from (name:version@preset)
`<bytes32Data...>`	bytes32 encoded transaction data to decode

Option	Description
`-c --chain-id <chainId>`	Chain ID of the variant to inspect (default: "13370")
`-p --preset <preset>`	(DEPRECATED) Preset of the variant to inspect
`-j --json`	Output as JSON

`test`#

Run forge tests on a cannon deployment. To pass arguments through to `forge test`, use `--`.

cannon test [cannonfile] [-- forge options...]

Argument	Description
`[cannonfile]`	Path to a cannonfile (default: "cannonfile.toml")
`[forge options...]`	Additional options to send to forge

Option	Description
`-n --provider-url [url]`	RPC endpoint to fork off of
`-c --chain-id`	Chain ID to connect to and run fork tests with
`-p --preset <preset>`	(DEPRECATED) The preset label for storing the build with the given settings
`--wipe`	Clear the existing deployment state and start this deploy from scratch.
`--upgrade-from [cannon-package:0.0.1]`	Specify a package to use as a new base for the deployment.
`--registry-priority <registry>`	Change the default registry to read from first. Default: onchain
`--forge-cmd <command>`	Use an alternative forge call, such as "coverage" (default: "test")

`interact`#

Start an interactive terminal against a set of active cannon deployments

cannon interact [options] <packageRef>

Argument	Description
`<packageRef>`	Name, version and preset of the Cannon package to interact with (name:version@preset)

Option	Description
`-c --chain-id <chainId>`	Chain ID of deployment to interact with
`-n --provider-url [url]`	RPC endpoint to execute the deployment on
`-p --preset <preset>`	(DEPRECATED) Load an alternate setting preset
`--mnemonic <phrase>`	Use the specified mnemonic to initialize a chain of signers while running
`--private-key [key]`	Specify a comma separated list of private keys which may be needed to sign a transaction
`--gas-price <gasPrice>`	Specify a gas price to use for the deployment
`--max-gas-fee <maxGasFee>`	Specify max fee per gas (EIP-1559) for deployment
`--max-priority-gas-fee <maxpriorityGasFee>`	Specify max fee per gas (EIP-1559) for deployment

`setup`#

Initialize cannon settings file

cannon setup

`clean`#

Delete packages cache directories

cannon clean [options]

Option	Description
`--no-confirm`	Do not ask for confirmation before deleting

`plugin list`#

List all installed Cannon plug-ins

cannon plugin list

`plugin add`#

Add a Cannon plug-in

cannon plugin add <name>

Argument	Description
`<name>`	npm package name of the Cannon plug-in

`plugin remove`#

Remove a Cannon plug-in

cannon plugin remove <name>

Argument	Description
`<name>`	npm package name of the Cannon plug-in

Cannon on GitHub

Star

Supported byand

Installation

Basic Commands

Advanced Commands

Command-Line Interface Documentation

Installation

Basic Commands

run#

Anvil Options

build#

Anvil Options

verify#

publish#

Advanced Commands

alter#

fetch#

pin#

unpublish#

register#

publishers#

inspect#

prune#

trace#

decode#

test#

interact#

setup#

clean#

plugin list#

plugin add#

plugin remove#

`run`#

`build`#

`verify`#

`publish`#

`alter`#

`fetch`#

`pin`#

`unpublish`#

`register`#

`publishers`#

`inspect`#

`prune`#

`trace`#

`decode`#

`test`#

`interact`#

`setup`#

`clean`#

`plugin list`#

`plugin add`#

`plugin remove`#