Get started

CLI quickstart

Query aVenture from your terminal in four commands
View as Markdown

The CLI wraps the same API and the same credentials. Public reads work with no credential at all, so you can run a real query before you sign in.

The CLI requires Node.js 24.18 or later in the 24.x series. npm install fails on any other major version.

1

Install

npm install --global @aventurevc/aventure-cli --registry=https://registry.npmjs.org/

The binary is aventure.

2

Run a public read

No credential required:

aventure entities list --size 3

Companies, products, and services come back as a table. Add --json for the full envelope or --data for the response body alone.

3

Sign in

aventure auth login

This uses the OAuth device authorization grant: it prints a one-time code and a sign-in URL, opens a browser when one is available, and polls until you approve. The same command works on a laptop, over SSH, and inside a container — --no-browser only skips the automatic open.

The credential is stored in your operating-system keyring, or in ~/.config/aventure/credentials.json with mode 0600 when no GUI session makes a keyring available. Access tokens renew from the refresh token automatically.

Prefer a personal API key? aventure auth login --key creates and stores one through the same browser approval. An existing key can always be supplied through the AUTH_TOKEN environment variable instead — that is the path for CI and other non-interactive environments.

4

Verify

aventure auth doctor

doctor runs every environment check in one call and reports { ok, check: [...] } covering the CLI version, the installed schema contracts, the API host, which credential scope resolved locally, and whether the command catalog matches the operation set the API serves. It exits 0 only when no check failed; a skipped check does not fail the run, and each failing message names the command that fixes it.

aventure auth status is the narrower version — it reports credential provenance and sign-in providers, never the secret itself.

The command shape

entities, people, and news are the three record types, and each takes the same verbs, so learning one teaches the rest:

aventure entities list --size 3
aventure entities get --entity-slug calendly-atlanta-ga-us
aventure entities search --query "fintech companies in Austin" --size 3
aventure lookup --token e9TwndP056X3
VerbWhat it does
listRead many records, with --page and --size
searchFind many from a plain-English --query or a filter set
getRead one record
lookupResolve a name, URL, or domain to one record of that type

Each record type names its own slug flag — --entity-slug, --person-slug, --news-slug — so the flag tells you which record you are asking for:

aventure entities get --entity-slug calendly-atlanta-ga-us
aventure people   get --person-slug yin-wu
aventure news     get --news-slug 2026-09-16-pulley-a-carta-rival-is-shutting-down

Bare --slug on these commands is the request body field used by --batch, not the single-record selector. Passing it alone returns 400 or 422. Use the owner-qualified flag above for one record, and --batch --slug <slug> <slug> for many.

Add --batch to get or lookup to resolve many records in one request.

aventure search and aventure lookup are the cross-record versions: search runs companies, people, and news together, and lookup --token resolves any identifier — a public handle such as e9TwndP056X3, a UUID, a slug, or an external registry id like a ticker or EIN — to whichever record owns it.

The first two commands read public data with no credential. aventure lookup needs a credential, and aventure search and aventure entities search additionally need a Pro subscription or trial — without one they answer 402. Run aventure auth login first.

Output and exit codes

Each command accepts an output mode:

  • --text — the default in a terminal: a table for a list, labelled fields for one record
  • --data — the response data as JSON, the default when piped or non-TTY
  • --json — the full envelope, capped at 50KB
  • --data-full — uncapped JSON, for bounded programs

Exit code 0 means envelope.ok === true; 1 means the call failed. Scripts can branch on that without parsing output.

Find the command for an operation

aventure docs api prints what an operation needs without calling the API, so you can go from an API reference operationId to the command that runs it:

aventure docs api getEntityDetail
cli: aventure entities get
GET /v1/entities/detail
operationId: getEntityDetail
resource: entities
intent: read
scope: read
mutates: false
destructive: false
mcpTool: aventure_read
body: none
required path flags: none
required query flags: none

mcpTool names the MCP tool that reaches the same operation, and scope tells you whether a read or write credential is needed before you run it. --help on any command lists that command’s own flags, grouped by whether they land in the path, the query string, or the request body.

Next