> ## Documentation Index
> Fetch the complete documentation index at: https://developers.fireblocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://developers.fireblocks.com/feedback

```json
{
  "path": "/docs/cli-usage",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# 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:

```bash theme={"system"}
fireblocks vaults get-paged-vault-accounts
fireblocks transactions create-transaction --data '...' --no-confirm
fireblocks staking get-chains
```

## Discover Commands

### Full Command Index

```bash theme={"system"}
fireblocks help-index
```

### List Actions in a Namespace

```bash theme={"system"}
fireblocks vaults --help
```

### Show All Flags for a Command

```bash theme={"system"}
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:

```bash theme={"system"}
fireblocks transactions create-transaction \
  --data '{"assetId":"BTC","amount":"0.001"}' \
  --dry-run
```

Output:

```json theme={"system"}
{
  "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:

```bash theme={"system"}
# 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:

```bash theme={"system"}
# 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`:

```bash theme={"system"}
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:

```bash theme={"system"}
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:

```bash theme={"system"}
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:

```bash theme={"system"}
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**:

```json theme={"system"}
{
  "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

```bash theme={"system"}
# 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 theme={"system"}
# Bash
fireblocks autocomplete bash

# Zsh
fireblocks autocomplete zsh
```