CLI

The Airweave CLI lets you interact with your collections from the command line. It’s designed for both developers and AI agents: interactive mode gives you rich output with spinners and prompts, while piped or non-TTY mode outputs clean JSON for scripting.

Installation

pip install airweave-cli

Verify the installation:

airweave --version

Authentication

Before using the CLI, authenticate with your Airweave account. There are two methods: browser-based login (OAuth) and API key.

Browser login

airweave auth login

This opens a browser window where you sign in via Auth0. The CLI stores the access token and organization ID in ~/.airweave/config.json.

API key login

airweave auth login --api-key

You’ll be prompted for your API key, base URL, and an optional default collection. The key is validated before being saved.

Check auth status

airweave auth status

Log out

airweave auth logout

Searching

The primary use case — search any collection from your terminal:

airweave search "quarterly revenue figures" --collection finance-data

If you’ve set a default collection (via login or environment variable), you can omit --collection:

airweave search "how does authentication work?"

Search modes

The CLI supports three search modes:

# Fast vector search
airweave search "error logs" --mode instant
# Keyword search for exact terms
airweave search "ERR-4032" --mode instant --strategy keyword
# AI-planned search (default)
airweave search "how does authentication work?"
# Agentic search — the agent reasons over your data
airweave search "summarize Q4 decisions" --mode agentic
# Agentic with extended thinking
airweave search "compare our auth design with the RFC" --mode agentic --thinking

Agentic search uses a streaming connection and shows real-time progress as the agent works:

  ▶ Search started
  ◆ Thinking (iter 1) (2340ms): Analyzing query...
  ⚡ Tool: search (iter 1) (890ms)
  ◆ Thinking (iter 2) (1560ms): Evaluating results...
  ⇅ Reranking: 25 → 10 results (320ms)
  ✔ Done — 10 results (8432ms)

Filtering

Use --filter to narrow results by source, entity type, date, or other fields:

# Filter to a specific source
airweave search "bugs" --filter '{"conditions": [
  {"field": "airweave_system_metadata.source_name", "operator": "equals", "value": "jira"}
]}'
# Filter by date
airweave search "updates" --filter '{"conditions": [
  {"field": "created_at", "operator": "greater_than", "value": "2026-01-01T00:00:00Z"}
]}'

Filterable fields include entity_id, name, created_at, updated_at, breadcrumbs.name, airweave_system_metadata.source_name, airweave_system_metadata.entity_type, and more. Operators: equals, not_equals, contains, in, not_in, greater_than, less_than, etc. Conditions within a group are AND’d; multiple groups are OR’d.

Piping results

When stdout is not a TTY (e.g. piped to another command), the CLI automatically outputs JSON:

airweave search "refund policy" | jq -r '.results[0].textual_representation'

You can also force JSON output in interactive mode:

airweave search "deploy steps" --json | jq '.results[0]'

Collections

List collections

airweave collections list

Create a collection

airweave collections create --name "My Data" --readable-id my-data

Get collection details

airweave collections get my-data-x7k9m

Sources

List source connections

airweave sources list --collection my-data

Add a source connection

airweave sources add slack --collection my-data --name "Team Slack"

Trigger a sync

airweave sources sync <source-connection-id>

Use --force for a full re-sync instead of incremental:

airweave sources sync <source-connection-id> --force

Global flags

These flags work with any command:

Configuration

The CLI resolves configuration in this order: CLI flags → environment variables → config file → defaults.

Environment variables

Config file

Stored at ~/.airweave/config.json:

{
  "api_key": "sk-...",
  "base_url": "https://api.airweave.ai",
  "collection": "my-default-collection"
}

Self-hosted instances

Point the CLI at your own Airweave deployment:

airweave auth login --api-key --base-url https://your-airweave-instance.com

Or set the environment variable:

export AIRWEAVE_BASE_URL="https://your-airweave-instance.com"

For custom Auth0 configurations, set these additional variables:

Output behavior

The CLI adapts its output based on context:

Errors always go to stderr. In JSON mode, errors are formatted as:

{
  "error": {
    "message": "Collection not found",
    "code": "not_found"
  }
}

Exit codes: 0 for success, 1 for failure.

Command reference

airweave [--version] [--json] [--quiet] <command>
Commands:
  search          Search a collection (instant, classic, or agentic)
  auth            Authentication management
    login         Authenticate (browser or API key)
    status        Print current auth state
    logout        Clear stored credentials
  collections     Collection management
    list          List all collections
    create        Create a new collection
    get           Get collection details
  sources         Source connection management
    list          List source connections
    add           Add a new source connection
    sync          Trigger a sync