> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vrin.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Overview

> Install and use the VRIN CLI to query, insert, and manage your knowledge base from the terminal

The VRIN CLI lets you interact with your knowledge base directly from the terminal. It's designed for both humans and AI agents: human-readable output at a TTY, structured JSON when piped or called programmatically.

## Installation

<Tabs>
  <Tab title="pip (Python)">
    ```bash theme={null}
    pip install vrin
    ```

    Requires Python 3.9+. Installs the `vrin` command globally.
  </Tab>

  <Tab title="npm (Node.js)">
    ```bash theme={null}
    npm install -g @vrin/cli
    ```

    Wraps the Python CLI. Requires Python 3.9+ on the system.
  </Tab>

  <Tab title="curl (no install)">
    Use the [REST API](/api-reference/query) directly:

    ```bash theme={null}
    curl -X POST https://api.vrin.cloud/query \
      -H "Authorization: Bearer vrin_live_your_api_key" \
      -H "Content-Type: application/json" \
      -d '{"query": "What is ACME revenue?"}'
    ```
  </Tab>
</Tabs>

## Authentication

Set your API key as an environment variable:

```bash theme={null}
export VRIN_API_KEY=vrin_live_your_api_key
```

Or pass it inline per command:

```bash theme={null}
VRIN_API_KEY=vrin_... vrin query "What is ACME's revenue?"
```

Get an API key at [vrin.cloud](https://vrin.cloud), or create one from the CLI:

```bash theme={null}
vrin auth login you@example.com
vrin auth create-key --name "my-agent"
```

## Quick start

```bash theme={null}
# Insert knowledge
vrin insert "ACME Corp reported $50M revenue in Q4 2025" --title "ACME Q4"

# Query
vrin query "What is ACME's revenue?"

# Upload a file
vrin upload ./earnings_report.pdf

# Get raw facts (no AI summary)
vrin facts "ACME revenue"

# Stream a response
vrin query "Summarize ACME performance" --stream
```

## Output modes

The CLI automatically detects its environment:

| Context                    | Output format  | Example                    |
| -------------------------- | -------------- | -------------------------- |
| Interactive terminal (TTY) | Human-readable | `vrin query "..."`         |
| Piped / non-TTY            | JSON           | `vrin query "..." \| jq .` |
| `--json` flag              | JSON (forced)  | `vrin query "..." --json`  |
| `VRIN_OUTPUT=json` env var | JSON (forced)  | For agent environments     |

**JSON output format:**

```json theme={null}
// Success
{"ok": true, "data": {"summary": "...", "facts_count": 12, ...}}

// Error (always to stderr)
{"ok": false, "error": {"code": "auth_failed", "message": "Invalid API key"}}
```

## For AI agents

VRIN is built to be called by AI agents. Key patterns:

**1. Auto-discovery:** Run `vrin --describe` to get a machine-readable JSON schema of all commands, arguments, and flags. Point your agent here first.

```bash theme={null}
vrin --describe
```

**2. Always use `--json`** when invoking programmatically:

```bash theme={null}
vrin query "What is ACME's revenue?" --json
```

**3. Exit codes** map to error types:

| Code | Meaning               |
| ---- | --------------------- |
| 0    | Success               |
| 1    | General error         |
| 2    | Authentication failed |
| 3    | Rate limited          |
| 4    | Validation error      |
| 5    | Job failed            |
| 6    | Timeout               |
| 7    | Service unavailable   |

**4. Errors go to stderr**, data goes to stdout. Your agent can parse stdout for results and stderr for errors independently.

## Next steps

* [Query commands](/cli/querying) -- modes, depth levels, streaming, conversations
* [Knowledge commands](/cli/knowledge) -- insert, upload, bulk-insert, async jobs
* [Admin commands](/cli/admin) -- health, limits, specialization, graph
* [Auth commands](/cli/auth) -- login, register, API key management
* [Python SDK](/sdk/client) -- programmatic access from Python code
* [MCP Server](/mcp/overview) -- connect VRIN to Claude, Cursor, or any MCP-compatible agent
* [Vrin for AI Agents](/agents) -- the 3-minute agent-onboarding page