CarsXE

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

# 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.

# 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:

carsxe login

Commands

Vehicle data

# 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

# 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

# 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

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:

FlagOutput
(default)Human-readable formatted output
--tableASCII table — good for quick comparison
--rawCompact JSON — pipe-friendly
# 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.

# 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:

# 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'