CLI Reference

The covenant CLI is the primary interface to the Covenant toolchain. All commands follow the pattern covenant <command> [options] [args].

What’s new in V0.9

V0.9 brings Foundry-class developer ergonomics. Seven commands round out the CLI:

Install: cargo install covenant-cli --version 0.9.0

Global flags

covenant new

Create a new project.

covenant new <name> [--template <template>]

covenant build

Compile source files to EVM bytecode.

covenant build [source.cov] [options]

covenant test

Run the test suite.

covenant test [--filter <pattern>] [--verbose]

Tests are defined in tests/*.cov or inline in source with #[test].

covenant lint

Run all static analysis detectors.

covenant lint [source.cov] [--fix] [--strict]

38+ detectors cover: reentrancy, integer overflow, unchecked external calls, missing guards, CEI violations, FHE reveal without guard, PQ signature misconfiguration, and more.

covenant deploy

Deploy a compiled artifact to a network.

covenant deploy <artifact> --network <network> [options]

covenant call

Call a view action (no transaction).

covenant call <address> <action> [args...] --network <network>

covenant send

Send a transaction to a contract.

covenant send <address> <action> [args...] --network <network> [--value <eth>]

covenant verify

Verify source on a block explorer.

covenant verify <address> --network <network> --source <file> --compiler-version <ver>

covenant upgrade-check

Check storage layout compatibility between two artifacts.

covenant upgrade-check <old.artifact> <new.artifact>

Exits 0 if safe, non-zero on collision with a human-readable diff.

covenant zk prove

Generate a ZK proof off-chain.

covenant zk prove --circuit <circuit-id> --private <key=val...> --public <key=val...>

covenant fmt V0.9

Canonical source formatter — opinionated, no configuration. Same role as gofmt / cargo fmt.

covenant fmt                # format all .cov files in src/
covenant fmt --check        # CI gate — non-zero exit if reformat needed
covenant fmt --diff         # show what would change without writing
covenant fmt path/to/file   # single file

Idempotent: running fmt twice on the same input produces identical output.

covenant doctor V0.9

Diagnose your environment. Runs 9 probes covering Rust toolchain, Cargo registry, Foundry availability, helper-bridge connectivity, RPC endpoints, and more.

covenant doctor          # human-readable summary
covenant doctor --json   # machine-readable
covenant doctor --strict # exit non-zero on any warning (CI use)

Each probe reports OK / WARN / FAIL with a remediation hint. Useful as a first step when something breaks unexpectedly.

covenant init V0.9

Scaffold a new project from a template. Replaces the older covenant new (which still works as an alias).

covenant init my-token                    # default: blank record contract
covenant init --template token my-token   # ERC-20 starter
covenant init --template ceremony my-cer  # amnesia ceremony starter
covenant init --template defi my-amm      # DeFi protocol scaffold

The scaffold creates covenant.toml, src/, tests/, a sample contract, and a CI workflow.

covenant explain V0.9

Show the long-form explanation of any diagnostic code (E0xxx for compiler errors, W0xxx for warnings, L00x for linter, C100+ for security findings).

covenant explain E0421
covenant explain L003
covenant explain C100

Output includes: what the diagnostic means, why it fires, common causes, and how to fix or suppress it.

covenant.toml reference

[project]
name    = "my-contract"
version = "0.1.0"

[compiler]
target  = "evm"         # default target
strict  = false
optimize = true

[networks.sepolia]
rpc_url    = "https://rpc.sepolia.org"
chain_id   = 11155111
explorer   = "https://sepolia.etherscan.io"

[networks.aster]
rpc_url    = "https://tapi.asterdex.com"
chain_id   = 1996
explorer   = "https://explorer.asterdex.com"

[deploy]
private_key_env = "DEPLOYER_PRIVATE_KEY"

Environment variables

Exit codes