CLI Usage Guide

Commands, flags, examples, and error handling for the Fireblocks CLI.

Command Pattern

Every Fireblocks API operation is available as a command organized under a namespace:

fireblocks <namespace> <action> [flags]

Namespaces correspond to Fireblocks API resource groups (e.g. vaults, transactions, assets, staking). Examples:

fireblocks vaults get-paged-vault-accounts
fireblocks transactions create-transaction --data '...' --no-confirm
fireblocks staking get-chains

Discover Commands

Full Command Index

fireblocks help-index

List Actions in a Namespace

fireblocks vaults --help

Show All Flags for a Command

fireblocks vaults get-vault-account --help

Preview a Request

Use --dry-run on any command to see the exact request that would be sent — without executing it:

fireblocks transactions create-transaction \
  --data '{"assetId":"BTC","amount":"0.001"}' \
  --dry-run

Output:

{
  "method": "POST",
  "url": "https://api.fireblocks.io/v1/transactions",
  "body": { "assetId": "BTC", "amount": "0.001" }
}

Flags

Path Parameters

OpenAPI path parameters (e.g. {vaultAccountId}) become required flags with kebab-case names:

# GET /v1/vault/accounts/{vaultAccountId}
fireblocks vaults get-vault-account --vault-account-id 0

Query Parameters

Query parameters become optional flags with the same kebab-case conversion:

# GET /v1/vault/accounts/paged?limit=50&namePrefix=hot
fireblocks vaults get-paged-vault-accounts --limit 50 --name-prefix hot

Request Body

Write operations (POST/PUT/PATCH/DELETE) accept a JSON request body via --data:

fireblocks transactions create-transaction \
  --data '{"assetId":"ETH","amount":"0.1","source":{"type":"VAULT_ACCOUNT","id":"0"},"destination":{"type":"VAULT_ACCOUNT","id":"1"}}' \
  --no-confirm

Global Flags

These flags are available on every command:

Flag	Env Var	Description
--api-key	FIREBLOCKS_API_KEY	Fireblocks API key
--secret-key	FIREBLOCKS_SECRET_KEY / FIREBLOCKS_SECRET_KEY_PATH	RSA private key — PEM content or file path
--base-url	FIREBLOCKS_BASE_URL	Override the API base URL
--profile		Use a named credential profile
--dry-run		Preview the request without executing it
--no-confirm		Skip write-operation confirmation prompts
--debug		Log request and response details to stderr
-o, --output		Output format: json (default) or yaml

Write Operations

POST, PUT, PATCH, and DELETE commands prompt for confirmation before executing:

About to execute POST /v1/transactions. Continue? (y/N)

Skip the prompt for scripting and automation — either pass --no-confirm or pipe stdin from a non-TTY source:

fireblocks transactions create-transaction --data '...' --no-confirm

Idempotency Keys

Endpoints that support idempotency accept --idempotency-key. Use this for safe retries on write operations to guarantee at-most-once execution:

fireblocks transactions create-transaction \
  --data '{"assetId":"ETH","amount":"1.0","source":{"type":"VAULT_ACCOUNT","id":"0"},"destination":{"type":"ONE_TIME_ADDRESS","oneTimeAddress":{"address":"0xABC"}}}' \
  --idempotency-key "$(uuidgen)" \
  --no-confirm

Output

• stdout — JSON response data only
• stderr — warnings, beta notices, errors, and debug logs

Debug Logging

Pass --debug to log request and response details to stderr:

fireblocks vaults get-vault-account --vault-account-id 0 --debug

[DEBUG] GET https://api.fireblocks.io/v1/vault/accounts/0
[DEBUG] Response: 200
[DEBUG] Request-ID: a1b2c3d4-...

Beta Commands

Some commands are marked as beta. They print a warning to stderr before executing:

Warning: This command is in beta and may change in future releases.

This is informational — the command still runs and produces output on stdout.

Exit Codes

Code	Meaning	Recovery
0	Success
1	Client error (400 / 409 / 422)	Check request body or parameters
2	Usage error (missing or invalid flag)	Check flag names and types
3	Auth error (401 / 403)	Verify credentials with fireblocks whoami
4	Not found (404)	Verify the resource ID exists
5	Rate limited (429)	Wait retry_after seconds from the error JSON, then retry
6	Server error (5xx)	Retry after a brief delay
7	Timeout (30s)	Retry; the timeout is not configurable

Error Format

Errors are written as JSON to stderr:

{
  "code": 5,
  "status": 429,
  "message": "Rate limit exceeded",
  "request_id": "a1b2c3d4-5678-...",
  "retry_after": 30
}

request_id and retry_after are included only when applicable.

Examples

# List vault accounts
fireblocks vaults get-paged-vault-accounts

# Get a specific vault
fireblocks vaults get-vault-account --vault-account-id 0

# Create a transaction
fireblocks transactions create-transaction \
  --data '{"assetId":"BTC","amount":"0.001","source":{"type":"VAULT_ACCOUNT","id":"0"},"destination":{"type":"VAULT_ACCOUNT","id":"1"}}' \
  --no-confirm

# Idempotent transaction with retry safety
fireblocks transactions create-transaction \
  --data '{"assetId":"ETH","amount":"1.0","source":{"type":"VAULT_ACCOUNT","id":"0"},"destination":{"type":"ONE_TIME_ADDRESS","oneTimeAddress":{"address":"0xABC"}}}' \
  --idempotency-key "$(uuidgen)" --no-confirm

# Preview a request without executing
fireblocks transactions create-transaction \
  --data '{"assetId":"BTC","amount":"0.001"}' \
  --dry-run

# Use the sandbox environment
fireblocks vaults get-paged-vault-accounts \
  --base-url https://sandbox-api.fireblocks.io

# Debug a failing request
fireblocks vaults get-vault-account --vault-account-id 0 --debug

# Pipe output to jq
fireblocks vaults get-paged-vault-accounts | jq '.accounts[].name'

Shell Autocomplete

The CLI supports tab completion for Bash and Zsh. Run the autocomplete command for your shell and follow the printed setup instructions:

# Bash
fireblocks autocomplete bash

# Zsh
fireblocks autocomplete zsh