Cannon
Beta

Search packages, etc.

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#

Run a local Cannon package (Chain ID: 13370) on a local node for development and testing

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

ArgumentDescription
<packageRefs...>List of packages to load, optionally with custom settings for each one
OptionDescription
-n --provider-url [url]RPC endpoint to fork off of
--buildSpecify 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
--logsShow 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-interactiveDo not prompt for any user input. Useful for scripts and CI processes.
-vPrint logs for builder, equivalent to DEBUG=cannon:builder
-vvPrint logs for builder and its definition section, equivalent to DEBUG=cannon:builder, cannon:builder:definition
-vvvPrint logs for builder and its all sub sections, equivalent to DEBUG=cannon:builder*
-vvvvPrint all cannon logs, equivalent to DEBUG=cannon:*

build#

Build a package from a Cannonfile

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

ArgumentDescription
[cannonfile]Path to a cannonfile (default: "cannonfile.toml")
[settings...]Custom settings for building the cannonfile
OptionDescription
-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-runSimulate building on a local fork rather than deploying on the real network
--keep-aliveAfter 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
--wipeClear 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-compileSkip 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 --quietSuppress extra logging
-vPrint logs for builder, equivalent to DEBUG=cannon:builder
-vvPrint logs for builder and its definition section, equivalent to DEBUG=cannon:builder, cannon:builder:definition
-vvvPrint logs for builder and its all sub sections, equivalent to DEBUG=cannon:builder*
-vvvvPrint all cannon logs, equivalent to DEBUG=cannon:*

verify#

Verify a package on Etherscan

cannon verify [options] <packageRef>

ArgumentDescription
<packageRef>Name, version and preset of the Cannon package to verify (name:version@preset)
OptionDescription
-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
-vPrint logs for builder, equivalent to DEBUG=cannon:builder
-vvPrint logs for builder and its definition section, equivalent to DEBUG=cannon:builder, cannon:builder:definition
-vvvPrint logs for builder and its all sub sections, equivalent to DEBUG=cannon:builder*
-vvvvPrint all cannon logs, equivalent to DEBUG=cannon:*

publish#

Publish a Cannon package to the registry (Note that the registry collects some ETH, indicated in the CLI output, to support an IPFS cluster that automatically pins package data.)

cannon publish [options] <packageRef>

ArgumentDescription
<packageRef>Name, version and preset of the Cannon package to publish (name:version@preset)
OptionDescription
-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 --quietOnly output final JSON object at the end, no human readable output
--include-provisioned(DEPRECATED) Includes provisioned packages when publishing to the registry
--exclude-clonedExcludes cloned packages when publishing to the registry
--skip-confirmSkip confirmation and package selection prompts
-vPrint logs for builder, equivalent to DEBUG=cannon:builder
-vvPrint logs for builder and its definition section, equivalent to DEBUG=cannon:builder, cannon:builder:definition
-vvvPrint logs for builder and its all sub sections, equivalent to DEBUG=cannon:builder*
-vvvvPrint all cannon logs, equivalent to DEBUG=cannon:*

Advanced Commands

alter#

Change a cannon package outside of the regular build process.

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

ArgumentDescription
<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
OptionDescription
-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
-vPrint logs for builder, equivalent to DEBUG=cannon:builder
-vvPrint logs for builder and its definition section, equivalent to DEBUG=cannon:builder, cannon:builder:definition
-vvvPrint logs for builder and its all sub sections, equivalent to DEBUG=cannon:builder*
-vvvvPrint all cannon logs, equivalent to DEBUG=cannon:*

fetch#

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

cannon fetch [options] <packageRef> <ipfsHash>

ArgumentDescription
<packageRef>Name, version and preset of the Cannon package to fetch from (name:version@preset)
<ipfsHash>IPFS hash to fetch deployment data from
OptionDescription
-c --chain-id <chainId>Chain ID of deployment to fetch
--meta-hash <metaHash>IPFS hash to fetch deployment metadata from
-vPrint logs for builder, equivalent to DEBUG=cannon:builder
-vvPrint logs for builder and its definition section, equivalent to DEBUG=cannon:builder, cannon:builder:definition
-vvvPrint logs for builder and its all sub sections, equivalent to DEBUG=cannon:builder*
-vvvvPrint all cannon logs, equivalent to DEBUG=cannon:*

pin#

Upload cannon pacakge data to a remote registry by IPFS hash

cannon pin [options] <ipfsHash>

ArgumentDescription
<ipfsHash>IPFS hash to write deployment data for
OptionDescription
-vPrint logs for builder, equivalent to DEBUG=cannon:builder
-vvPrint logs for builder and its definition section, equivalent to DEBUG=cannon:builder, cannon:builder:definition
-vvvPrint logs for builder and its all sub sections, equivalent to DEBUG=cannon:builder*
-vvvvPrint all cannon logs, equivalent to DEBUG=cannon:*

unpublish#

Unpublish a Cannon package to the registry

cannon unpublish [options] <packageRef>

ArgumentDescription
<packageRef>Name, version and preset of the Cannon package to unpublish (name:version@preset)
OptionDescription
-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
-vPrint logs for builder, equivalent to DEBUG=cannon:builder
-vvPrint logs for builder and its definition section, equivalent to DEBUG=cannon:builder, cannon:builder:definition
-vvvPrint logs for builder and its all sub sections, equivalent to DEBUG=cannon:builder*
-vvvvPrint all cannon logs, equivalent to DEBUG=cannon:*

register#

Register a Cannon package on the Cannon Registry

cannon register [options] <packageRefs...>

ArgumentDescription
<packageRefs...>List of packages you want to register on the Cannon Registry
OptionDescription
-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
-vPrint logs for builder, equivalent to DEBUG=cannon:builder
-vvPrint logs for builder and its definition section, equivalent to DEBUG=cannon:builder, cannon:builder:definition
-vvvPrint logs for builder and its all sub sections, equivalent to DEBUG=cannon:builder*
-vvvvPrint all cannon logs, equivalent to DEBUG=cannon:*

publishers#

Add a new publisher to your Cannon package

cannon publishers [options] <packageRef>

ArgumentDescription
<packageRef>Name, version and preset of the Cannon package (name:version@preset)
OptionDescription
-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
-vPrint logs for builder, equivalent to DEBUG=cannon:builder
-vvPrint logs for builder and its definition section, equivalent to DEBUG=cannon:builder, cannon:builder:definition
-vvvPrint logs for builder and its all sub sections, equivalent to DEBUG=cannon:builder*
-vvvvPrint all cannon logs, equivalent to DEBUG=cannon:*

inspect#

Inspect the details of a Cannon package

cannon inspect [options] <packageRef>

ArgumentDescription
<packageRef>Name, version and preset of the Cannon package to inspect (name:version@preset)
OptionDescription
-c --chain-id <chainId>Chain ID of the variant to inspect (default: "13370")
-p --preset <preset>(DEPRECATED) Preset of the variant to inspect
-j --jsonOutput as JSON
-w --write-deployments <writeDeployments>Path to write the deployments data (address and ABIs), like "./deployments"
-q --quietSuppress extra logging
-s --sourcesShow contract sources
-vPrint logs for builder, equivalent to DEBUG=cannon:builder
-vvPrint logs for builder and its definition section, equivalent to DEBUG=cannon:builder, cannon:builder:definition
-vvvPrint logs for builder and its all sub sections, equivalent to DEBUG=cannon:builder*
-vvvvPrint all cannon logs, equivalent to DEBUG=cannon:*

prune#

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

cannon prune [options]

OptionDescription
--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-runPrint out information about prune without committing
-y --yesSkip confirmation prompt
-vPrint logs for builder, equivalent to DEBUG=cannon:builder
-vvPrint logs for builder and its definition section, equivalent to DEBUG=cannon:builder, cannon:builder:definition
-vvvPrint logs for builder and its all sub sections, equivalent to DEBUG=cannon:builder*
-vvvvPrint all cannon logs, equivalent to DEBUG=cannon:*

trace#

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

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

ArgumentDescription
<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
OptionDescription
-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 --jsonOutput as JSON
-vPrint logs for builder, equivalent to DEBUG=cannon:builder
-vvPrint logs for builder and its definition section, equivalent to DEBUG=cannon:builder, cannon:builder:definition
-vvvPrint logs for builder and its all sub sections, equivalent to DEBUG=cannon:builder*
-vvvvPrint all cannon logs, equivalent to DEBUG=cannon:*

decode#

decode transaction data using the ABIs of the given Cannon package

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

ArgumentDescription
<packageRef>Name, version and preset of the package to decode from (name:version@preset)
<bytes32Data...>bytes32 encoded transaction data to decode
OptionDescription
-c --chain-id <chainId>Chain ID of the variant to inspect (default: "13370")
-p --preset <preset>(DEPRECATED) Preset of the variant to inspect
-j --jsonOutput as JSON
-vPrint logs for builder, equivalent to DEBUG=cannon:builder
-vvPrint logs for builder and its definition section, equivalent to DEBUG=cannon:builder, cannon:builder:definition
-vvvPrint logs for builder and its all sub sections, equivalent to DEBUG=cannon:builder*
-vvvvPrint all cannon logs, equivalent to DEBUG=cannon:*

test#

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

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

ArgumentDescription
[cannonfile]Path to a cannonfile (default: "cannonfile.toml")
[forge options...]Additional options to send to forge
OptionDescription
-n --provider-url [url]RPC endpoint to fork off of
-c --chain-idChain ID to connect to and run fork tests with
-p --preset <preset>(DEPRECATED) The preset label for storing the build with the given settings
--wipeClear 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")
-vPrint logs for builder, equivalent to DEBUG=cannon:builder
-vvPrint logs for builder and its definition section, equivalent to DEBUG=cannon:builder, cannon:builder:definition
-vvvPrint logs for builder and its all sub sections, equivalent to DEBUG=cannon:builder*
-vvvvPrint all cannon logs, equivalent to DEBUG=cannon:*

interact#

Start an interactive terminal against a set of active cannon deployments

cannon interact [options] <packageRef>

ArgumentDescription
<packageRef>Name, version and preset of the Cannon package to interact with (name:version@preset)
OptionDescription
-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
-vPrint logs for builder, equivalent to DEBUG=cannon:builder
-vvPrint logs for builder and its definition section, equivalent to DEBUG=cannon:builder, cannon:builder:definition
-vvvPrint logs for builder and its all sub sections, equivalent to DEBUG=cannon:builder*
-vvvvPrint all cannon logs, equivalent to DEBUG=cannon:*

setup#

Initialize cannon settings file

cannon setup

clean#

Delete packages cache directories

cannon clean [options]

OptionDescription
--no-confirmDo 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>

ArgumentDescription
<name>npm package name of the Cannon plug-in

plugin remove#

Remove a Cannon plug-in

cannon plugin remove <name>

ArgumentDescription
<name>npm package name of the Cannon plug-in

Supported byOptimismandSafe