CarsXE CLI

Command-line interface for the CarsXE API. Query vehicle specs, market value, history, recalls, license plates, OBD codes, and more — directly from your terminal or AI agent.

Requirements

• Node.js 22 or higher — nodejs.org

Installation

npm install -g @carsxe/cli

This works the same on Linux, macOS, and Windows (including WSL).

Setup

Option 1 — Browser login (recommended)

Run once and your API key is saved automatically:

carsxe login

This opens your browser to api.carsxe.com, authenticates you, and saves your key to ~/.carsxe/config.json. It is used automatically for every command from that point on.

Option 2 — Set the key manually

Paste your API key from api.carsxe.com/dashboard/developer:

carsxe config set-key YOUR_API_KEY

Option 3 — Environment variable

Set CARSXE_API_KEY before running any command. This takes precedence over the saved config file.

Linux / macOS

export CARSXE_API_KEY=YOUR_API_KEY

Windows (PowerShell — permanent)

[System.Environment]::SetEnvironmentVariable("CARSXE_API_KEY", "YOUR_API_KEY", "User")

Priority order

CARSXE_API_KEY env var takes precedence over ~/.carsxe/config.json.

Global Options

These options apply to every command:

| Option | Description | | --------------- | ------------------------------------------- | | --table | Output as a formatted table instead of JSON | | --raw | Output compact single-line JSON | | -v, --version | Print version number | | -h, --help | Display help |

Tip: Run carsxe <command> --help to see all options for any command.

Commands

login — Browser Login

Authorize via browser and save your API key automatically.

carsxe login

Opens api.carsxe.com/cli-auth in your browser. Sign in with your CarsXE account, the tab closes itself, and your API key is saved to ~/.carsxe/config.json — no copy-pasting needed.

Works on Windows, macOS, Linux, and WSL.

config — Configuration

Manage your saved API key.

carsxe config set-key <api-key>   # Save API key
carsxe config get-key             # Show active key and its source
carsxe config remove-key          # Remove saved key

Examples:

carsxe config set-key abc123xyz
# API key saved to ~/.carsxe/config.json   (Linux/macOS)
# API key saved to C:\Users\You\.carsxe\config.json   (Windows)
# Key: abc1...3xyz

carsxe config get-key
# Source : ~/.carsxe/config.json
# Key    : abc1...3xyz

carsxe config remove-key
# API key removed.

specs — Vehicle Specifications

Decode a VIN and get full vehicle specifications (make, model, year, engine, trim, equipment, and more).

carsxe specs --vin <vin> [--deep-data] [--disable-int-vin]

| Option | Required | Description | | ------------------- | -------- | ----------------------------------------------- | | --vin <vin> | Yes | Vehicle Identification Number | | --deep-data | No | Enable deep data (additional equipment details) | | --disable-int-vin | No | Disable international VIN decoding fallback |

Example:

carsxe specs --vin 1HGBH41JXMN109186

market-value — Market Value

Get the current estimated market value of a vehicle.

carsxe market-value --vin <vin> [--mileage <mileage>] [--state <state>] [--condition <condition>] [--country <country>]

| Option | Required | Description | | ------------------------- | -------- | ----------------------------------------------------------------- | | --vin <vin> | Yes | Vehicle Identification Number | | --mileage <mileage> | No | Current odometer reading in miles | | --state <state> | No | Two-letter US state code for regional pricing (e.g. CA, TX) | | --condition <condition> | No | Vehicle condition: excellent | clean | average | rough | | --country <country> | No | Country code for pricing (default: US) |

Example:

carsxe market-value --vin 1HGBH41JXMN109186 --mileage 45000 --state CA --condition clean

history — Vehicle History

Get a full vehicle history report including past owners, accidents, title status, and odometer readings.

carsxe history --vin <vin>

| Option | Required | Description | | ------------- | -------- | ----------------------------- | | --vin <vin> | Yes | Vehicle Identification Number |

Example:

carsxe history --vin 1HGBH41JXMN109186

recalls — Safety Recalls

Check for open safety recalls on a vehicle.

carsxe recalls --vin <vin>

| Option | Required | Description | | ------------- | -------- | ----------------------------- | | --vin <vin> | Yes | Vehicle Identification Number |

Example:

carsxe recalls --vin 1HGBH41JXMN109186

lien-theft — Lien & Theft Check

Check whether a vehicle has active liens or has been reported stolen.

carsxe lien-theft --vin <vin>

| Option | Required | Description | | ------------- | -------- | ----------------------------- | | --vin <vin> | Yes | Vehicle Identification Number |

Example:

carsxe lien-theft --vin 1HGBH41JXMN109186

international-vin — International VIN Decoder

Decode a VIN from a non-US vehicle (European, Asian, and other markets).

carsxe international-vin --vin <vin>

| Option | Required | Description | | ------------- | -------- | ----------------------------- | | --vin <vin> | Yes | Vehicle Identification Number |

Example:

carsxe international-vin --vin WBAFR7C57CC811956

plate-decoder — License Plate Decoder

Look up vehicle information from a license plate number.

carsxe plate-decoder --plate <plate> --country <country> [--state <state>] [--district <district>]

| Option | Required | Description | | ----------------------- | -------- | ---------------------------------------------- | | --plate <plate> | Yes | License plate number | | --country <country> | Yes | Country code (e.g. US, GB, DE, CA) | | --state <state> | No | State or province code (e.g. CA, TX, ON) | | --district <district> | No | District or region |

Example:

carsxe plate-decoder --plate ABC1234 --country US --state CA

plate-image — Plate Image Recognition

Extract and decode a license plate from an image URL.

carsxe plate-image --image <url>

| Option | Required | Description | | --------------- | -------- | ------------------------------------ | | --image <url> | Yes | Publicly accessible URL of the image |

Example:

carsxe plate-image --image https://example.com/car-photo.jpg

vin-ocr — VIN OCR from Image

Extract a VIN from a photo of a VIN plate or dashboard sticker.

carsxe vin-ocr --image <url>

| Option | Required | Description | | --------------- | -------- | ------------------------------------ | | --image <url> | Yes | Publicly accessible URL of the image |

Example:

carsxe vin-ocr --image https://example.com/vin-sticker.jpg

ymm — Year / Make / Model

Look up vehicle data when you don't have a VIN — search by year, make, and model instead.

carsxe ymm --year <year> --make <make> --model <model> [--trim <trim>]

| Option | Required | Description | | ----------------- | -------- | ----------------------------- | | --year <year> | Yes | Model year (e.g. 2020) | | --make <make> | Yes | Vehicle make (e.g. Toyota) | | --model <model> | Yes | Vehicle model (e.g. Camry) | | --trim <trim> | No | Trim level (e.g. LE, XSE) |

Example:

carsxe ymm --year 2020 --make Toyota --model Camry --trim LE

images — Vehicle Images

Retrieve photos of a vehicle by make, model, and year.

carsxe images --make <make> --model <model> [options]

| Option | Required | Description | | --------------------- | -------- | ------------------------------------------------------------------ | | --make <make> | Yes | Vehicle make (e.g. Toyota) | | --model <model> | Yes | Vehicle model (e.g. Camry) | | --year <year> | No | Model year | | --trim <trim> | No | Trim level | | --color <color> | No | Vehicle color | | --angle <angle> | No | Photo angle: front | side | back | | --photo-type <type> | No | Photo type: interior | exterior | engine | | --size <size> | No | Image size: Small | Medium | Large | Wallpaper | All |

Example:

carsxe images --make Toyota --model Camry --year 2020 --angle front --size Large

obd — OBD-II Code Decoder

Decode a diagnostic trouble code (DTC) from your OBD-II scanner.

carsxe obd --code <code>

| Option | Required | Description | | --------------- | -------- | ----------------------------------------------------- | | --code <code> | Yes | OBD-II code (e.g. P0300, C1234, B0001, U0100) |

Example:

carsxe obd --code P0300

Output

By default all commands output pretty-printed JSON.

Table view — use --table for a human-friendly two-column layout:

carsxe --table obd --code P0300

┌──────────────────────┬────────────────────────────────────────┐
│ Field                │ Value                                  │
├──────────────────────┼────────────────────────────────────────┤
│ success              │ true                                   │
│ code                 │ P0300                                  │
│ definition           │ Random/Multiple Cylinder Misfire ...   │
│ ...                  │ ...                                    │
└──────────────────────┴────────────────────────────────────────┘

Nested objects are flattened with dot notation (e.g. engine.cylinders). Arrays of primitives are joined on one line.

Raw JSON — use --raw for compact single-line JSON, useful for piping to jq or scripts:

Linux / macOS

carsxe --raw specs --vin 1HGBH41JXMN109186 | jq '.make'

Windows (PowerShell)

carsxe --raw specs --vin 1HGBH41JXMN109186 | ConvertFrom-Json | Select-Object -ExpandProperty make

Exit Codes

| Code | Meaning | | ---- | ----------------------------------------- | | 0 | Success | | 1 | API error, HTTP error, or missing API key |

License

MIT — CarsXE