CLI Reference

This page lists every command of the interfold CLI in release 0.18.0. It also lists update and uninstall, which only releases after 0.19.0 have. It is for developers who build E3 programs and for operators who run ciphernodes. Each entry gives the purpose, the usage line, and a table of flags with their default values. The source of truth is the clap definitions in crates/cli/src.

Commands at a glance

Run interfold <command> --help to print the help text of one command. Run interfold --version to print the release version.

Global options

These options apply to every interfold command. You can put them before or after the command name.

The node profile also sets the storage paths. Each profile keeps its keys and data in folders named after the profile. See storage paths.

Behavior common to all commands

Configuration file

Most commands need a configuration file. The CLI looks for the file in the order that Node Configuration describes. When the CLI finds no file, only these commands run:

All other commands stop with this error:

Configuration file not found. Run `interfold ciphernode setup` to create a configuration.

init and ciphernode setup do the opposite. They stop with an error when the CLI finds a configuration file.

When the configuration sets autopassword: true or autowallet: true, every command that loads the file first creates a missing password or wallet key. update and uninstall do not. See node keys.

Commands that run inside a running node

interfold start opens a control port on 127.0.0.1 at ctrl_port (default 50505). Before a command runs, the CLI sends a request to that port and waits up to 1 second. When a node answers, these read-only commands run inside that node and print its answer:

• config get
• ciphernode status
• events query
• net get-peer-id
• noir status
• print-env
• rev (without --features)
• wallet get

All other commands run in the local process.

Exit status

A command that fails prints the error in red and exits with status 1.

Command output uses the e3-console channel and printer task. Normal completion waits for the printer to drain after its senders close; remote commands can collect those lines instead. This is not a crash-durable output log, and the channel is unbounded.

Install and update

Install script

The install script at the repository root installs interfold in ~/.local/bin. It supports Linux on x86_64 and macOS on Apple silicon. On other platforms, build the CLI from source.

curl -fsSL https://raw.githubusercontent.com/theinterfold/interfold/main/install | bash

The environment variables INTERFOLD_VERSION and INTERFOLD_INSTALL_DIR set the same values as --version and --dir. To pass the flag through the pipe, give it to bash -s --:

curl -fsSL https://raw.githubusercontent.com/theinterfold/interfold/main/install | bash -s -- --version v0.19.0

Release 0.19.0 and earlier do not have the update command. On these releases, use the install script to change the release. For a binary outside ~/.local/bin, give its folder with --dir.

update

Replaces this binary with another release from GitHub. Use an older tag to downgrade. When the installed version already matches the release, the command does nothing. upgrade is another name for this command.

interfold update [--version <TAG>]

The value dev selects the most recently published release, stable or pre-release.

The command replaces the file that runs, after it resolves symbolic links. It writes the new binary to a temporary file in the same folder and renames it, so a running node continues to use the old release until it restarts. When a node answers on the control port, the command prints a reminder to restart it. When the user cannot write to the folder, the command stops with Permission denied. Run it with sudo in that case.

uninstall

Removes this binary. It does not remove configuration files, keys, or node data.

interfold uninstall

Project commands

These commands make and run an E3 project from the template. For a walkthrough, see Quick Start.

interfold init

Makes a new Interfold project from a template. The command clones the template, pins its Interfold crates to the cloned commit, runs pnpm install, and makes the first Git commit. It needs git and pnpm.

interfold init [PATH] [--template <TEMPLATE>] [--skip-cleanup] [--skip-install]

The default template uses the tag of the installed CLI version.

interfold compile

Compiles the E3 program of the project. This command is the same as interfold program compile.

interfold compile [--dev <true|false>]

interfold program

Manages the E3 program of the project. Each subcommand runs in the current directory and builds or runs the program-runner binary of the project's runner/ crate.

The --dev flag selects the mode. When the flag is absent, the CLI uses program.dev from the configuration, which defaults to false.

Outside Dev Mode, program compile and program start need a program.openvm section with at least one worker. The CLI refuses the removed program.risc0 section. See program settings.

interfold print-env

Prints the contract addresses and the RPC URL of one configured chain as environment variables on one line. Use it to give the addresses to a client or a server.

interfold print-env --chain <CHAIN> [--vite]

When no chain has the given name, the command prints an empty line.

Node commands

These commands configure and run a ciphernode. For the full procedure, see Running a ciphernode.

interfold ciphernode setup

Makes a configuration file for one ciphernode and stores its password and wallet key. The command runs only when the CLI finds no configuration file.

interfold ciphernode setup [--network sepolia] [-r <RPC_URL>] [--config-dir <PATH>] [--password-stdin] [--private-key-stdin]

Without a stdin flag, the command uses a hidden prompt for that secret. It rejects secret values in command arguments. The password must not be blank. The wallet key must contain 32 bytes in hexadecimal. The RPC prompt proposes wss://ethereum-sepolia-rpc.publicnode.com. Without --config-dir, the last prompt asks for the configuration folder. The default is interfold in the operating system configuration folder, for example ~/.config/interfold on Linux. Without a terminal, the command cannot prompt: give --rpc-url, --config-dir, --password-stdin, and --private-key-stdin.

The command writes interfold.config.yaml with these values:

• node.network and node.address, which comes from the private key
• One chain named after the network, with chain_id and rpc_url
• A data_availability block that reads the Sepolia deployment's data from Avail Turing (https://turing-rpc.avail.so/rpc)
• The interfold, ciphernode_registry, bonding_registry, and slashing_manager contracts with their deploy blocks

The contract addresses are the Sepolia deployment that was built into the binary. To compare them with the current deployment, run interfold config check. The binary has no local deployment, so the command refuses a local network: for a local chain, start from the project template's interfold.config.yaml. See data availability.

interfold start

Starts the ciphernode in the foreground. The node syncs chain events, joins the P2P network, and serves on committees. With --bootstrap, it only syncs chain events and joins the network, so that other nodes can find each other through it. Stop it with SIGINT (Ctrl+C) or SIGTERM. The node then does a controlled shutdown.

interfold start [--peer <PEER>]... [--bootstrap]

The command holds a lock on the data folder of the profile, so a second process cannot use the same data. A data folder keeps the role, full or bootstrap, of the first node that used it, and the command does not start a node of the other role on it. It also opens the control port and, when dashboard_port is set, a dashboard at http://127.0.0.1:<dashboard_port>. The node stops with an error when its chain connection fails or when its event store fails.

interfold nodes

Runs a set of nodes on one host. The set is every profile under the nodes key. The _default profile is never part of the set. A supervisor process listens on 127.0.0.1:13415 and controls the node processes.

Each node starts as interfold start --name <id>. The supervisor adds a --peer flag for every other node in the set, in the form /ip4/127.0.0.1/udp/<quic_port>/quic-v1.

Before it deletes anything, nodes purge checks each node whose store, event log, or key file it would delete. It finds these nodes in the configuration, in .interfold/data, and in .interfold/config. It refuses in these cases:

• The node runs. The purge takes the lock that interfold start takes, and it opens the node's store. Nothing overrides this refusal.
• The node holds a key share for an E3 that it has not seen complete.
• The purge cannot check the node. For example, the store is missing at the configured path, or it holds no operator key.

The purge reports every refusal at once. --allow-active-e3s overrides the last two kinds of refusal together. The purge also refuses when .interfold, .interfold/data, or .interfold/config is a symbolic link.

Before the first deletion, the purge writes a purge-in-progress file into each node folder that it empties. When the purge stops part of the way, run it again. The second run finishes the folders that hold this file. If another file or a link has this name, the purge stops and deletes nothing.

interfold start writes the path of its store next to the key file, as <key file>.store-record. The record keeps the store of each start, one path per line. For a key file with a record, the purge locks and checks every recorded store, also when the node ran with another E3_DATA_DIR, data_dir, or working directory. A recorded store that is no longer there is a refusal that --allow-active-e3s overrides, unless an earlier purge of the same folders deleted it. To forget a store that is gone for good, or that belongs to the project that this one was copied from, delete its line from the record. A key file that no configured node uses is checked through its record.

The purge has limits:

• A key file without a record, as of a node that has not started with this release, is checked through the store at the configured path. A stale copy of a store there passes the check.
• It finds stores only directly inside each node folder in .interfold/data.

The detached supervisor does not receive the --otel flag. Set otel in the configuration file, or E3_OTEL, for the nodes that it runs.

interfold noir

Manages the Noir prover tools that the node uses to make zero-knowledge proofs: the Barretenberg binary (bb) and the compiled circuits. The required versions come from crates/zk/prover/versions.json. For release 0.18.0, they are bb 5.1.0 and circuits 0.18.0.

With a configuration file, the tools go to .interfold/noir next to that file. Without one, they go to ~/.interfold/noir. A custom bb from custom_bb or E3_CUSTOM_BB replaces the downloaded one.

Circuit downloads require an archive SHA-256 compiled in for the required version from crates/zk/prover/versions.json or the release build input. noir status reports the required version and this pin. The installer checks this digest before extraction. It then requires a nonempty checksums.json that covers every artifact file and verifies each entry. The archive must contain the full supported preset/committee matrix and the complete artifact inventory used by release validation. If validation fails, the installed circuits and version record stay unchanged. --circuits-archive applies the same checks to a local file: the archive must have the release pin of this binary's circuit version. To install another archive, such as a local build, add --allow-unpinned-archive; the internal manifest checks still apply. To install a subset from a local archive, add --circuits-configuration <PRESET/COMMITTEE> for each required pair. For example, --circuits-configuration insecure-64/minimum selects the development configuration. This option requires --circuits-archive and cannot reduce the network download requirements.

If circuit replacement or the version update fails, the installer attempts rollback and returns the original installation error. Each rollback failure logs the source and target paths. If the previous circuits cannot be restored, the installer keeps the staging directory and logs its path for recovery.

interfold events query

Reads events from the local event store of the node. The command prints one JSON object for each event. The last line is a JSON cursor that you can use for the next page.

interfold events query [--agg <AGG>] [--since <SINCE>] [--limit <LIMIT>]

interfold config get

Prints one resolved configuration value, or all values when you give no parameter.

interfold config get [PARAM]

An unknown parameter causes the error Unknown config parameter. The value of peers includes the bootstrap peer of the network profile when the config sets no peers.

Operator on-chain lifecycle

Most of these commands send transactions to the BondingRegistry contract of a configured chain. status only reads, and faucet calls a Faucet contract that the chain entry names. For the procedures, see Registration and Manage tickets.

Shared flags and values

The wallet that wallet set stored signs every transaction. The contract checks that this wallet can do the action. For example, registerOperatorFor accepts only the bond owner of the operator.

Amounts are decimal token units, for example 1000 or 0.5. You can use _ to group digits. The number of decimal places must not be more than the decimals of the token. When a command needs a token allowance, it sends an approve transaction first.

interfold ciphernode set-bond-owner

Authorizes the first bond owner of the operator. The configured wallet is the operator.

interfold ciphernode set-bond-owner --owner <ADDRESS> [--chain <CHAIN>]

interfold ciphernode propose-bond-owner

Proposes to move an operator position to a new bond owner.

interfold ciphernode propose-bond-owner --operator <ADDRESS> --new-owner <ADDRESS> [--chain <CHAIN>]

interfold ciphernode accept-bond-owner

Accepts a proposed bond owner transfer. The configured wallet must be the proposed owner.

interfold ciphernode accept-bond-owner --operator <ADDRESS> [--chain <CHAIN>]

interfold ciphernode bond

Manages the FOLD bond of an operator. The parent command accepts --operator and --chain.

interfold ciphernode bond [--operator <ADDRESS>] [--chain <CHAIN>] <bond|unbond|claim> [FLAGS]

interfold ciphernode tickets

Manages the tickets of an operator. The parent command accepts --operator and --chain.

interfold ciphernode tickets [--operator <ADDRESS>] [--chain <CHAIN>] <buy|burn> --amount <AMOUNT>

The number of available tickets is floor(collateral balance / ticket price). After the transaction, both subcommands print the new ticket count.

interfold ciphernode register

Registers the operator in the BondingRegistry and the CiphernodeRegistry. It calls registerOperatorFor, which only the bond owner can call. The FOLD bond must be at least the required bond before you register.

interfold ciphernode register [--operator <ADDRESS>] [--chain <CHAIN>]

interfold ciphernode deregister

Requests deregistration. The bond owner or the operator key can send it. It calls deregisterOperatorFor, which puts all collateral in the exit queue.

interfold ciphernode deregister [--operator <ADDRESS>] [--chain <CHAIN>]

interfold ciphernode activate

Sends refreshOperatorStatus for a registered operator, so that the contract recomputes its activation state from its registration, release acknowledgement, bans, bond and tickets against the current requirements. The command prints the Active flag after the transaction. The admission cooldown is not part of Active; it affects eligibility, which status shows separately. For an operator that is not registered, the command stops and points to register.

interfold ciphernode activate [--operator <ADDRESS>] [--chain <CHAIN>]

interfold ciphernode deactivate

Withdraws tickets, FOLD bond, or both, so that the operator becomes inactive. You must give at least one of the two amount flags.

interfold ciphernode deactivate [--tickets <AMOUNT>] [--bond <AMOUNT>] [--operator <ADDRESS>] [--chain <CHAIN>]

interfold ciphernode status

Prints the on-chain state of an operator. The command sends no transaction.

interfold ciphernode status [--operator <ADDRESS>] [--no-committees] [--chain <CHAIN>]

The output shows these values:

• The operator key, the bond owner, and a pending bond owner
• The Registered, Active, and Exit pending flags, and Eligible for new committees: eligibilityAt at the latest block time, which also applies the admission cooldown and the admission policy. An operator in the cooldown is Active but not yet eligible.
• The ticket balance and the number of available tickets
• The FOLD bond and the pending exits
• The requirements: minTickets, ticketPrice, and ciphernodeBond
• The committees that hold the collateral of the operator, each with its E3 ID, the membership (candidate, member, or expelled), and the E3 stage

A committee stays in the list until releaseCommittee(e3Id) releases it, also after its E3 is complete or failed. A candidate holds a provisional seat while the sortition of the E3 is open.

To find the committees, the command reads the unresolvedCommitteesOf and committeeObligationAt views of BondingRegistry: one block read, one call for the number, and one call for each committee. These calls read no event history. A registry deployed before these views, or one that holds committees requested before them, does not list every committee. The command then reads the CommitteeObligationUpdated events of BondingRegistry. The first run reads from the deploy_block of the contract. When the configuration has no deploy_block for bonding_registry, the read starts at block 0. The first run sends one eth_getLogs request for each 10,000 blocks (or the chain's rpc_log_range_blocks), or for each smaller range that the RPC endpoint accepts. Thus the first run can take some seconds, and longer on an endpoint with a small range limit.

The command saves the result in committee-scans/ in the node data directory, one file for each operator. A later run reads only the blocks after the saved block: usually one eth_getLogs request, and three block reads that detect a chain reorganization. After a reorganization of the saved block, the command reads the full history again. The read stops at the latest block minus the chain's ingestion_confirmations, so a new committee shows after that number of blocks.

If the read fails, the command shows Committees: unavailable with the error, and it shows all the other values.

interfold faucet

Testnet only Requests test tokens from the faucet contract of a chain. The Faucet contract of the repository (contracts/test/Faucet.sol) sends 1000 FOLD and 1000 fee tokens to the configured wallet. It sends each token only when the wallet holds less than 1000 of it.

interfold faucet [--chain <CHAIN>]

The chain must have a faucet entry in contracts. If the entry is missing, the command stops with the error No faucet contract configured for chain '<CHAIN>'. Sepolia publishes a faucet, so interfold faucet --chain sepolia sends 1000 FOLD and 1000 MockUSDC. Mainnet has no faucet. On Sepolia, one faucet call provides enough FOLD for the 100 FOLD operator bond. See Contracts & Addresses.

Keys and secrets

The node stores its password in a key file. It uses the password to encrypt the wallet key and the libp2p key in its data store. See node keys.

interfold password set

Sets the password when no password exists. When the key file already exists, the command stops with an error. Run interfold password delete first.

interfold password set [--password-stdin]

Without the flag, the hidden prompt asks for the password twice. The password must not be blank. The command rejects password values in command arguments.

interfold password delete

Deletes the key file. The command asks for confirmation and for the current password.

interfold password delete

interfold wallet set

Stores the wallet private key, encrypted with the password. The command also derives the libp2p keypair from the same private key and stores it. The wallet key gives the node its Ethereum address and its peer ID.

interfold wallet set [--private-key-stdin]

Without the flag, the command asks for the wallet key with a hidden prompt. The key must contain 32 bytes in hexadecimal. The command rejects wallet key values in command arguments.

interfold wallet get

Prints the Ethereum address of the stored wallet key.

interfold wallet get

Network commands

interfold net get-peer-id

Prints the libp2p peer ID of the node. The peer ID comes from the stored wallet key.

interfold net get-peer-id

To dial extra peers, use interfold start --peer. To set peers permanently, use the peers key. See network settings.

Maintenance commands

interfold node validate

Checks the stored state of one node without a start. The command checks these items:

• This binary can load the storage schema.
• The event log is intact.
• The snapshot cursor is consistent.
• No committee tickets are orphaned.

Without --repair, the command changes no files. It exits with an error when a check fails.

interfold node validate [--repair]

The command takes the same data-folder lock as interfold start. Stop the node before you run it. Use it before an upgrade and after a crash. See Upgrades.

interfold node reset-data

Deletes the durable protocol state of one node but keeps its identity. Use it when a release raises the storage schema and the binary refuses to load the old data folder.

interfold node reset-data --yes

The command first writes an encrypted backup of the wallet key and libp2p key to identity-backup-<name>-<timestamp>.json next to the database. Then it deletes the key/value store and the event log, writes the identity back, and reads it again to confirm. The command refuses to run while the node runs. It also refuses, and deletes nothing, while the node holds a key share for an E3 that it has not seen complete, including an E3 that shows Failed. See Reset node state. The command in v0.18.0 and earlier has no such check. Run the reset with the binary of the new release.

interfold config check

Compares the contract addresses in the configuration with the published deployment manifest. See Contracts & Addresses.

interfold config check [--chain <CHAIN>] [--manifest-url <MANIFEST_URL>]

The command compares a chain only when its name is a network in the manifest, mainnet or sepolia. It skips other chains. Each finding has one of these labels:

The command exits with status 1 when it finds a STALE value. A supervisor or a CI job can use it as a gate before a restart. It does not compare e3_program, because each application has its own E3 program.

interfold rev

Prints the Git revision that the binary was built from.

interfold rev [--features]

interfold purge-all

Deletes .interfold/data, .interfold/config, and .interfold/caches in the current directory. This command is nodes purge and program cache purge together, with the same checks as nodes purge.

interfold purge-all --yes [--allow-active-e3s]

Hidden and feature-gated items

Next steps