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

# Visor CLI

> Install, authenticate, update, and use the Visor CLI for the Public API.

The Visor CLI is a read-only command-line client for the Visor Public API. It covers listings, facets, VIN lookup, dealers, and dealer inventory, with JSON output, field selection, CSV export, and compact output for scripts and agents.

## Install

### macOS and Linux

Install the latest prebuilt binary without Go:

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/visorvin/cli/main/install.sh | sh
```

For CI, agents, and other non-interactive shells, install into a user-writable directory so the installer does not need `sudo`:

```bash theme={null}
BIN_DIR="$HOME/.local/bin" sh -c 'curl -fsSL https://raw.githubusercontent.com/visorvin/cli/main/install.sh | sh'
```

If needed, add the install directory to `PATH`:

```bash theme={null}
export PATH="$HOME/.local/bin:$PATH"
```

### Windows

Download the latest Windows archive from GitHub Releases, extract `visor.exe`, and add it to your `PATH`:

```text theme={null}
https://github.com/visorvin/cli/releases/latest
```

### From source

Developers who already have Go installed can build the CLI and optional MCP server from source:

```bash theme={null}
go install github.com/visorvin/cli/cmd/visor@latest
go install github.com/visorvin/cli/cmd/visor-mcp@latest
```

## Authenticate

The CLI reads `VISOR_API_KEY` from the environment:

```bash theme={null}
export VISOR_API_KEY="your-api-key"
visor doctor
```

You can also store a token locally. For humans, use the secure prompt:

```bash theme={null}
visor auth set-token
visor auth status
```

For scripts and agents, pipe the token over stdin so it does not appear in process arguments:

```bash theme={null}
printf '%s' "$VISOR_API_KEY" | visor auth set-token --stdin
visor auth status --json
```

Run `visor doctor` to check authentication and API connectivity.

## Use the CLI

Run help first to see the available commands and flags:

```bash theme={null}
visor --help
visor listings list --help
visor facets --help
```

The main commands map to Public API endpoints:

| CLI command                               | API endpoint                           |
| ----------------------------------------- | -------------------------------------- |
| `visor listings list`                     | `GET /v1/listings`                     |
| `visor listings get <listing_id>`         | `GET /v1/listings/{listing_id}`        |
| `visor facets`                            | `GET /v1/facets`                       |
| `visor vins <vin>`                        | `GET /v1/vins/{vin}`                   |
| `visor dealers list`                      | `GET /v1/dealers`                      |
| `visor dealers get <dealer_id>`           | `GET /v1/dealers/{dealer_id}`          |
| `visor dealers listings list <dealer_id>` | `GET /v1/dealers/{dealer_id}/listings` |

## Output

Use `--json` for full JSON output:

```bash theme={null}
visor listings list --json --make toyota --model camry --limit 10
```

Use `--agent` for compact, predictable output in scripts and LLM tools:

```bash theme={null}
visor listings list --agent --make toyota --model camry --limit 10
```

`--agent` enables JSON output, compact responses, no interactive prompts, no color, and yes-to-confirmations where applicable.

Use `--select` to return only specific fields:

```bash theme={null}
visor listings list \
  --agent \
  --make toyota \
  --model camry \
  --limit 10 \
  --select id,vin,year,make,model,price,miles,dealer_name,vdp_url
```

For standard list responses, `--select` accepts row-relative field names such as `id,vin,year,price,miles`. Full response paths such as `results.data.vin` also work. Listing fields use `miles`, not `mileage`, and `vdp_url`, not `url`.

## Facet-first searches

Use facets before narrow listing searches when you are unsure of canonical make, model, trim, or inventory values.

```bash theme={null}
visor facets --agent --facets make --facet-value-limit 100
```

Then use the returned make value to discover models:

```bash theme={null}
visor facets --agent --facets model --make Ford --facet-value-limit 100
```

Use `--facet-value-limit 100` when you need more than the default 20 values per categorical facet.

Use the exact returned facet value in listing searches:

```bash theme={null}
visor listings list \
  --agent \
  --make Ford \
  --model F-150 \
  --state TX \
  --limit 10
```

If a narrow search returns no rows, go back to facets and inspect canonical values for the next filter instead of guessing spellings.

## Update

For prebuilt installs, rerun the installer:

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/visorvin/cli/main/install.sh | sh
```

For user-writable installs:

```bash theme={null}
BIN_DIR="$HOME/.local/bin" sh -c 'curl -fsSL https://raw.githubusercontent.com/visorvin/cli/main/install.sh | sh'
```

For Go installs:

```bash theme={null}
go install github.com/visorvin/cli/cmd/visor@latest
go install github.com/visorvin/cli/cmd/visor-mcp@latest
```

Check the installed version and health after updating:

```bash theme={null}
visor version
visor doctor
```

## MCP options

The hosted MCP server is the recommended setup for Claude Desktop, Claude Code, Codex, ChatGPT, OpenCode, and other clients that support remote MCP servers:

```txt theme={null}
https://mcp.visor.vin/mcp
```

See [MCP setup](/docs/mcp-setup) for OAuth and bearer-token configuration snippets.

The optional local CLI MCP server is available for hosts that need to launch a local stdio process:

```bash theme={null}
visor-mcp --help
```

Example local config:

```json theme={null}
{
  "mcpServers": {
    "visor": {
      "command": "visor-mcp",
      "env": {
        "VISOR_API_KEY": "your-api-key"
      }
    }
  }
}
```