# CLI

> The cadastre command line: install, sign in, screen and rank in the terminal, and add the MCP server to an agent.

`cadastre` is Cadastre's command-line client for the [API](https://getcadastre.com/docs/api): screens, rankings, comparisons and metro profiles in your terminal and your scripts, with the credit every answer requires printed under it, and a command that adds the [MCP server](https://getcadastre.com/docs/mcp) to your AI agent. It is open source (Apache-2.0) and in beta, like the API. Its [README](https://github.com/waratuman/cadastre-cli#readme) is the full reference.

It reads what the API serves, and works without signing in: the data commands read the public datasets at 30 requests a minute. `cadastre login` gives higher limits, with an account that has API access turned on (write to support@getcadastre.com to ask for it).

## Install

```sh
curl -fsSL https://raw.githubusercontent.com/waratuman/cadastre-cli/main/install.sh | sh
```

The script works on macOS and Linux (x86_64 and arm64): it downloads the release for your machine, checks its SHA-256 checksum, and installs `cadastre` to `~/.local/bin` (`/usr/local/bin` as root). It edits no shell profile. Each [release](https://github.com/waratuman/cadastre-cli/releases) has a static binary for Linux (x86_64 and aarch64), macOS (x86_64 and Apple silicon) and Windows (x86_64), with checksums; on Windows, download it from the releases page. The Windows build is listed but has not been tested yet.

## Sign in (optional)

Signing in raises the limits; nothing else needs it.

```sh
cadastre login            # opens your browser: approve "Cadastre CLI" for an account
cadastre login --device   # no browser on this machine: type the code it shows at https://getcadastre.com/oauth/device
cadastre login --key      # use an API key from Settings instead (read from stdin, never an argument)
cadastre whoami           # who the CLI acts as and its limits, or "Not signed in (anonymous ...)"
cadastre logout
```

The browser sign-in is the same consent page every app uses: choose the account, and approve. The CLI keeps its tokens in the system keychain where there is one and refreshes them itself. `CADASTRE_API_KEY`, when set, is used instead of any saved sign-in, for CI. Only start a device sign-in yourself: never type a code someone sent you.

## Commands

| Command | What it does |
| --- | --- |
| `cadastre datasets [key]` | The datasets the API serves, or one with its measures |
| `cadastre measures [name]` | Search the measures, or show one |
| `cadastre metros` | The metro areas, filtered by state or name |
| `cadastre metro <ref>` | One metro's profile, by CBSA code, slug or id |
| `cadastre compare <ref>...` | Up to 25 metros side by side |
| `cadastre screen` | The metros that pass your requirements, with the funnel |
| `cadastre rank` | Rank the metros on weighted criteria |
| `cadastre mcp add <client>` | Add the MCP server to Claude Code, Codex, Cursor or VS Code |
| `cadastre docs [page]` | Open these docs |

`cadastre help <command>` lists every flag. For example:

```sh
cadastre screen --min-pop 500k --max-unemployment 5.5 --states TX,OK
cadastre rank --min-pop 250k --criterion unemployment_rate:2:lower --criterion population
cadastre compare 26620 48620 46140 --json
```

`screen` and `rank` compute an answer and save nothing, as the API's do.

## Output and attribution

Answers print as tables; `--json` prints the API's answer exactly as it came, `attribution` included, for `jq` and for agents. Under every table the CLI prints each source's credit, licence, notices and retrieval date: carry them with the figures wherever you use them, as the [Terms of Service](https://getcadastre.com/terms#api) require. Values marked `*` are Cadastre's own computations from the publisher's figures. [Rights and attribution](https://getcadastre.com/docs/rights) explains each source.

## Connect an AI agent

```sh
cadastre mcp add claude-code     # or codex, cursor, vscode
cadastre mcp add cursor --write  # edit the client's config file for you
```

It prints the client's own command (where it has one) and the config file alternative; nothing is written without `--write`, and with it the file is backed up first and only a `cadastre` entry is added. The agent works without signing in. With `--sign-in` the entry uses the server's sign-in address, and the agent signs in through your browser itself, for higher limits. [Connect an AI agent](https://getcadastre.com/agents) has a guide for each client.

## Exit codes

| Code | Meaning |
| --- | --- |
| 0 | Success |
| 1 | An error: the API refused the request, not found, or a network failure |
| 2 | Usage: an unknown command or flag, or a bad value |
| 3 | The sign-in or key no longer works, or the command needs one: run `cadastre login` |
| 4 | Accept Cadastre's current Terms of Service in a browser (`terms_required`) |
| 5 | Rate limited: wait the seconds the message gives, or sign in for higher limits |
| 6 | The account does not have API access for data that needs it (`api_access_required`; none does today): write to support@getcadastre.com |