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:

1
{
2
  "api_key": "sk-...",
3
  "base_url": "https://api.airweave.ai",
4
  "collection": "my-default-collection"
5
}

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:

1
{
2
  "error": {
3
    "message": "Collection not found",
4
    "code": "not_found"
5
  }
6
}

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