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>]]

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.

setup#

Initialize cannon settings file

cannon setup

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

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

publish#

Publish a Cannon package to the registry

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
--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-provisionedIncludes provisioned packages when publishing to the registry
--skip-confirmSkip confirmation and package selection prompts

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

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

pin#

Upload cannon pacakge data to a remote registry by IPFS hash

cannon pin <ipfsHash>

ArgumentDescription
<ipfsHash>IPFS hash to write deployment data for

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

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

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

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

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

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

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