CLI Quickstart Guide
Query vehicle specs, market value, history, recalls, license plates, OBD codes, and more — directly from your terminal using the CarsXE CLI.
On this page
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 page.
RequirementsCopy section for LLMCopy link to sectionAsk AI about this section
- Node.js 22 or higher — nodejs.org
InstallationCopy section for LLMCopy link to sectionAsk AI about this section
Install the CLI globally with npm:
Install
npm install -g @carsxe/cliVerify the installation:
Verify
carsxe --versionSetupCopy section for LLMCopy link to sectionAsk AI about this section
Save your API key once — it is stored locally and used automatically for every command:
Save API Key
carsxe config set-key YOUR_API_KEYThe key is saved to a local config file:
| OS | Path |
|---|---|
| Linux / macOS | ~/.carsxe/config.json |
| Windows | C:\Users\<YourName>\.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.
Linux / macOS
export CARSXE_API_KEY=YOUR_API_KEYWindows (PowerShell)
$env:CARSXE_API_KEY = "YOUR_API_KEY"Windows (Command Prompt)
set CARSXE_API_KEY=YOUR_API_KEYTo make the variable permanent on Linux/macOS, add the export line to your ~/.bashrc, ~/.zshrc, or ~/.profile.
Global OptionsCopy section for LLMCopy link to sectionAsk AI about this section
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 <command> --help to see all options for any specific command.
CommandsCopy section for LLMCopy link to sectionAsk AI about this section
specs — Vehicle Specifications
Decode a VIN and get full vehicle specifications: make, model, year, engine, trim, equipment, and more.
specs
carsxe specs --vin 1HGBH41JXMN109186| 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 |
market-value — Market Value
Get the current estimated market value of a vehicle.
market-value
carsxe market-value --vin 1HGBH41JXMN109186 --mileage 45000 --state CA --condition clean| 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) |
history — Vehicle History
Get a full vehicle history report including past owners, accidents, title status, and odometer readings.
history
carsxe history --vin 1HGBH41JXMN109186| Option | Required | Description |
|---|---|---|
--vin <vin> | Yes | Vehicle Identification Number |
recalls — Safety Recalls
Check for open safety recalls on a vehicle.
recalls
carsxe recalls --vin 1HGBH41JXMN109186| Option | Required | Description |
|---|---|---|
--vin <vin> | Yes | Vehicle Identification Number |
lien-theft — Lien & Theft Check
Check whether a vehicle has active liens or has been reported stolen.
lien-theft
carsxe lien-theft --vin 1HGBH41JXMN109186| Option | Required | Description |
|---|---|---|
--vin <vin> | Yes | Vehicle Identification Number |
international-vin — International VIN Decoder
Decode a VIN from a non-US vehicle (European, Asian, and other markets).
international-vin
carsxe international-vin --vin WBAFR7C57CC811956| Option | Required | Description |
|---|---|---|
--vin <vin> | Yes | Vehicle Identification Number |
plate-decoder — License Plate Decoder
Look up vehicle information from a license plate number.
plate-decoder
carsxe plate-decoder --plate ABC1234 --country US --state CA| 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 |
plate-image — Plate Image Recognition
Extract and decode a license plate from an image URL.
plate-image
carsxe plate-image --image https://example.com/car-photo.jpg| Option | Required | Description |
|---|---|---|
--image <url> | 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.
vin-ocr
carsxe vin-ocr --image https://example.com/vin-sticker.jpg| Option | Required | Description |
|---|---|---|
--image <url> | 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.
ymm
carsxe ymm --year 2020 --make Toyota --model Camry --trim LE| 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) |
images — Vehicle Images
Retrieve photos of a vehicle by make, model, and year.
images
carsxe images --make Toyota --model Camry --year 2020 --angle front --size Large| Option | Required | Description |
|---|---|---|
--make <make> | Yes | Vehicle make |
--model <model> | Yes | Vehicle model |
--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 |
obd — OBD-II Code Decoder
Decode a diagnostic trouble code (DTC) from your OBD-II scanner.
obd
carsxe obd --code P0300| Option | Required | Description |
|---|---|---|
--code <code> | Yes | OBD-II code (e.g. P0300, C1234, B0001, U0100) |
config — Configuration
Manage your saved API key.
config
# 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-keyOutput FormatsCopy section for LLMCopy link to sectionAsk AI about this section
By default all commands return pretty-printed JSON. Two flags change the format:
Table view — human-friendly two-column layout, great for quick inspection:
--table
carsxe --table obd --code P0300Nested 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:
--raw
carsxe --raw specs --vin 1HGBH41JXMN109186