---
title: "CLI"
description: "CarsXE command-line interface — query vehicle data from your terminal or AI agent."
canonical_url: "https://docs.carsxe.com/docs/sdks/cli"
markdown_url: "https://docs.carsxe.com/docs/sdks/cli.md"
last_updated: "1980-01-01"
---

# CLI
URL: /docs/sdks/cli
LLM index: /llms.txt
Description: CarsXE command-line interface — query vehicle data from your terminal or AI agent.

The `@carsxe/cli` package puts every CarsXE endpoint on the command line. Decode VINs, look up plates, pull recalls, and more — all from your terminal. Requires Node.js 22 or later.

## Installation

```bash
# Install globally
npm install -g @carsxe/cli

# Or run without installing
npx @carsxe/cli specs --vin WBAFR7C57CC811956
```

## Authentication

Set your API key before running commands. The `CARSXE_API_KEY` environment variable takes priority over the saved config.

```bash
# Save to ~/.carsxe/config.json
carsxe config set-key YOUR_API_KEY

# Or use an environment variable (takes priority)
export CARSXE_API_KEY=YOUR_API_KEY
```

You can also authenticate via browser:

```bash
carsxe login
```

## Commands

### Vehicle data

```bash
# Full vehicle specs from VIN
carsxe specs --vin WBAFR7C57CC811956

# Include extended vehicle data
carsxe specs --vin WBAFR7C57CC811956 --deep-data

# Market value estimate
carsxe market-value --vin WBAFR7C57CC811956 --mileage 45000 --state CA

# Vehicle history report
carsxe history --vin WBAFR7C57CC811956

# Open safety recalls
carsxe recalls --vin WBAFR7C57CC811956

# License plate → VIN
carsxe plate-decoder --plate ABC1234 --country US --state CA

# Lien and theft status
carsxe lien-theft --vin WBAFR7C57CC811956

# International VIN decoder
carsxe international-vin --vin WBAFR7C57CC811956
```

### Recognition

```bash
# Extract plate info from an image URL
carsxe plate-image --image https://example.com/plate.jpg

# Extract VIN from an image via OCR
carsxe vin-ocr --image https://example.com/vin.jpg
```

### Year Make Model

```bash
# Look up vehicles by year, make, and model
carsxe ymm --year 2022 --make BMW --model "3 Series"

# Get vehicle photos
carsxe images --make BMW --model "3 Series" --year 2022 --angle front

# Decode an OBD-II diagnostic code
carsxe obd --code P0420
```

### Config

```bash
carsxe config set-key YOUR_API_KEY   # Save API key
carsxe config get-key                # Show active key
carsxe config remove-key             # Remove saved key
```

## Output formats

By default the CLI prints a formatted, colorized summary. Use `--table` or `--raw` to change the output:

| Flag | Output |
|---|---|
| _(default)_ | Human-readable formatted output |
| `--table` | ASCII table — good for quick comparison |
| `--raw` | Compact JSON — pipe-friendly |

```bash
# Pipe raw JSON to jq
carsxe specs --vin WBAFR7C57CC811956 --raw | jq '.data.make'

# Save to a file
carsxe history --vin WBAFR7C57CC811956 --raw > history.json
```

## Best practices

**Use the environment variable in CI/CD.** Add `CARSXE_API_KEY` as a secret in GitHub Actions, CircleCI, or your deployment environment — don't rely on the saved config file in automated contexts.

```yaml
# GitHub Actions example
- name: Decode VIN
  env:
    CARSXE_API_KEY: ${{ secrets.CARSXE_API_KEY }}
  run: carsxe specs --vin WBAFR7C57CC811956 --raw
```

**Combine `--raw` with `jq`** for scripting:

```bash
# Extract just the market value retail price
carsxe market-value --vin WBAFR7C57CC811956 --mileage 30000 --raw \
  | jq '.data.retail'

# Check if a VIN has any open recalls
carsxe recalls --vin WBAFR7C57CC811956 --raw \
  | jq 'if .data | length > 0 then "HAS RECALLS" else "CLEAN" end'
```

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).