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

# Realie CLI

> Property data from the terminal — built for developers and AI agents

## About the Realie CLI

The Realie CLI lets you access property data, manage API keys, and monitor usage directly from the terminal. It's designed for both interactive use and autonomous operation by AI coding agents like Claude Code, Cursor, and Copilot.

Every command outputs human-readable text by default, with a `--json` flag for machine-parseable output.

## Install

<Tabs>
  <Tab title="Shell (recommended)">
    ```bash theme={null}
    curl -fsSL https://app.realie.ai/api/cli/install | bash
    ```

    This downloads a single-file bundle (\~150KB) to `~/.realie/bin/` and adds it to your PATH. Requires Node.js 18+.
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    npm install -g @realie/cli
    ```
  </Tab>

  <Tab title="npx (no install)">
    ```bash theme={null}
    npx @realie/cli --help
    ```
  </Tab>
</Tabs>

## Quick Start

<Steps>
  <Step title="Authenticate">
    Run `realie login` to open your browser and sign in:

    ```bash theme={null}
    realie login
    ```

    This opens `app.realie.ai` in your browser. Sign in with your Realie account, confirm the code shown in the terminal, and you're authenticated.

    For CI/CD or AI agents, pass an API key directly:

    ```bash theme={null}
    realie login --api-key YOUR_API_KEY
    ```
  </Step>

  <Step title="Look up a property">
    ```bash theme={null}
    realie lookup --address "504 LAVACA ST" --state TX --county TRAVIS
    ```
  </Step>

  <Step title="Check your usage">
    ```bash theme={null}
    realie usage
    ```
  </Step>
</Steps>

## Commands

### Authentication

| Command         | Description                                                |
| --------------- | ---------------------------------------------------------- |
| `realie login`  | Sign in via browser (OAuth) or `--api-key` for direct auth |
| `realie logout` | Remove stored credentials                                  |
| `realie whoami` | Show current authenticated user and plan                   |

### Property Data

| Command                                                         | Description                                                               |
| --------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `realie lookup --address "..." --state TX`                      | Look up a property by address                                             |
| `realie search --state TX --county DENTON --limit 10`           | Search properties using the full `/api/public/property/search` filter set |
| `realie comparables --latitude 30.2 --longitude -97.7`          | Find comparable properties near a location                                |
| `realie parcel --parcel-id "R12345" --state TX --county TRAVIS` | Look up a property by parcel ID                                           |
| `realie location --latitude 30.2 --longitude -97.7`             | Search nearby properties                                                  |

### Account Management

| Command                  | Description                                     |
| ------------------------ | ----------------------------------------------- |
| `realie usage`           | Show API token usage for current billing period |
| `realie keys list`       | Show your current API key                       |
| `realie keys regenerate` | Generate a new API key                          |

### Utilities

| Command                           | Description                                |
| --------------------------------- | ------------------------------------------ |
| `realie docs [search]`            | Search Realie documentation                |
| `realie config list`              | Show CLI configuration                     |
| `realie config set <key> <value>` | Set a config value (baseUrl, defaultState) |
| `realie status`                   | Check API health and latency               |
| `realie version`                  | Show CLI version and environment info      |
| `realie upgrade`                  | Upgrade to the latest CLI version          |

## JSON Mode

Add `--json` to any command for machine-readable output. This is what AI agents and scripts should use.

```bash theme={null}
# Human-readable (default)
realie usage
# Plan: Enterprise 1 (yearly)
# Period: Mar 29, 2026 – Mar 29, 2027
# API Tokens: ░░░░░░░░░░░░░░░░░░░░ 6 / 1,200,000 (0.0%)

# Machine-readable
realie --json usage
```

```json theme={null}
{
  "plan": "Enterprise 1",
  "planId": "apiEnterprise1",
  "billingPeriod": { "start": "2026-03-29", "end": "2027-03-29", "interval": "yearly" },
  "usage": { "apiCalls": 6, "apiTokens": 6, "baseTokens": 1200000 },
  "endpointBreakdown": { "property/address": 1, "premium/comparables": 4, "property/search": 1 },
  "overage": { "tokens": 0, "estimatedCost": "$0.00" }
}
```

## API Parameter Parity

The API-backed property commands mirror their corresponding endpoint query parameters using kebab-case CLI flags.

* `realie lookup` mirrors `/api/public/property/address`
* `realie search` mirrors `/api/public/property/search`
* `realie parcel` mirrors `/api/public/property/parcelId`
* `realie location` mirrors `/api/public/property/location`
* `realie comparables` mirrors `/api/public/premium/comparables`

Examples:

```bash theme={null}
realie search \
  --state WI \
  --county TAYLOR \
  --city WESTBORO \
  --zip-code 54451 \
  --include-unassigned-address true \
  --limit 25

realie comparables \
  --latitude 30.2672 \
  --longitude -97.7431 \
  --time-frame 12 \
  --beds-min 2 \
  --beds-max 4 \
  --price-min 300000 \
  --price-max 900000

realie location \
  --latitude 45.3090682 \
  --longitude -90.5608659 \
  --radius 0.05 \
  --include-unassigned-address true \
  --limit 10
```

## Configuration

Config is stored at `~/.realie/config.json`:

| Key             | Description                           | Default                 |
| --------------- | ------------------------------------- | ----------------------- |
| `apiKey`        | Your API key (set via `realie login`) | —                       |
| `baseUrl`       | API base URL                          | `https://app.realie.ai` |
| `defaultState`  | Default state code for queries        | —                       |
| `defaultFormat` | Output format (`json` or `pretty`)    | `pretty`                |

You can also authenticate via the `REALIE_API_KEY` environment variable:

```bash theme={null}
REALIE_API_KEY=your_key realie whoami
```

## For AI Agents

The CLI is designed for fully autonomous use by AI coding agents:

* **Browser login**: `realie login` opens a browser for OAuth sign-in (interactive terminals)
* **Direct auth**: `realie login --api-key <key>` or `REALIE_API_KEY` env var (non-interactive / CI)
* **JSON output**: `--json` on every command for structured, parseable responses
* **Structured errors**: `{ "error": "message", "code": "ERROR_CODE" }` with exit code 1
* **Self-updating**: `realie upgrade` checks for and installs new versions

<Tabs>
  <Tab title="Claude Code">
    Add to your `CLAUDE.md` or agent instructions:

    ```
    Use the `realie` CLI to query property data.
    Always pass --json for parseable output.
    Authenticate with: realie login --api-key <key>
    ```
  </Tab>

  <Tab title="Cursor">
    Add to your `.cursorrules`:

    ```
    The realie CLI is available for property data queries.
    Use `realie --json <command>` for structured output.
    ```
  </Tab>

  <Tab title="Environment Variable">
    For CI/CD or agent environments, set the API key as an environment variable:

    ```bash theme={null}
    export REALIE_API_KEY=your_api_key
    realie --json lookup --address "123 Main St" --state TX
    ```
  </Tab>
</Tabs>