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

# CLI Reference

> Complete reference for all zero CLI commands

## Overview

The `zero` CLI provides full access to 0 Finance from your terminal. All commands output JSON for easy scripting and piping.

```bash theme={null}
zero <command> [subcommand] [options]
```

<Tip>You can also use the alias `zero-bank`.</Tip>

<Info>
  Transfers, savings actions, and crypto moves create proposals that require
  dashboard approval.
</Info>

***

## Authentication

### `zero auth connect`

Open the browser to connect the CLI and store the API key automatically.

```bash theme={null}
zero auth
zero auth connect
zero login
```

| Option         | Required | Description                                  |
| -------------- | -------- | -------------------------------------------- |
| `--base-url`   | No       | Base URL (default: `https://www.0.finance`)  |
| `--no-browser` | No       | Print URL instead of opening a browser       |
| `--manual`     | No       | Skip callback and paste the API key manually |

### `zero auth login`

Store your API key and configure the CLI manually.

```bash theme={null}
zero auth login --api-key sk_live_xxx
zero auth login --api-key sk_live_xxx --base-url https://custom.0.finance
```

| Option       | Required | Description                                     |
| ------------ | -------- | ----------------------------------------------- |
| `--api-key`  | Yes      | Your workspace API key                          |
| `--base-url` | No       | API base URL (default: `https://www.0.finance`) |

### `zero auth whoami`

Show the current workspace context.

```bash theme={null}
zero auth whoami
```

### `zero auth logout`

Remove stored credentials.

```bash theme={null}
zero auth logout
```

***

## Configuration

### `zero config show`

Show the current config path, base URL, and key prefix.

```bash theme={null}
zero config show
```

### `zero config set`

Update stored configuration values.

```bash theme={null}
zero config set --base-url http://localhost:3050
zero config set --api-key sk_live_xxx
```

***

## Debugging

Use `--debug` to see request URLs and the base URL being used.

```bash theme={null}
zero --debug auth whoami
```

***

## Balance

### `zero balance`

Show your spendable, earning, and idle USDC balances on Base.

```bash theme={null}
zero balance
```

**Output:**

```json theme={null}
{
  "idle_balance": "3200.00",
  "earning_balance": "4220.50",
  "spendable_balance": "7420.50",
  "safe_address": "0x954A329e1e59101DF529CC54A54666A0b36Cae22",
  "chain": "base"
}
```

<Tip>Use `zero savings positions` to include vault-level breakdowns.</Tip>

***

## Bank Accounts

### `zero bank accounts list`

List all saved bank accounts.

```bash theme={null}
zero bank accounts list
```

### `zero bank accounts create`

Create a saved bank account from a JSON file.

```bash theme={null}
zero bank accounts create --json ./account.json
```

**account.json (IBAN example):**

```json theme={null}
{
  "account_name": "Acme EUR",
  "bank_name": "Commerzbank",
  "account_holder_type": "business",
  "account_holder_business_name": "Acme Corp",
  "country": "DE",
  "city": "Berlin",
  "street_line_1": "Friedrichstr. 1",
  "postal_code": "10117",
  "account_type": "iban",
  "iban_number": "DE89370400440532013000",
  "bic_swift": "COBADEFFXXX",
  "is_default": true
}
```

<Tip>
  For US accounts, set `account_type` to `"us"` and include `account_number` and
  `routing_number`. For individual accounts, provide `account_holder_first_name`
  and `account_holder_last_name`.
</Tip>

***

## Bank Transfers

### `zero bank transfers propose`

Propose a bank transfer for approval.

```bash theme={null}
zero bank transfers propose \
  --amount 1000 \
  --currency usd \
  --bank-account-id ba_xxx \
  --reason "Contractor payment for January"
```

| Option              | Required | Description                           |
| ------------------- | -------- | ------------------------------------- |
| `--amount`          | Yes      | Amount in USDC                        |
| `--currency`        | Yes      | Destination currency (`usd` or `eur`) |
| `--bank-account-id` | Yes      | Saved bank account ID                 |
| `--reason`          | No       | Reason for the transfer               |

<Info>
  IBAN accounts require `--currency eur`. US bank accounts require `--currency
      usd`.
</Info>

<Info>
  Transfers create proposals that require approval in the dashboard before
  executing.
</Info>

<Warning>
  Transfers require completed KYC. If KYC is missing, the command returns an
  error asking the user to complete verification.
</Warning>

### `zero bank proposals list`

List pending transfer proposals.

```bash theme={null}
zero bank proposals list
zero bank proposals list --include-completed
```

| Option                | Description                 |
| --------------------- | --------------------------- |
| `--include-completed` | Include completed proposals |

### `zero bank proposals dismiss`

Dismiss a transfer proposal.

```bash theme={null}
zero bank proposals dismiss --proposal-id prop_xxx
```

***

## Invoices

### `zero invoices create`

Create a new invoice.

```bash theme={null}
zero invoices create \
  --recipient-email client@example.com \
  --recipient-name "Acme Corp" \
  --amount 2500 \
  --currency USD \
  --description "Q1 consulting services" \
  --due-date 2026-02-15 \
  --notes "Payment terms: Net 30"
```

| Option              | Required | Description                    |
| ------------------- | -------- | ------------------------------ |
| `--recipient-email` | Yes      | Client's email address         |
| `--recipient-name`  | No       | Client's name                  |
| `--amount`          | Yes      | Invoice amount                 |
| `--currency`        | Yes      | Currency code (USD, EUR, etc.) |
| `--description`     | Yes      | Line item description          |
| `--due-date`        | No       | Due date (YYYY-MM-DD)          |
| `--notes`           | No       | Additional notes               |

### `zero invoices list`

List invoices with optional filters.

```bash theme={null}
zero invoices list
zero invoices list --status pending --limit 10
```

| Option     | Description                                                    |
| ---------- | -------------------------------------------------------------- |
| `--status` | Filter by status (`db_pending`, `pending`, `paid`, `canceled`) |
| `--limit`  | Maximum number of results                                      |

### `zero invoices get`

Get a specific invoice.

```bash theme={null}
zero invoices get --invoice-id inv_xxx
```

### `zero invoices update`

Update an existing invoice.

```bash theme={null}
zero invoices update \
  --invoice-id inv_xxx \
  --amount 3000 \
  --description "Updated scope"
```

| Option              | Required | Description            |
| ------------------- | -------- | ---------------------- |
| `--invoice-id`      | Yes      | Invoice ID             |
| `--recipient-email` | No       | Update recipient email |
| `--recipient-name`  | No       | Update recipient name  |
| `--amount`          | No       | Update amount          |
| `--currency`        | No       | Update currency        |
| `--description`     | No       | Update description     |

### `zero invoices send`

Send an invoice to the recipient.

```bash theme={null}
zero invoices send --invoice-id inv_xxx
```

***

## Transactions

### `zero transactions list`

List transaction history.

```bash theme={null}
zero transactions list
zero transactions list --status completed --limit 50
```

| Option     | Description                                         |
| ---------- | --------------------------------------------------- |
| `--status` | Filter by status (`pending`, `completed`, `failed`) |
| `--limit`  | Maximum number of results                           |

### `zero transactions get`

Get transaction details.

```bash theme={null}
zero transactions get --transaction-id tx_xxx
```

***

## Attachments

### `zero attachments add`

Attach a file to a transaction.

```bash theme={null}
zero attachments add \
  --transaction-id tx_xxx \
  --transaction-type offramp \
  --file ./receipt.pdf
```

| Option               | Required | Description                               |
| -------------------- | -------- | ----------------------------------------- |
| `--transaction-id`   | Yes      | Transaction ID                            |
| `--transaction-type` | Yes      | Transaction type (`offramp` or `invoice`) |
| `--type`             | No       | Alias for `--transaction-type`            |
| `--file`             | Yes      | Path to file                              |
| `--content-type`     | No       | MIME type (auto-detected if omitted)      |

### `zero attachments list`

List attachments.

```bash theme={null}
zero attachments list
zero attachments list --transaction-id tx_xxx
```

| Option               | Description                             |
| -------------------- | --------------------------------------- |
| `--transaction-id`   | Filter by transaction ID                |
| `--transaction-type` | Filter by type (`offramp` or `invoice`) |
| `--limit`            | Maximum number of results               |

### `zero attachments remove`

Remove an attachment.

```bash theme={null}
zero attachments remove --attachment-id att_xxx
```

***

## Payment Details

### `zero payment-details show`

Show payment details for receiving funds (USD ACH + EUR IBAN).

```bash theme={null}
zero payment-details show
```

**Output:**

```json theme={null}
{
  "payment_details": {
    "hasAccounts": true,
    "accountTier": "full",
    "hasCompletedKyc": true,
    "usdAccount": {
      "type": "us_ach",
      "currency": "USD",
      "bankName": "Mercury",
      "routingNumber": "123456789",
      "accountNumber": "000123456789",
      "beneficiaryName": "0 Finance FBO Jane Doe"
    },
    "eurAccount": {
      "type": "iban",
      "currency": "EUR",
      "bankName": "Commerzbank",
      "iban": "DE89370400440532013000",
      "bicSwift": "COBADEFFXXX",
      "beneficiaryName": "0 Finance FBO Jane Doe"
    },
    "workspaceInfo": {
      "companyName": "Acme Corp",
      "firstName": "Jane",
      "lastName": "Doe"
    }
  },
  "message": "These are the bank account details for receiving payments."
}
```

### `zero payment-details share`

Email your payment details to someone.

```bash theme={null}
zero payment-details share \
  --recipient-email accountant@example.com \
  --recipient-name "Jane Smith"
```

***

## Crypto Transfers

### `zero crypto transfers propose`

Propose a crypto transfer.

```bash theme={null}
zero crypto transfers propose \
  --to 0x742d35Cc6634C0532925a3b844Bc9e7595f... \
  --token-address 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 \
  --amount 100 \
  --token-symbol USDC \
  --token-decimals 6 \
  --chain-id 8453 \
  --reason "Partner payment"
```

| Option             | Required | Description                                   |
| ------------------ | -------- | --------------------------------------------- |
| `--to`             | Yes      | Recipient wallet address                      |
| `--token-address`  | Yes      | Token contract address                        |
| `--amount`         | Yes      | Token amount                                  |
| `--token-symbol`   | No       | Token symbol (e.g., USDC)                     |
| `--token-decimals` | No\*     | Token decimals (required for non-USDC tokens) |
| `--chain-id`       | No       | Chain ID (defaults to 8453/Base if omitted)   |
| `--reason`         | No       | Reason for transfer                           |

<Tip>
  If `--token-address` is the Base USDC contract, you can omit
  `--token-decimals` and it will default to 6.
</Tip>

### `zero crypto proposals list`

List crypto transfer proposals.

```bash theme={null}
zero crypto proposals list
zero crypto proposals list --include-completed
```

| Option                | Description                 |
| --------------------- | --------------------------- |
| `--include-completed` | Include completed proposals |

### `zero crypto proposals dismiss`

Dismiss a crypto proposal.

```bash theme={null}
zero crypto proposals dismiss --proposal-id prop_xxx
```

***

## Savings

### `zero vaults list`

List supported yield vaults.

```bash theme={null}
zero vaults list
```

### `zero savings deposits propose`

Propose a deposit into a yield vault.

```bash theme={null}
zero savings deposits propose \
  --vault-address 0x... \
  --amount 1000 \
  --reason "Earning yield on idle funds"
```

### `zero savings withdrawals propose`

Propose a withdrawal from a yield vault.

```bash theme={null}
zero savings withdrawals propose \
  --vault-address 0x... \
  --amount 500 \
  --reason "Need funds for payment"
```

<Info>
  Vault addresses must come from `zero vaults list` (Base USDC vaults).
</Info>

### `zero savings proposals list`

List savings proposals.

```bash theme={null}
zero savings proposals list
zero savings proposals list --include-completed
```

| Option                | Description                 |
| --------------------- | --------------------------- |
| `--include-completed` | Include completed proposals |

### `zero savings positions`

Show idle balance, earning balance, and vault positions.

```bash theme={null}
zero savings positions
```

**Output:**

```json theme={null}
{
  "idle_balance": "420.50",
  "earning_balance": "2000.00",
  "spendable_balance": "2420.50",
  "safe_address": "0x954A329e1e59101DF529CC54A54666A0b36Cae22",
  "chain": "base",
  "vault_positions": [
    {
      "vault_address": "0x...",
      "vault_name": "Morpho USDC",
      "balance_usd": 2000
    }
  ]
}
```

***

## Admin Commands

<Warning>
  Admin commands require an admin token. Set `ZERO_FINANCE_ADMIN_TOKEN` or use
  `--admin-token`.
</Warning>

### `zero users create`

Provision a new user.

```bash theme={null}
zero users create \
  --email user@example.com \
  --admin-token adm_xxx
```

| Option           | Required | Description                                     |
| ---------------- | -------- | ----------------------------------------------- |
| `--email`        | Yes\*    | User email (required if no phone)               |
| `--phone`        | Yes\*    | User phone (required if no email)               |
| `--wallets-json` | No       | Path to wallets JSON array                      |
| `--admin-token`  | No       | Admin token (or set `ZERO_FINANCE_ADMIN_TOKEN`) |

### `zero users show`

Get user details.

```bash theme={null}
zero users show --user-id did:privy:xxx --admin-token adm_xxx
```

### `zero users wallets pregenerate`

Pregenerate wallets for a user.

```bash theme={null}
zero users wallets pregenerate \
  --user-id did:privy:xxx \
  --wallets-json ./wallets.json \
  --admin-token adm_xxx
```

| Option           | Required | Description                                     |
| ---------------- | -------- | ----------------------------------------------- |
| `--user-id`      | Yes      | Privy user DID                                  |
| `--wallets-json` | No       | Path to wallets JSON array                      |
| `--admin-token`  | No       | Admin token (or set `ZERO_FINANCE_ADMIN_TOKEN`) |

### `zero api-keys create`

Create an API key for a workspace.

```bash theme={null}
zero api-keys create \
  --workspace-id ws_xxx \
  --created-by did:privy:xxx \
  --name "Production API Key" \
  --admin-token adm_xxx
```

| Option           | Required | Description                                     |
| ---------------- | -------- | ----------------------------------------------- |
| `--workspace-id` | Yes      | Workspace ID                                    |
| `--created-by`   | Yes      | Privy user DID that owns the key                |
| `--name`         | No       | Friendly name for the key                       |
| `--expires-at`   | No       | ISO expiration date (e.g. `2026-12-31`)         |
| `--admin-token`  | No       | Admin token (or set `ZERO_FINANCE_ADMIN_TOKEN`) |

***

## Tips

### JSON output

All commands output JSON. Pipe to `jq` for formatting:

```bash theme={null}
zero balance | jq .spendable_balance
```

### Scripting

Use the CLI in scripts:

```bash theme={null}
#!/bin/bash
BALANCE=$(zero balance | jq -r .spendable_balance)
if (( $(echo "$BALANCE > 10000" | bc -l) )); then
  zero savings deposits propose \
    --vault-address 0x... \
    --amount 5000 \
    --reason "Auto-deposit excess funds"
fi
```

### Error handling

Non-zero exit codes indicate errors. Error messages are printed to stderr:

```bash theme={null}
zero invoices get --invoice-id invalid_id || echo "Invoice not found"
```