The CarsXE CLI lets you query vehicle data straight from your terminal — no browser, no code, no boilerplate. It works on Linux, macOS, and Windows, and is designed to integrate naturally with shell scripts, AI agents, and developer workflows.
You will need a CarsXE API key before using the CLI. Grab one from your [Dashboard → Developer](/dashboard/developer) page.
## Requirements
- **Node.js 22 or higher** — [nodejs.org](https://nodejs.org)
## Installation
Install the CLI globally with npm:
```bash
npm install -g @carsxe/cli
```
Verify the installation:
```bash
carsxe --version
```
## Setup
Save your API key once — it is stored locally and used automatically for every command:
```bash
carsxe config set-key YOUR_API_KEY
```
The key is saved to a local config file:
| OS | Path |
| --- | --- |
| Linux / macOS | `~/.carsxe/config.json` |
| Windows | `C:\Users\\.carsxe\config.json` |
### Using an environment variable instead
If you prefer not to save the key to disk, set the `CARSXE_API_KEY` environment variable. The environment variable takes precedence over the saved config file.
```bash
export CARSXE_API_KEY=YOUR_API_KEY
```
```bash
$env:CARSXE_API_KEY = "YOUR_API_KEY"
```
```bash
set CARSXE_API_KEY=YOUR_API_KEY
```
To make the variable permanent on Linux/macOS, add the `export` line to your `~/.bashrc`, `~/.zshrc`, or `~/.profile`.
---
## 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 (useful with `jq`) |
| `-v, --version` | Print the version number |
| `-h, --help` | Display help |
Run `carsxe --help` to see all options for any specific command.
---
## Commands
### `specs` — Vehicle Specifications
Decode a VIN and get full vehicle specifications: make, model, year, engine, trim, equipment, and more.
```bash
carsxe specs --vin 1HGBH41JXMN109186
```
| Option | Required | Description |
| --- | --- | --- |
| `--vin ` | Yes | Vehicle Identification Number |
| `--deep-data` | No | Enable deep data (additional equipment details) |
| `--disable-int-vin` | No | Disable international VIN decoding fallback |
---
### `market-value` — Market Value
Get the current estimated market value of a vehicle.
```bash
carsxe market-value --vin 1HGBH41JXMN109186 --mileage 45000 --state CA --condition clean
```
| Option | Required | Description |
| --- | --- | --- |
| `--vin ` | Yes | Vehicle Identification Number |
| `--mileage ` | No | Current odometer reading in miles |
| `--state ` | No | Two-letter US state code for regional pricing (e.g. `CA`, `TX`) |
| `--condition ` | No | Vehicle condition: `excellent` \| `clean` \| `average` \| `rough` |
| `--country ` | No | Country code for pricing (default: `US`) |
---
### `history` — Vehicle History
Get a full vehicle history report including past owners, accidents, title status, and odometer readings.
```bash
carsxe history --vin 1HGBH41JXMN109186
```
| Option | Required | Description |
| --- | --- | --- |
| `--vin ` | Yes | Vehicle Identification Number |
---
### `recalls` — Safety Recalls
Check for open safety recalls on a vehicle.
```bash
carsxe recalls --vin 1HGBH41JXMN109186
```
| Option | Required | Description |
| --- | --- | --- |
| `--vin ` | Yes | Vehicle Identification Number |
---
### `lien-theft` — Lien & Theft Check
Check whether a vehicle has active liens or has been reported stolen.
```bash
carsxe lien-theft --vin 1HGBH41JXMN109186
```
| Option | Required | Description |
| --- | --- | --- |
| `--vin ` | Yes | Vehicle Identification Number |
---
### `international-vin` — International VIN Decoder
Decode a VIN from a non-US vehicle (European, Asian, and other markets).
```bash
carsxe international-vin --vin WBAFR7C57CC811956
```
| Option | Required | Description |
| --- | --- | --- |
| `--vin ` | Yes | Vehicle Identification Number |
---
### `plate-decoder` — License Plate Decoder
Look up vehicle information from a license plate number.
```bash
carsxe plate-decoder --plate ABC1234 --country US --state CA
```
| Option | Required | Description |
| --- | --- | --- |
| `--plate ` | Yes | License plate number |
| `--country ` | Yes | Country code (e.g. `US`, `GB`, `DE`, `CA`) |
| `--state ` | No | State or province code (e.g. `CA`, `TX`, `ON`) |
| `--district ` | No | District or region |
---
### `plate-image` — Plate Image Recognition
Extract and decode a license plate from an image URL.
```bash
carsxe plate-image --image https://example.com/car-photo.jpg
```
| Option | Required | Description |
| --- | --- | --- |
| `--image ` | Yes | Publicly accessible URL of the image |
---
### `vin-ocr` — VIN OCR from Image
Extract a VIN from a photo of a VIN plate or dashboard sticker.
```bash
carsxe vin-ocr --image https://example.com/vin-sticker.jpg
```
| Option | Required | Description |
| --- | --- | --- |
| `--image ` | Yes | Publicly accessible URL of the image |
---
### `ymm` — Year / Make / Model
Look up vehicle data when you don't have a VIN — search by year, make, and model instead.
```bash
carsxe ymm --year 2020 --make Toyota --model Camry --trim LE
```
| Option | Required | Description |
| --- | --- | --- |
| `--year ` | Yes | Model year (e.g. `2020`) |
| `--make ` | Yes | Vehicle make (e.g. `Toyota`) |
| `--model ` | Yes | Vehicle model (e.g. `Camry`) |
| `--trim ` | No | Trim level (e.g. `LE`, `XSE`) |
---
### `images` — Vehicle Images
Retrieve photos of a vehicle by make, model, and year.
```bash
carsxe images --make Toyota --model Camry --year 2020 --angle front --size Large
```
| Option | Required | Description |
| --- | --- | --- |
| `--make ` | Yes | Vehicle make |
| `--model ` | Yes | Vehicle model |
| `--year ` | No | Model year |
| `--trim ` | No | Trim level |
| `--color ` | No | Vehicle color |
| `--angle ` | No | Photo angle: `front` \| `side` \| `back` |
| `--photo-type ` | No | Photo type: `interior` \| `exterior` \| `engine` |
| `--size ` | No | Image size: `Small` \| `Medium` \| `Large` \| `Wallpaper` \| `All` |
---
### `obd` — OBD-II Code Decoder
Decode a diagnostic trouble code (DTC) from your OBD-II scanner.
```bash
carsxe obd --code P0300
```
| Option | Required | Description |
| --- | --- | --- |
| `--code ` | Yes | OBD-II code (e.g. `P0300`, `C1234`, `B0001`, `U0100`) |
---
### `config` — Configuration
Manage your saved API key.
```bash
# Save your API key
carsxe config set-key YOUR_API_KEY
# Show active key and its source
carsxe config get-key
# Remove the saved key
carsxe config remove-key
```
---
## Output Formats
By default all commands return pretty-printed JSON. Two flags change the format:
**Table view** — human-friendly two-column layout, great for quick inspection:
```bash
carsxe --table obd --code P0300
```
Nested objects are flattened with dot notation (e.g. `engine.cylinders`). Arrays of primitives are joined on a single line.
**Raw JSON** — compact single-line output:
```bash
carsxe --raw specs --vin 1HGBH41JXMN109186
```
---
## What's next?
- [Grab your API key from the CarsXE dashboard](/dashboard/developer)
- [Browse the full Vehicle Specifications API](/docs/v1/specifications)
- [Learn about authentication](/docs/authentication)
- [Check the full list of error codes](/docs/errors)