# CLI Setup

> Install lev-cli, authenticate with an API key, validate the connection, and run your first deal query from the terminal.

Source: https://www.lev.com/docs/build/cli-setup

Last updated: March 2026

---
## When to use the CLI

Pick the tool that matches the task — the CLI is optimized for terminals, pipes, and agents.

**CLI fit guide**

- **Good CLI fit:** Ad-hoc queries, CI/CD pipelines, shell scripts, CSV exports, quick lookups during development, LLM-driven coding agents (the CLI outputs structured JSON that tools like Claude Code and Cursor can parse and act on directly), and any workflow where you want structured output without writing code.
- **Bad CLI fit:** Long-running event-driven integrations (use the REST API) or browser-based conversational AI workflows (use MCP).

If you are building a product integration, prefer the **[REST API](/build/api-overview)** directly. If you want AI agents working with Lev, prefer **[MCP Setup](/build/mcp/setup)**.

Put the `lev` binary on your PATH so every later command resolves.

1. **Install with pipx.** Run `pipx install lev-cli` — it installs the CLI in an isolated environment without polluting your global packages.
2. **Fall back to pip if needed.** Run `pip install lev-cli` if you don't have pipx available.
3. **Confirm Python is new enough.** Run `python3 --version` — the CLI requires **Python 3.13+**.

  The Lev CLI is not yet published to PyPI. The commands below are the planned install path — running them today will fail with a "package not found" error. Reach out to your Lev contact for early access via a source install, or check back after GA.

**Install the CLI (once published)**

### pipx (recommended)

```bash
pipx install lev-cli
```

### pip

```bash
pip install lev-cli
```

Check your version with `python3 --version`. We recommend pipx because it installs the CLI in an isolated environment without polluting your global packages.

Store your API key once so every later command is already signed in.

1. **Start the login flow.** Run `lev auth login` and paste your API key when prompted — it's stored in your OS keychain, never written to a file.
2. **Use an environment variable in CI.** For CI/CD, export `LEV_API_KEY=lev_sk_your_key_here` before calling the CLI so keys stay out of command arguments and shell history.
3. **Load from a file to avoid shell history.** For local scripts, use `lev --api-key @/path/to/key.txt deals list` to read the key from a file at call time.

**Choose an auth method**

### Interactive (recommended)

```bash
# Paste your API key when prompted — stored in OS keychain, never written to a file
lev auth login
```

### Environment variable (CI/CD)

```bash
export LEV_API_KEY=lev_sk_your_key_here
lev deals list
```

### From a file (avoids shell history)

```bash
lev --api-key @/path/to/key.txt deals list
```

Create an API key in the Lev platform or via the [API Keys](/build/api-keys) endpoint before authenticating.

Confirm the CLI is signed in to the right account before you run real commands.

1. **Run `lev auth status`.** The command prints your user, account, tier, granted scopes, and rate limits.
2. **Confirm the account name.** If you see the expected workspace name, you're connected.
3. **Review your scopes.** Note which `*:read` and `*:write` scopes are granted — each command below requires specific scopes.

```bash
lev auth status
```

Hit a real read endpoint and see how the CLI switches output format between humans and agents.

1. **List your deals.** Run `lev deals list` — the CLI renders a formatted table in an interactive terminal.
2. **Pipe to JSON for automation.** When piped, the CLI auto-switches to JSON, so `lev deals list | jq '.data[0].title'` returns structured data an LLM agent can parse.
3. **Narrow the query.** Add flags (for example `--limit 5` or filters from `lev deals list --help`) to fetch just what you need.

```bash
lev deals list
```

The CLI renders a formatted table:

```
                       Deals (7 total)
┌──────┬──────────────────────────┬─────────────┬───────────┬──────────┐
│ Id   │ Title                    │ Loan Amount │ Type      │ Updated  │
├──────┼──────────────────────────┼─────────────┼───────────┼──────────┤
│ 2303 │ Office Tower Acquisition │ $50,000,000 │ permanent │ 2d ago   │
│ 2301 │ 500 Broadway Refinance   │ $22,500,000 │ permanent │ 5d ago   │
│ 2000 │ Palm Avenue Residence    │ $19,125,000 │ permanent │ 1mo ago  │
└──────┴──────────────────────────┴─────────────┴───────────┴──────────┘
```

When piped, it switches to JSON automatically:

```bash
lev deals list | jq '.data[0].title'
# "Office Tower Acquisition"
```

## Output formats

The CLI auto-detects: tables for terminals, JSON for pipes. This means LLM coding agents that execute shell commands (Claude Code, Cursor, Windsurf) automatically receive structured JSON they can parse and act on — no extra flags needed.

**Output format flags**

- **(default):** Table — human-readable, auto-selected in interactive terminals.
- **-o json:** JSON — for piping to jq, scripts, LLM agents, or other tools. Auto-selected when output is piped.
- **-o csv:** CSV — export to spreadsheets or data tools.
- **-q:** IDs only — one ID per line for scripting.

**Next:** [CLI Commands](/build/cli-commands) for every command the CLI supports with full examples and output.