Auto.dev CLI Setup

Purpose

Install, authenticate, and verify the @auto.dev/sdk npm package so a downstream agent can run any Auto.dev automotive data task — VIN decode, photos, listings search, specs, OEM build data, recalls (safety + open), monthly payment / APR / TCO calculations, license-plate-to-VIN, taxes & fees, and account usage — via the global auto CLI binary, the bundled stdio MCP server, or the JS/TS SDK. Read-only against Auto.dev's API surface; the CLI does not mutate vehicle records — it only fetches data and writes local config to ~/.auto-dev/config.json.

When to Use

An agent needs to pull automotive data once or repeatedly from Auto.dev and you want to avoid hand-rolling HTTP requests against api.auto.dev.
The calling agent is an MCP-capable client (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code Copilot) and the cleanest path is to register Auto.dev as a tool provider so the model can call auto_decode, auto_listings, etc. natively.
A CI job or headless runtime needs Auto.dev data via shell — AUTODEV_API_KEY + auto <command> is the lowest-overhead integration.
Code-generation contexts where you want the agent to emit TypeScript that imports @auto.dev/sdk and calls auto.decode(...) / auto.listings(...) against the same auth.

Workflow

The fastest reliable setup for a non-interactive agent is (1) global install of @auto.dev/sdk from npm, (2) auth via the AUTODEV_API_KEY environment variable (the browser-based auto login OAuth flow does not work headless), and (3) smoke-test with auto whoami + a free-tier call like auto decode 1HGCM82633A004352 --json. If the agent is running inside an MCP-capable host (Claude Code / Desktop, Cursor, Windsurf, VS Code Copilot), run npx @auto.dev/sdk mcp install afterward — it edits the host's MCP config file in place so the model can call auto_* tools without shelling out. The bare HTTP API at https://api.auto.dev is the lowest-level fallback if npm is unavailable, but you lose the CLI's response-stripping, plan-tier guards, parameter shorthand, and offline explore/docs introspection.

Verify prerequisites. node --version must be >= 18.0.0 (the package's engines field; verified against 0.1.23). npm ≥ 8 is fine.

Install globally. Use npm i -g, not npx, so the auto binary is on $PATH for follow-up calls in the same session:

npm install -g @auto.dev/sdk
auto --version    # → 0.1.23 (or newer)

In sandboxed environments without root, fall back to a project-local install + the node_modules/.bin/auto shim:

mkdir -p /tmp/autodev && cd /tmp/autodev && npm init -y >/dev/null && \
  npm install --no-audit --no-fund @auto.dev/sdk
alias auto="$PWD/node_modules/.bin/auto"

Authenticate. Three options, in order of preference for an agent:
- AUTODEV_API_KEY env var (preferred for headless / CI). Get a key from https://auto.dev/dashboard → API Keys → Create New Key. Format starts with sk_ad_. Export it for the session:
```
export AUTODEV_API_KEY=sk_ad_...
```
  The CLI, SDK, and stdio MCP server all read this variable. No auto login step needed.
- --api-key <key> flag. Per-invocation override, useful when juggling multiple Auto.dev accounts or for one-off tests:
```
auto decode 1HGCM82633A004352 --api-key sk_ad_...
```
- auto login (interactive only). Opens a browser tab at id.org.ai for OAuth. Stores refresh tokens in ~/.auto-dev/config.json. Do not invoke this from a headless agent — it will block waiting for a browser callback that never arrives. There is no auto login --device-code flow at v0.1.23.
Smoke-test. Three offline-friendly probes confirm install + auth without burning API quota:
```
auto --version              # confirms the binary resolves
auto explore                # offline; prints the endpoint table by plan tier
auto config list            # offline; reads ~/.auto-dev/config.json
```
Then one live call against the free-tier VIN-decode endpoint to confirm auth works end-to-end:
```
auto decode 1HGCM82633A004352 --json | head -20
```
A successful response prints stripped vehicle data (make/model/year/trim/engine). A No API key found. Set AUTODEV_API_KEY or run: auto login error means step 3 didn't take. A 401/403 means the key is invalid or the account is suspended.
(Optional) Install the MCP server into the host agent. If the calling agent is one of the supported MCP clients, run:
```
auto mcp install            # or: npx @auto.dev/sdk mcp install
auto mcp status             # verify which clients are configured
```
This writes to the appropriate config file(s):
- Claude Code — ~/.claude.json
- Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
- Cursor — ~/.cursor/mcp.json
Manual MCP config (equivalent):
```
{ "mcpServers": { "auto-dev": { "command": "auto", "args": ["--mcp"] } } }
```
For remote MCP (hosted, OAuth-only — useful for Claude Desktop without a local Node install), point the client at https://mcp.auto.dev/mcp instead. Both transports expose the same auto_* tool set.

Drive the API. With auth configured, the agent invokes one command per task. Each subcommand accepts --json, --yaml, --table (default), and --raw (un-strips API metadata).

auto decode <vin>                            # Starter plan
auto photos <vin>                            # Starter
auto listings --make Toyota --year 2024 --price 10000-40000 --state CA   # Starter
auto specs <vin>                             # Growth
auto build <vin>                             # Growth
auto recalls <vin>                           # Growth
auto payments <vin> --price 35000 --zip 90210 --down-payment 5000        # Growth
auto apr <vin> --year 2024 --make Honda --model Accord --zip 90210 --credit-score 750   # Growth
auto tco <vin> --zip 90210                   # Growth
auto open-recalls <vin>                      # Scale
auto plate <state-code> <plate>              # Scale  e.g. auto plate CA ABC1234
auto taxes <vin> --price 35000 --zip 90210   # Scale
auto usage                                   # any plan

For discoverability mid-task: auto explore lists every endpoint by tier; auto explore listings shows each filter, whether it's required, and the underlying API field it maps to (e.g. --make → vehicle.make). auto docs <name> browses bundled documentation when it's been built; on a fresh global install it may print No bundled docs found — fall back to the hosted docs at https://docs.auto.dev/v2/products/.

(Optional) Code-generation path with the SDK. When the downstream task wants TypeScript instead of shell, import directly:
```
import { AutoDev } from '@auto.dev/sdk'
const auto = new AutoDev({ apiKey: process.env.AUTODEV_API_KEY })
const { data, meta } = await auto.decode('1HGCM82633A004352')
// data = stripped vehicle object; meta = { requestId, tier, usage: { remaining } }
// Pass { raw: true } on the constructor to disable stripping globally.
```
Filter-style methods take an object whose keys are the full API field names ('vehicle.make', 'retailListing.price', etc.) — the CLI shorthand (--make) is a CLI-layer convenience only; the SDK does not rewrite keys. Run auto explore listings to see the shorthand-to-field mapping before authoring an SDK call.
(Optional, fallback) Bare HTTP API. If npm is unavailable:
```
curl -H "Authorization: Bearer $AUTODEV_API_KEY" \
     https://api.auto.dev/vin/1FTFW3LDXRFB40317
```
You lose all CLI conveniences. Note that the bare API response includes the api/links/user/examples/discover/actions metadata that the CLI strips by default — equivalent to --raw.

Site-Specific Gotchas

Browser-based auto login blocks headless agents. It launches a system browser to id.org.ai and waits for an OAuth callback. There is no device-code or copy-paste-token variant in v0.1.23. For any non-interactive runtime, use AUTODEV_API_KEY (env var) or --api-key <key> (per-call). The error path when nothing is set is explicit: No API key found. Set AUTODEV_API_KEY or run: auto login.
Plan-tier gating is enforced server-side, not client-side. auto explore cheerfully prints every endpoint regardless of plan, but a call to a higher-tier endpoint on a Starter account returns an error from the API, not from the CLI. Tier mapping at the time of writing: Starter = decode, photos, listings (1,000 calls/mo free); Growth = +specs, build, recalls, payments, apr, tco ($299/mo, 14-day trial); Scale = +open-recalls, plate, taxes ($599/mo). auto usage reports remaining-call counts; agents should check it before bulk loops.
Rate limits by plan: Starter 5 req/s, Growth 10 req/s, Scale 50 req/s. The CLI does not back-off automatically — an agent looping over a list of VINs must throttle itself.
Response stripping is on by default. auto decode <vin> returns clean vehicle fields; the API's api/links/user/examples/discover/actions envelope is dropped. Pass --raw (CLI) or new AutoDev({ raw: true }) (SDK) when you need the metadata — e.g. for HATEOAS link traversal or quota inspection from a single call. auto config set raw true flips the default persistently in ~/.auto-dev/config.json, which is shared across CLI, SDK, and stdio MCP.
SDK response envelope is { data, meta } — not the bare object. Forgetting to destructure is the most common SDK foot-gun. meta.usage.remaining is the canonical place to read quota.
CLI shorthand ≠ SDK keys. auto listings --make Toyota works; auto.listings({ make: 'Toyota' }) does not — the SDK requires the full dotted path { 'vehicle.make': 'Toyota' }. Use auto explore <endpoint> to see the mapping table.
auto docs ships empty on the npm tarball. On a fresh npm i -g @auto.dev/sdk@0.1.23, auto docs and auto docs <query> print No bundled docs found · Run: npm run build:docs — the build step only runs in the package's source repo. Treat the hosted docs at https://docs.auto.dev/v2/products/ as the source of truth for endpoint reference. auto explore <endpoint> still works offline and is the next-best discoverability tool.
MCP install rewrites config files in place. auto mcp install mutates ~/.claude.json, ~/.cursor/mcp.json, etc. without dry-run or backup. Diff the file before/after if the host config is hand-maintained. auto mcp uninstall reverses it.
Two MCP transports, same tools, different auth. Local stdio (auto --mcp invoked by the host) inherits AUTODEV_API_KEY from the host's env or ~/.auto-dev/config.json from auto login. Remote (https://mcp.auto.dev/mcp) does its own OAuth at id.org.ai on first tool call — no env var needed, but the user must complete a browser flow once. For shared/CI Claude Code installs, prefer local stdio with AUTODEV_API_KEY.
Plate lookup needs a US state code, not name. auto plate California ABC1234 will fail; auto plate CA ABC1234 works. State codes are 2-letter USPS abbreviations.
VIN format is not validated client-side. The CLI passes the VIN straight to the API. A malformed 17-char VIN (or one with I/O/Q, which never appear in real VINs) returns a 4xx from the API, not a friendly local error.
No retries on transient errors. A 5xx or a connection reset bubbles up immediately; wrap calls in your own retry loop if reliability matters. The Node fetch underneath surfaces getaddrinfo ENOTFOUND api.auto.dev if your runtime has no egress to that host — relevant in restricted sandboxes.
npx @auto.dev/sdk mcp install is the documented one-shot, but it installs a per-run binary, not a global one. If the agent will run more than one auto command in the same session, prefer the explicit two-step (npm i -g @auto.dev/sdk then auto mcp install) so subsequent shell calls don't have to re-fetch the package each time.
Config lives at ~/.auto-dev/config.json and is shared. Editing it (or running auto config set <k> <v>) affects every later auto, AutoDev SDK import, and stdio MCP invocation under the same $HOME. Multi-tenant setups should pass --api-key per call instead of relying on the file.

Expected Output

The skill's "output" is a verified-working install. The agent should observe each of these in order — the JSON example at the end is what a downstream automotive-data task will then see:

# Step 2 verification
$ auto --version
0.1.23

# Step 4 offline smoke-tests (no API call)
$ auto explore | head -3
[STARTER]
  decode           /vin/{vin}                    Decode a VIN — returns make, model, year, trim, engine, drivetrain
  photos           /photos/{vin}                 Get vehicle photos by VIN

$ auto config list
(empty on a fresh install; or printed key/value pairs after `auto config set`)

// Step 4 live VIN-decode response (auto decode 1HGCM82633A004352 --json),
// with default response-stripping on. Shape is approximate — fields vary by VIN.
{
  "vin": "1HGCM82633A004352",
  "year": 2003,
  "make": "Honda",
  "model": "Accord",
  "trim": "EX",
  "bodyStyle": "Coupe",
  "engine": { "displacement": "3.0L", "cylinders": 6, "fuelType": "Gasoline" },
  "drivetrain": "FWD",
  "transmission": "Automatic"
}

// MCP-installed state (after step 5). `auto mcp status` prints a tick per
// detected client, e.g.:
//   ✔ Claude Code        installed
//   ✔ Cursor             installed
//   ✖ Claude Desktop     not installed
//
// The relevant section of the host's MCP config file:
{
  "mcpServers": {
    "auto-dev": {
      "command": "auto",
      "args": ["--mcp"]
    }
  }
}

// SDK-style envelope (step 7). All SDK methods return this shape.
{
  "data": { "vin": "1HGCM82633A004352", "year": 2003, "make": "Honda", ... },
  "meta": {
    "requestId": "req_01HXYZ...",
    "tier": "starter",
    "usage": { "remaining": 998 }
  }
}

// Failure shapes the calling agent should branch on:
// 1. Missing/unset auth:
Error: No API key found. Set AUTODEV_API_KEY or run: auto login

// 2. Invalid key:
HTTP 401 Unauthorized  (body: { "error": "invalid_api_key" })

// 3. Plan-tier denied (e.g. `auto specs` on Starter):
HTTP 403 Forbidden     (body: { "error": "plan_required", "required": "growth" })

// 4. Quota exhausted:
HTTP 429 Too Many Requests   (body: { "error": "rate_limited" } or { "error": "monthly_quota_exceeded" })

// 5. Network/runtime can't reach api.auto.dev (sandboxed egress):
TypeError: fetch failed
  cause: Error: getaddrinfo ENOTFOUND api.auto.dev