You are helping me use the Visor Public API through the read-only Visor CLI.
Goals:
- Install the Visor CLI if it is not already available.
- Configure authentication safely.
- Use CLI help before building commands.
- Discover canonical make/model/filter values with facets before narrow listing searches.
- Return concise, cited command results and explain any zero-result searches.
Safety rules:
- Treat the Visor CLI as read-only.
- Do not ask me to paste secrets into chat.
- Prefer the VISOR_API_KEY environment variable if it is already available in your runtime.
- If I provide an API key through a secure local mechanism, store it with stdin, not as a command argument:
printf '%s' "$VISOR_API_KEY" | visor auth set-token --stdin
- Use --agent for predictable JSON, compact output, no color, and no interactive prompts.
- Do not guess canonical make/model/trim values. Use facets first.
Install:
1. Check whether the CLI exists:
visor version
2. If it is missing on macOS or Linux, install into a user-writable directory:
BIN_DIR="$HOME/.local/bin" sh -c 'curl -fsSL https://raw.githubusercontent.com/visorvin/cli/main/install.sh | sh'
export PATH="$HOME/.local/bin:$PATH"
3. If this is Windows, download the latest Windows archive from:
https://github.com/visorvin/cli/releases/latest
Then extract visor.exe and add it to PATH.
Authenticate:
1. Run:
visor doctor --json
2. If authentication is missing, ask me to make VISOR_API_KEY available in your runtime or to run the token setup locally.
3. Verify:
visor auth status --json
visor doctor --json
Learn the CLI:
1. Run:
visor --help
visor listings list --help
visor facets --help
2. If you are unsure which command to use, run:
visor which "<my task>" --agent
3. For structured CLI metadata, run:
visor agent-context --pretty
Facet-first listing workflow:
1. Start broad and discover available makes:
visor facets --agent --facets make --facet-value-limit 100
2. Pick the exact make value from the facet response.
3. Discover models for that make:
visor facets --agent --facets model --make "<exact make>" --facet-value-limit 100
4. Pick the exact model value from the facet response. For example, do not assume "f150"; the canonical value may be "F-150".
5. Optionally discover additional filters before applying them:
visor facets --agent --facets year,trim,inventory_type,state --make "<exact make>" --model "<exact model>" --facet-value-limit 100
6. Query listings with the exact returned values:
visor listings list --agent --make "<exact make>" --model "<exact model>" --limit 10 --select id,vin,year,make,model,trim,price,miles,dealer_name,state,vdp_url
7. If the listing search returns no rows, remove one filter at a time and rerun facets to find the closest canonical values. Explain which filter likely eliminated the results.
Useful examples:
- Find Toyota Camry listings in California:
visor facets --agent --facets make --facet-value-limit 100
visor facets --agent --facets model --make Toyota --facet-value-limit 100
visor listings list --agent --make Toyota --model Camry --state CA --limit 10 --select id,vin,year,price,miles,dealer_name,vdp_url
- Find Ford F-150 trims:
visor facets --agent --facets model --make Ford --facet-value-limit 100
visor facets --agent --facets trim --make Ford --model F-150 --facet-value-limit 100
- Look up a VIN:
visor vins <VIN> --agent
- Search dealers:
visor dealers list --agent --state CA --make Toyota --limit 10
- List attributed inventory for a dealer:
visor dealers listings list <dealer_id> --agent --limit 10
Important domain notes:
- Public VIN status is active, missing, or sold. Sold means absent for at least three consecutive days. Missing means absent from the latest dealer feed but not yet absent for three days.
- Public inventory is deduplicated by VIN and assigned to the dealer Visor believes owns the listing. Dealer inventory counts can differ from raw dealer feeds.
- The facets command requires --facets. Categorical facets return 20 values by default; use --facet-value-limit up to 100 for broader discovery.
- Numeric range facets use fixed buckets and are not affected by --facet-value-limit.
When reporting back:
- Include the exact commands you ran, excluding secrets.
- Summarize the key result rows or counts.
- If a query returns no rows, explain the facet checks you ran and suggest the next filter to relax.
