umbra-cli

Privacy-preserving token transfers on Solana, from your terminal.

Community-built CLI for the Umbra protocol. Not an official Umbra product.

Documentation

Install

npm install --global umbraprivacy-cli

Requires Bun >= 1.0 and a Solana keypair on disk. If you don't have one:

solana-keygen new

Quickstart

# 1. Add a signer user (links your keypair to the CLI)
umbra user add alice --backend local

# 2. Create your on-chain Umbra identity (one-time)
umbra register

# 3. Shield tokens into an encrypted balance
umbra eta deposit EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v 100000000

# 4. Check your encrypted balance
umbra eta balance EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

Amounts are in base units — for a 6-decimal token, 1000000 = 1 token.

Commands

| Command | Description | |---|---| | umbra user add <name> --backend <backend> | Add a signer user (local keypair or managed wallet) | | umbra user list | List configured users | | umbra user use <name> | Set the active user for all commands | | umbra user remove <name> | Remove a user and its stored credentials | | umbra config set <key> <value> | Set a CLI-wide config value | | umbra config get [key] | Print one or all config values | | umbra register | Publish your on-chain Umbra user account | | umbra eta deposit <mint> <amount> | Move tokens into your encrypted balance | | umbra eta balance <mint...> | Decrypt and display your encrypted balances | | umbra eta withdraw <mint> <amount> | Move tokens from your encrypted balance back to your wallet | | umbra eta convert [mint...] | Convert an MXE-encrypted balance to shared mode (required before withdrawing a balance received via the protocol) | | umbra utxo create <mint> <amount> | Create an anonymous stealth UTXO in the mixer | | umbra utxo scan | Scan the chain for UTXOs belonging to you | | umbra utxo claim | Scan and claim all found UTXOs | | umbra plugin add <name> | Install a plugin from npm | | umbra plugin list | List installed plugins | | umbra plugin remove <name> | Uninstall a plugin | | umbra plugin use <plugin> <name> | Set the active user for a specific plugin |

For full option details, see the docs.

Run any command with --help for a quick reference inline.

Plugins

The CLI supports plugins — npm packages that add new commands to umbra. Install any compatible plugin from npm:

umbra plugin add jup-earn
umbra plugin add @myorg/umbra-plugin-defi

Each plugin can be pinned to a different wallet without changing your global active user:

umbra plugin use jup-earn alice

For plugin authors: the CLI exposes its internals at the umbra-cli/lib entry point. Import helpers like resolvePluginUser, getPluginRpc, and config utilities directly rather than reimplementing them:

import { resolvePluginUser, getPluginRpc } from 'umbra-cli/lib';

const user = await resolvePluginUser('my-plugin');
const { rpc } = await getPluginRpc();

Docs

Docs are built with Mintlify and hosted at umbra.0xcreator.dev. Source files live in the docs/ folder as .mdx files.

To preview changes locally:

cd docs
npx mintlify dev

This starts a local dev server at http://localhost:3000. Navigation is configured in docs/docs.json.

Dev setup

bun install
bun run build   # tsc + chmod dist/cli.js
bun run dev     # tsc --watch
bun test tests/ # prettier + xo + bun test

Project structure

The CLI is built with Oclif for command routing and Ink (React for the terminal) for rendering. Each command file exports an Ink component (the UI) and an Oclif Command class (the routing and flag parsing). Commands are explicitly registered in source/commands.ts.

To add a new command:

1. Create a .tsx file in the appropriate source/commands/ subfolder with a default-exported Ink component and a named-exported Command class.
2. Register it in source/commands.ts with its command ID (e.g. 'eta:mycommand').

License

MIT