CLI Setup

When to use the CLI

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

If you are building a product integration, prefer the REST API directly. If you want AI agents working with Lev, prefer MCP Setup.

1. Install

   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+.

   Coming soon — not yet on PyPI

   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.

   pipx (recommended)

   pipx install lev-cli

   2 examples. View source for the rest.

   Requires Python 3.13+

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

   Running lev --version in any new terminal returns a version string.
2. Authenticate

   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.

   Interactive (recommended)

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

   3 examples. View source for the rest.

   Need a key first?

   Create an API key in the Lev platform or via the API Keys endpoint before authenticating.

   The CLI accepts your key and returns to the prompt without errors.
3. Validate the connection

   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.

   lev auth status

   You see your account name and a list of scopes that covers the resources you plan to query.
4. Make your first call

   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.

   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:

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

   A deals table in the terminal, or structured JSON when piping to another command.

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.

Next: CLI Commands for every command the CLI supports with full examples and output.