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

# CLI Reference

> Full command reference for the Legend CLI

# CLI Reference

The `legend-cli` binary is a Rust-based tool for managing Legend accounts, signing transactions, and running a local MCP server. It handles P256 key management, OAuth login, and direct API access.

## Installation

```bash theme={null}
# macOS (Homebrew)
brew tap legend-hq/tap
brew install legend-cli

# From source (requires Rust toolchain)
cargo install legend-cli
```

On macOS, the Homebrew install is recommended — it includes a code-signed `.app` bundle that enables iCloud Keychain sync for your signing keys.

## Authentication

### OAuth Login (recommended)

```bash theme={null}
legend-cli login
```

Opens your browser for Google SSO. On success, saves a JWT (valid for 30 days) to your profile at `~/.legend/prod/profiles/default.json`. No manual key management needed.

### Query Key

```bash theme={null}
legend-cli config set query-key qk_YOUR_KEY_HERE
```

Or pass it per-command:

```bash theme={null}
legend-cli --key qk_YOUR_KEY_HERE accounts list
```

Or set the environment variable:

```bash theme={null}
export LEGEND_QUERY_KEY=qk_YOUR_KEY_HERE
```

Auth resolution order: `--key` flag > `LEGEND_QUERY_KEY` env > profile file.

## Global Flags

| Flag               | Description                              |
| ------------------ | ---------------------------------------- |
| `--profile <name>` | Use a named profile (default: `default`) |
| `--key <qk_...>`   | Override auth with a query key           |
| `--base-url <url>` | Override API base URL                    |
| `--json`           | Force JSON output (default when piped)   |
| `--quiet`          | Minimal output (IDs only)                |
| `--version` / `-V` | Print version                            |

## Commands

### `login`

Authenticate via Google SSO and save the token to your profile.

```bash theme={null}
legend-cli login
```

### `whoami`

Show current authentication info.

```bash theme={null}
legend-cli whoami
```

### `accounts`

#### `accounts list`

List all sub-accounts.

```bash theme={null}
legend-cli accounts list
```

#### `accounts get <account_id>`

Get details of a specific sub-account.

```bash theme={null}
legend-cli accounts get acc_xxx
```

#### `accounts create`

Create a new sub-account.

```bash theme={null}
# Generate a P256 key and create a Turnkey-backed account (recommended)
legend-cli accounts create --keygen

# Use file-based key instead of macOS Keychain
legend-cli accounts create --keygen --use-file-key

# Create an EOA account with an existing Ethereum address
legend-cli accounts create --signer-type eoa --ethereum-signer 0x742d...
```

With `--keygen`, the CLI:

1. Generates a P256 key in your Mac's Keychain (or on disk with `--use-file-key`)
2. Sends the public key to Legend to create a Turnkey-backed sub-account
3. Saves account details and key reference to your profile

### `plan`

Create execution plans. Add `--execute` to automatically sign and execute in one step.

```bash theme={null}
# Create a plan (returns plan_id + digest for manual signing)
legend-cli plan earn acc_xxx --amount 1000000 --asset USDC --network base --protocol compound

# Create, sign, and execute in one step
legend-cli plan earn acc_xxx --amount 1000000 --asset USDC --network base --protocol compound --execute

# Swap
legend-cli plan swap acc_xxx --sell-asset USDC --buy-asset WETH --sell-amount 1000000 --network base --execute

# Transfer
legend-cli plan transfer acc_xxx --amount 1000000 --asset USDC --network base --recipient 0x742d... --execute
```

Available plan types: `earn`, `swap`, `withdraw`, `transfer`, `borrow`, `repay`.

#### `plan execute`

Execute a previously created plan with a signature.

```bash theme={null}
legend-cli plan execute acc_xxx --plan-id pln_xxx --signature 0xdef456...

# Or auto-sign with the profile's P256 key
legend-cli plan execute acc_xxx --plan-id pln_xxx --auto-sign --digest 0xabc123...
```

### `sign`

Sign an EIP-712 digest using the profile's P256 key via Turnkey.

```bash theme={null}
legend-cli sign 0xabc123...
# Output: 0xdef456... (the signature)
```

### `folio`

View an account's portfolio.

```bash theme={null}
legend-cli folio acc_xxx
```

### `activities`

View transaction history.

```bash theme={null}
legend-cli activities acc_xxx
legend-cli activities acc_xxx --id 42
```

### `networks`

List supported networks.

```bash theme={null}
legend-cli networks
```

### `assets`

List supported assets.

```bash theme={null}
legend-cli assets
```

### `keygen`

Generate a P256 keypair without creating an account.

```bash theme={null}
legend-cli keygen
legend-cli keygen --use-file-key
```

### `keys`

Manage local signing keys. Lists keys from all sources (iCloud Keychain and file).

#### `keys list`

List all keys for the current environment.

```bash theme={null}
legend-cli keys list
# Output:
# default   keychain  0x02abc...
# backup    file      0x03def...
```

#### `keys create <name>`

Create a new key in the iCloud Keychain.

```bash theme={null}
legend-cli keys create my-key
```

#### `keys sign <name> <digest>`

Sign a hex digest with a local key (no Turnkey round-trip).

```bash theme={null}
legend-cli keys sign my-key 0xdeadbeef
```

#### `keys delete <name>`

Delete a key from the Keychain.

```bash theme={null}
legend-cli keys delete my-key
```

### `config set`

Set a configuration value.

```bash theme={null}
legend-cli config set query-key qk_YOUR_KEY_HERE
```

### `mcp serve`

Run a local MCP server via stdio. See [MCP Setup](/agents/mcp/setup) for details.

```bash theme={null}
legend-cli mcp serve
```

## Profile Storage

Profiles are stored at `~/.legend/prod/profiles/<name>.json` and contain:

* Authentication token (query key or JWT)
* P256 key reference (Keychain label or file path)
* Associated account and Turnkey sub-org IDs

## Key Storage

On macOS, P256 keys are stored in the iCloud-synced Data Protection Keychain by default. This means your signing keys are available on all Apple devices signed into the same iCloud account.

File-based keys (when using `--use-file-key`) are stored at `~/.legend/prod/keys/<name>.key` with `chmod 600`. These are local-only and do not sync.

Use `legend-cli keys list` to see all keys available on the current machine.

## Output Modes

* **TTY (human)**: Formatted tables
* **Piped / `--json`**: Raw JSON (default when stdout is not a terminal)
* **`--quiet`**: Just the primary identifier (account\_id, plan\_id, signature)

JSON-by-default-when-piped means agents can pipe output to `jq` without extra flags:

```bash theme={null}
PLAN=$(legend-cli plan earn acc_xxx --amount 1000000 --asset USDC --network base --protocol compound)
echo "$PLAN" | jq -r .plan_id
```