Tools

CLI

@cowlprotocol/cli puts the whole protocol in your terminal — an encrypted local wallet, the shielded pool, private sends, private trades, withdrawals, view keys, and a relayer you can run yourself. Same contracts as the web app, every flag exposed, scriptable end to end.

Mainnet · Live

Every shielded command below runs on Robinhood Chain mainnet and testnet. Proofs are generated on your machine with no toolchain to install, and spends go through the gasless relayer by default.

Install

npm install -g @cowlprotocol/cli

Requires Node.js 18+. The command is cowl. Bare cowl prints a status overview: network, addresses, contracts, and both balances.

Quick start

cowl init                    # wallet + view key + shielded keys + network
cowl network use robinhood-mainnet
cowl shield 0.1              # deposit into the shielded pool
cowl scan                    # sync the note tree
cowl balance --shielded      # the book only your keys can open
cowl receive                 # your shielded payment address

Everything lives in ~/.cowl/ (private, mode 0600). Keys are encrypted with a passphrase (scrypt + AES-256-GCM) and never leave your machine.

Wallet

cowl init                 # guided setup (new or import + passphrase + network)
cowl wallet new           # create a new wallet
cowl wallet import [0x…]  # import a private key or a seed phrase
cowl wallet address       # print your public address
cowl wallet export        # reveal your private key (asks to confirm)
cowl wallet passphrase    # change the keystore passphrase
cowl wallet backup        # write an encrypted backup
cowl wallet restore       # restore one
cowl wallet doctor        # check the keystore, permissions, and derivation

The shielded pool

Deposits, private sends, trades, and withdrawals settle against the Cowl pool on Robinhood Chain, mainnet and testnet both. Each one is a ZK proof generated locally. Amounts cross the boundary in shared denominations by default, and any spend can travel through a relayer so your wallet never pays the gas.

cowl shield <amount> [token]       # deposit — proves and settles on chain
cowl scan                          # replay the tree and open your notes
cowl balance --shielded            # shielded book (plain balance is the public side)
cowl receive                       # your zcowl1… payment address
cowl send <amount> ETH zcowl1…     # private, in-pool transfer
cowl unshield <amount> [token]     # withdraw
cowl consolidate [token]           # merge fragmented notes into spendable ones
cowl portfolio                     # shielded and public holdings, priced
cowl trade <amount> <token>        # private swap — say what you want to RECEIVE

Flags that matter

Flag	What it does
`--self`	Submit and pay gas yourself instead of going through the relayer. The default is gasless.
`--relay <url>`	Point at a specific relayer rather than the network one.
`--exact`	Cross the boundary at the precise amount instead of splitting into shared denominations.
`--spread <window>`	Scatter a multi-transaction boundary crossing across a time window (`45s`, `20m`, `3h`) so the parts do not land as one obvious burst.
`--max <amount>`	On a trade, cap what you are willing to spend. Defaults to the quoted price.
`--yes`	Skip the confirmation prompt. What automation needs, and nothing else should use.
`--json`	Machine-readable output on any command.

Stealth addresses

Public deposits can land on a fresh, unlinkable stealth address that only you can spend from. Spending and viewing keys derive from your wallet, so addresses are always recoverable.

cowl address          # generate a one-time stealth address
cowl address --meta   # show your shareable stealth meta-address

View keys

A view key is what you hand an auditor for read-only disclosure. The public half is shareable; the private half stays in ~/.cowl/.

cowl viewkey show   # print your public view key
cowl viewkey new    # generate a new view key

Relayer

Any install can serve as a relayer and earn the fee leg of every spend it submits.

cowl relay serve                                   # your wallet becomes a relayer
cowl relay quote https://relay.cowlprotocol.com    # what it charges per spend

Tokens and markets

cowl token list          # ERC-20s tracked in your portfolio
cowl token add 0x…       # track one
cowl token remove 0x…    # stop tracking it
cowl markets             # what is routable, and through which venue

Networks & config

Robinhood Chain is an Arbitrum-based L2. Mainnet is robinhood-mainnet, chain 4663; the public testnet is robinhood-testnet, chain 46630. Everything is overridable.

cowl network              # list networks (active is marked)
cowl network use <key>    # switch active network

cowl config show          # resolved network + contract addresses
cowl config set rpcUrl <url>
cowl config set explorer <url>
cowl config set shieldedAccount sig-v1   # open the web app's shielded book

Global flags --network <key>, --rpc <url>, and --json work on any command. Set COWL_HOME to keep more than one profile side by side.

One wallet, one book

The terminal keystore and the app derive different shielded accounts by construction. cowl config set shieldedAccount sig-v1points the CLI at the app’s derivation, so both surfaces read the same notes. Confirm cowl receivematches the app’s Receive tab before you move anything.

Command reference

Command	What it does	Status
`cowl init` · `wallet`	Set up or manage the local wallet, view key, and shielded keys	Live
`cowl balance` · `portfolio` · `token`	Public and shielded holdings, priced, with tracked ERC-20s	Live
`cowl address` · `receive`	Stealth address for public deposits, shielded address for private payments	Live
`cowl viewkey`	Selective-disclosure view keys	Live
`cowl shield` · `scan`	Deposit into the shielded pool, sync the local tree	Mainnet & testnet
`cowl send` → `zcowl1…` · `unshield`	Private send and withdrawal from your shielded balance	Mainnet & testnet
`cowl trade`	Private swap: spend, fill against public liquidity, re-shield, one transaction	Mainnet & testnet
`cowl consolidate`	Merge fragmented shielded notes	Mainnet & testnet
`cowl relay` · `--relay`	Run a relayer, or spend through one	Mainnet & testnet
`cowl send` → `0x…`	Public transfer, native or ERC-20	Live
`cowl fees` · `ping` · `status` · `network` · `config` · `markets`	Fee schedule, connectivity, resolved state, routing	Live
`cowl faucet`	Where to top up on the active network	Testnet

File locations

~/.cowl/
  keystore.json   # encrypted EVM key   (scrypt + AES-256-GCM, 0600)
  viewkey.json    # ed25519 view key    (0600)
  config.json     # network + overrides (0600)
  stealth.json    # stealth-address state    (0600)
  shielded/       # your opened notes and tree cache, per shielded account

Override the directory with COWL_HOME.

Non-custodial by design

Your keys never leave your device, and no service — not the relayer, not governance — can move your funds. Every security control the contracts and circuits go through is published with its findings on the audits page, and you can run all of them yourself.

Links

npm · GitHub