> ## 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.

# Query Commands

> Search your knowledge base and retrieve facts from the terminal

## vrin query

Query the knowledge base with natural language. VRIN retrieves relevant facts from your knowledge graph, combines them with matching document chunks, and generates a reasoned response.

```bash theme={null}
vrin query "What were ACME's key financial metrics in Q4?"
```

### Options

| Flag                     | Short | Default       | Description                                           |
| ------------------------ | ----- | ------------- | ----------------------------------------------------- |
| `--stream / --no-stream` |       | `--no-stream` | Stream tokens to stdout as they arrive                |
| `--mode`                 | `-m`  | `chat`        | Response mode: `chat`, `thinking`, `research`         |
| `--depth`                | `-d`  |               | Query depth: `basic`, `thinking`, `research`          |
| `--model`                |       |               | LLM model override (e.g., `claude-sonnet-4-20250514`) |
| `--session-id`           | `-s`  |               | Continue a conversation session                       |
| `--web-search`           |       | `false`       | Enable web search augmentation                        |
| `--json`                 |       |               | Force JSON output                                     |

### Response modes

<Tabs>
  <Tab title="chat">
    Default mode. Fast, conversational response.

    ```bash theme={null}
    vrin query "What is ACME's revenue?" --mode chat
    ```
  </Tab>

  <Tab title="thinking">
    Shows reasoning steps before the final answer. Good for complex questions.

    ```bash theme={null}
    vrin query "Compare ACME and Beta Corp revenue trends" --mode thinking
    ```
  </Tab>

  <Tab title="research">
    Exhaustive analysis with maximum retrieval depth. Uses more facts and chunks.

    ```bash theme={null}
    vrin query "What are the key risk factors across our portfolio?" --mode research
    ```
  </Tab>
</Tabs>

### Query depth

Controls how deeply VRIN searches your knowledge graph:

| Depth      | Behavior                                          | Best for                              |
| ---------- | ------------------------------------------------- | ------------------------------------- |
| `basic`    | Fast vector + graph retrieval                     | Simple factual lookups                |
| `thinking` | Cross-document analysis, multi-hop reasoning      | Questions connecting multiple sources |
| `research` | Exhaustive graph traversal, maximum fact coverage | Complex analytical queries            |

```bash theme={null}
vrin query "How do risk factors in our Q3 and Q4 reports compare?" --depth research
```

### Streaming

Stream tokens to stdout as they arrive. Metadata is written to stderr after streaming completes.

```bash theme={null}
vrin query "Summarize our competitive position" --stream
```

With `--json`, the full response is buffered and output as JSON after streaming completes:

```bash theme={null}
vrin query "Summarize our competitive position" --stream --json
```

### Conversations

Continue a multi-turn conversation by passing a session ID:

```bash theme={null}
# Start a conversation
vrin query "What was ACME's Q4 revenue?" --json
# Response includes session_id

# Continue it
vrin query "How does that compare to Q3?" --session-id "sess_abc123"
```

See [conversation commands](/cli/conversations) for managing conversation history.

***

## vrin facts

Fast fact retrieval without AI summary generation. Returns raw structured facts from the knowledge graph. Useful for quick lookups or when you want to process facts programmatically.

```bash theme={null}
vrin facts "ACME revenue"
```

### Options

| Flag     | Description       |
| -------- | ----------------- |
| `--json` | Force JSON output |

### Example output (JSON)

```bash theme={null}
vrin facts "ACME revenue" --json
```

```json theme={null}
{
  "ok": true,
  "data": {
    "facts": [
      {
        "subject": "ACME Corp",
        "predicate": "reported_revenue",
        "object": "$50M in Q4 2025",
        "confidence": 0.95,
        "source": "ACME Q4 2025 Earnings"
      }
    ],
    "count": 1
  }
}
```