Vainu CLI

The Vainu CLI (`vainu-cli`) is a Python package that wraps the Vainu REST API. It gives you a `vainu` terminal command and an importable `vainu_cli` library, and it handles authentication, token refresh, async job polling, and streaming on your behalf.

The CLI is the right tool when you need:

For one-off lookups and ad-hoc analysis, the Vainu MCP connector requires no setup and is usually faster to reach an answer. For integrations written outside Python, call the REST API directly.

Run the installer for your operating system.

macOS and Linux

Windows (PowerShell)

The installer uses uv and places the `vainu` command in `~/.local/bin` on macOS and Linux, or `%USERPROFILE%\.local\bin` on Windows.

If you manage your own Python environment, `pip install vainu-cli` works as well. Use version `0.1.1` or later.

⚠️ Warning: Your shell caches command locations for the duration of a session. Open a new terminal window after installing, or the `vainu` command will not be found.

If the browser does not open, run `vainu login --no-browser` and open the URL printed in the terminal.

The CLI supports three credential types. `vainu login` stores a cached token and has the same effect as OAuth or JWT credentials.

⚠️ Warning: Access is gated by capability, not only by account. A static API key reaches `companies` and `organizations` and nothing else. The `signals-news`, `signals-data-changes`, `lists`, and `enrichment-agent` commands require OAuth, JWT, or `vainu login`. With an API key alone, these commands fail with a generic authentication error rather than a message about scope.

OAuth tokens are fetched and refreshed for you. The cache lives in your operating system keyring — Keychain, Secret Service, or Credential Locker — and falls back to a `0600` file in your user config directory when no keyring backend is available.

Cache entries are keyed by base URL, client ID, and scope, so credentials for several environments coexist without conflicting. A token rejected with a `401` is discarded and the request is retried once. Repeated `401` responses point to a bad credential rather than an expired cache entry.

To clear cached tokens, run `vainu auth logout`.

Look up a single company by business ID:

Browse the field catalog to find valid field paths:

💡 Tip: `vainu fields organizations` is the only source of truth for valid field paths. There is no static field list, and the available fields vary by country and by the entitlements on your account.

Count matches before you export, so you know how large the result set is:

Export a large result set, streamed to a file as it arrives:

ℹ️ Note: The `jsonl` and `csv` formats stream by default, writing each line as it arrives. The `json` format never streams, because the document is not valid until the last byte. Combining `--stream` with `--format json` returns an error.

Run `vainu --help`, or `vainu COMMAND --help`, for the full list of commands and flags.

⚠️ Warning: Data retrieved through the CLI carries the same restrictions as all Vainu data. Do not use it to train, fine-tune, evaluate, or improve AI or machine-learning models, and do not use it to populate vector databases or retrieval-augmented generation systems. These restrictions also cover AI-generated output derived from Vainu data.