> For the complete documentation index, see [llms.txt](https://zerc20.gitbook.io/zerc20/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://zerc20.gitbook.io/zerc20/for-users/getting-started-1.md). # Using the CLI This guide walks you through installing and using the zERC20 command-line interface. ## Installation ```bash git clone https://github.com/zerc20io/zERC20.git cd zERC20/cli cargo install --path . ``` This installs the CLI binary as `zerc20-cli` (older versions may install as `cli`). Alternatively, run directly from the repository: ```bash cd zERC20/cli cargo run -r -- ... ``` ## Prerequisites ### Circuit Artifacts Circuit artifacts are required for generating withdrawal proofs. Download the official published artifacts before using the withdrawal CLI flows: ```bash cargo install --path ../circuit-setup zerc20-circuit-setup download --version ``` Proof of Innocence uses `proof_of_innocence_nova_pp.bin` and `proof_of_innocence_nova_vp.bin`. The currently published official artifact versions do not include those files yet, so Proof of Innocence requires locally generated artifacts until a POI-enabled version and manifest digest are published. See [Circuit Setup](/zerc20/for-developers/circuit-setup.md) for more details. ## Configuration ### Environment Variables Load environment variables from `.env` (see `.env.example` in the cli directory): ```bash # Token configuration export TOKENS_FILE_PATH=../config/tokens.json # Internet Computer endpoints (required) export IC_REPLICA_URL= export KEY_MANAGER_CANISTER_ID= export STORAGE_CANISTER_ID= # Required for receiving funds (path to downloaded circuit artifacts) export NOVA_ARTIFACTS_DIR=/path/to/nova_artifacts # Optional relay node URL (used for --relay / swap flows) export RELAY_URL=http://127.0.0.1:3000 ``` See [ICP Canister IDs](/zerc20/reference/addresses.md#icp-canister-ids) for mainnet/testnet values. ## Basic Commands ### Issue an Invoice Generate a burn address to receive payments: ```bash zerc20-cli invoice issue --chain-id ``` ### List Invoices View your invoices: ```bash zerc20-cli invoice ls --chain-id ``` ### Transfer Send zERC20 to a burn address: ```bash zerc20-cli transfer \ --chain-id \ --to \ --amount ``` ### Check Invoice Status ```bash zerc20-cli invoice status --chain-id --invoice-id ``` ### Receive Funds Generate proofs and receive: ```bash zerc20-cli invoice receive --chain-id --invoice-id ``` ### Gasless Receive via Relay Node Ask the relay node to submit the redeem transaction on your behalf: ```bash zerc20-cli invoice receive \ --chain-id \ --invoice-id \ --relay \ --relay-url $RELAY_URL ``` Useful flags: * `--max-relay-fee ` to abort if the quoted fee is too high * `--yes` to skip the confirmation prompt * `--local` to redeem from the latest proved local root instead of the global root ### Swap zERC20 into Native Gas Use the relay node to swap zERC20 into the chain's native gas token: ```bash zerc20-cli swap \ --chain-id \ --amount \ --relay-url $RELAY_URL ``` Useful flags: * `--slippage-bps ` sets the minimum accepted native output (`0..=9999`, default `100`) * `--recipient
` sends native tokens to a different address * `--yes` skips the confirmation prompt Notes: * The CLI prints `Swap submitted.` after the relay accepts the request and returns a transaction hash * If the quote reports `priceFallback`, the CLI warns because fallback or stale oracle prices may be less favorable ### Proof of Innocence Generate an off-chain proof that a set of received transfers did not originate from OFAC-sanctioned addresses: The directory in `NOVA_ARTIFACTS_DIR` must contain locally generated `proof_of_innocence_nova_pp.bin` and `proof_of_innocence_nova_vp.bin` files. The currently published official downloads are not enough for this command. ```bash zerc20-cli proof-of-innocence generate \ --nova-artifacts-dir $NOVA_ARTIFACTS_DIR \ --recipient \ --ofac-root \ --transfer-root \ --transfers-file ./transfers.json \ --exclusion-proofs-file ./exclusion_proofs.json \ --output ./innocence_proof.bin ``` Verify the proof and expected public values: ```bash zerc20-cli proof-of-innocence verify \ --nova-artifacts-dir $NOVA_ARTIFACTS_DIR \ --proof ./innocence_proof.bin \ --recipient \ --total-teleported \ --ofac-root \ --transfer-root ``` The witness files must include transfer Merkle paths and OFAC exclusion paths. See [Proof of Innocence](/zerc20/for-developers/proof-of-innocence.md) for the JSON format. ## Quick Start Example ```bash # 1. Issue an invoice zerc20-cli invoice issue --chain-id 1 # 2. List invoices to get the invoice ID and burn address zerc20-cli invoice ls --chain-id 1 # 3. Send funds to the burn address zerc20-cli transfer \ --chain-id 1 \ --to 0x1234567890abcdef1234567890abcdef12345678 \ --amount 1000000000000000000 # 4. Check status zerc20-cli invoice status --chain-id 1 --invoice-id inv-01 # 5. Receive zerc20-cli invoice receive --chain-id 1 --invoice-id inv-01 # 6. Or redeem through a relay node if you have no native gas zerc20-cli invoice receive --chain-id 1 --invoice-id inv-01 --relay --relay-url $RELAY_URL # 7. Optionally swap zERC20 into native gas zerc20-cli swap --chain-id 1 --amount 1000000 --relay-url $RELAY_URL ``` ## Important Notes * **Crosschain Capability**: Global-mode tokens can send on one chain and receive on another. Local-mode tokens such as zJPYC settle on the connected chain. * **Processing Time**: Private transfers typically take 30 minutes to 1 hour on mainnet * **Testnet Limitations**: On testnets, cross-chain transfers may take longer due to LayerZero instability. Local-mode zJPYC does not wait for LayerZero, but it can still be delayed by RPC or indexer issues. ## Next Steps * [FAQ](/zerc20/for-users/faq.md) — Common questions and troubleshooting * [CLI README](https://github.com/zerc20io/zERC20/tree/main/cli) — Full CLI documentation --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://zerc20.gitbook.io/zerc20/for-users/getting-started-1.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.