> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/volcengine/OpenViking/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Usage

> Complete command-line interface guide for OpenViking with all commands and examples

The OpenViking CLI (`ov`) provides a powerful command-line interface for managing resources, searching, and interacting with OpenViking.

## Installation

<Tabs>
  <Tab title="Quick Install (Linux/macOS)">
    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/crates/ov_cli/install.sh | bash
    ```
  </Tab>

  <Tab title="From Source">
    ```bash theme={null}
    # Requires Rust >= 1.88
    cargo install --path crates/ov_cli
    ```
  </Tab>

  <Tab title="Via Python Package">
    ```bash theme={null}
    pip install openviking
    # CLI binary is bundled in the wheel
    ```
  </Tab>
</Tabs>

## Configuration

Create `~/.openviking/ovcli.conf`:

```json theme={null}
{
  "url": "http://localhost:1933",
  "api_key": "your-api-key",
  "agent_id": "my-agent",
  "timeout": 60.0,
  "output": "table",
  "echo_command": true
}
```

| Field          | Description                          | Default    |
| -------------- | ------------------------------------ | ---------- |
| `url`          | Server URL                           | (required) |
| `api_key`      | API key for authentication           | `null`     |
| `agent_id`     | Agent identifier                     | `null`     |
| `timeout`      | Request timeout in seconds           | `60.0`     |
| `output`       | Output format: `"table"` or `"json"` | `"table"`  |
| `echo_command` | Echo command before execution        | `true`     |

<Tip>
  You can also set `OPENVIKING_CLI_CONFIG_FILE` environment variable to use a custom config path.
</Tip>

## Quick Start

```bash theme={null}
# Add a resource
ov add-resource https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/docs/en/about/01-about-us.md --wait

# List contents
ov ls viking://resources

# Semantic search
ov find "what is openviking"

# Get file tree
ov tree viking://resources

# Read content
ov read viking://resources/...
```

## Global Options

These options work with all commands:

```bash theme={null}
ov [OPTIONS] <COMMAND>
```

| Option              | Description                      |
| ------------------- | -------------------------------- |
| `--output <FORMAT>` | Output format: `table` or `json` |
| `-o <FORMAT>`       | Short form of `--output`         |
| `--help`            | Show help information            |
| `--version`         | Show version                     |

**Examples:**

```bash theme={null}
# JSON output
ov --output json ls viking://
ov -o json ls viking://

# Table output (default)
ov --output table ls viking://
```

## Resource Management

### add-resource

Add a local file, directory, or URL to OpenViking.

```bash theme={null}
ov add-resource <PATH> [OPTIONS]
```

**Options:**

| Option                 | Description                              |
| ---------------------- | ---------------------------------------- |
| `--target <URI>`       | Target path in VikingFS                  |
| `--reason <TEXT>`      | Context/reason for adding                |
| `--instruction <TEXT>` | Processing instruction                   |
| `--wait`               | Wait for processing to complete          |
| `--timeout <SECONDS>`  | Wait timeout (default: 300)              |
| `--no-index`           | Skip vector indexing                     |
| `--summarize`          | Generate summary                         |
| `--ignore-dirs <DIRS>` | Comma-separated dirs to ignore           |
| `--exclude <PATTERNS>` | Comma-separated file patterns to exclude |

<Accordion title="Examples">
  ```bash theme={null}
  # Add URL and wait
  ov add-resource https://example.com/docs --wait --timeout 60

  # Add local file
  ov add-resource ./README.md --reason "Project documentation"

  # Add directory with filters
  ov add-resource ./project \
    --wait \
    --timeout 600 \
    --ignore-dirs "node_modules,.git" \
    --exclude "*.log,*.tmp"

  # Add to specific target
  ov add-resource ./docs \
    --target "kb/project-docs" \
    --wait
  ```
</Accordion>

### add-skill

Add a skill to OpenViking.

```bash theme={null}
ov add-skill <DATA> [OPTIONS]
```

**Options:**

* `--wait` - Wait for processing
* `--timeout <SECONDS>` - Wait timeout

### export

Export resource as .ovpack file.

```bash theme={null}
ov export <URI> --to <PATH>
```

**Example:**

```bash theme={null}
ov export viking://resources/docs --to ./backup/docs.ovpack
```

### import

Import .ovpack file.

```bash theme={null}
ov import <FILE> --target <URI> [OPTIONS]
```

**Options:**

* `--force` - Overwrite existing resources
* `--no-vectorize` - Skip vectorization

**Example:**

```bash theme={null}
ov import ./backup/docs.ovpack --target viking://resources/restored
```

## File System Operations

### ls

List directory contents.

```bash theme={null}
ov ls <URI> [OPTIONS]
```

**Options:**

| Option        | Description      |
| ------------- | ---------------- |
| `--simple`    | Show only paths  |
| `--recursive` | List recursively |

<Accordion title="Examples">
  ```bash theme={null}
  # Basic listing
  ov ls viking://resources

  # Simple mode (paths only)
  ov ls viking://resources --simple

  # Recursive
  ov ls viking://resources --recursive

  # JSON output
  ov -o json ls viking://resources
  ```
</Accordion>

### tree

Get directory tree structure.

```bash theme={null}
ov tree <URI>
```

**Example:**

```bash theme={null}
ov tree viking://resources
ov tree viking://resources/docs
```

### mkdir

Create a directory.

```bash theme={null}
ov mkdir <URI>
```

**Example:**

```bash theme={null}
ov mkdir viking://resources/new-folder
```

### rm

Remove a resource.

```bash theme={null}
ov rm <URI> [OPTIONS]
```

**Options:**

* `--recursive` - Remove directory recursively

<Accordion title="Examples">
  ```bash theme={null}
  # Delete file
  ov rm viking://resources/example.md

  # Delete directory
  ov rm viking://resources/old-docs --recursive
  ```
</Accordion>

### mv

Move or rename a resource.

```bash theme={null}
ov mv <FROM_URI> <TO_URI>
```

**Example:**

```bash theme={null}
ov mv viking://resources/old.md viking://resources/new.md
```

### stat

Get resource metadata.

```bash theme={null}
ov stat <URI>
```

**Example:**

```bash theme={null}
ov stat viking://resources/example.md
```

## Content Access

### read

Read L2 (full content).

```bash theme={null}
ov read <URI> [OPTIONS]
```

**Options:**

* `--offset <N>` - Start at line N
* `--limit <N>` - Read N lines

<Accordion title="Examples">
  ```bash theme={null}
  # Read entire file
  ov read viking://resources/example.md

  # Read with pagination
  ov read viking://resources/large.txt --offset 0 --limit 100
  ```
</Accordion>

### abstract

Read L0 abstract (\~100 token summary).

```bash theme={null}
ov abstract <URI>
```

**Example:**

```bash theme={null}
ov abstract viking://resources/docs
```

### overview

Read L1 overview (\~2k token overview).

```bash theme={null}
ov overview <URI>
```

**Example:**

```bash theme={null}
ov overview viking://resources/docs
```

## Search Operations

### find

Semantic search (quick retrieval).

```bash theme={null}
ov find <QUERY> [OPTIONS]
```

**Options:**

| Option                | Description               |
| --------------------- | ------------------------- |
| `--target <URI>`      | Scope to directory        |
| `--limit <N>`         | Max results (default: 10) |
| `--threshold <FLOAT>` | Minimum score (0.0-1.0)   |

<Accordion title="Examples">
  ```bash theme={null}
  # Basic search
  ov find "how to deploy openviking"

  # With filters
  ov find "authentication guide" \
    --target viking://resources/docs \
    --limit 5 \
    --threshold 0.7

  # JSON output for scripting
  ov -o json find "installation steps" | jq '.result.resources[].uri'
  ```
</Accordion>

### search

Context-aware search with session.

```bash theme={null}
ov search <QUERY> [OPTIONS]
```

**Options:**

* `--session-id <ID>` - Use session context
* `--target <URI>` - Scope to directory
* `--limit <N>` - Max results
* `--threshold <FLOAT>` - Minimum score

**Example:**

```bash theme={null}
# Create session first
SESSION=$(ov -o json session new | jq -r '.result.session_id')

# Add context
ov session add-message --session-id $SESSION --role user --content "Tell me about OpenViking"

# Context-aware search
ov search "how to use it" --session-id $SESSION
```

### grep

Content pattern search (regex).

```bash theme={null}
ov grep <URI> <PATTERN> [OPTIONS]
```

**Options:**

* `--case-insensitive` - Case-insensitive search

<Accordion title="Examples">
  ```bash theme={null}
  # Case-sensitive
  ov grep viking://resources "OpenViking"

  # Case-insensitive
  ov grep viking://resources "openviking" --case-insensitive

  # Search in specific directory
  ov grep viking://resources/docs "API"
  ```
</Accordion>

### glob

File pattern matching.

```bash theme={null}
ov glob <PATTERN> [OPTIONS]
```

**Options:**

* `--uri <URI>` - Root URI (default: `viking://`)

<Accordion title="Examples">
  ```bash theme={null}
  # Find all markdown files
  ov glob "**/*.md"

  # Find in specific directory
  ov glob "**/*.py" --uri viking://resources/code

  # Find config files
  ov glob "**/config*.json"
  ```
</Accordion>

## Session Management

### session new

Create a new session.

```bash theme={null}
ov session new
```

**Example:**

```bash theme={null}
# Create and capture ID
SESSION=$(ov -o json session new | jq -r '.result.session_id')
echo $SESSION
```

### session list

List all sessions.

```bash theme={null}
ov session list
```

### session get

Get session details.

```bash theme={null}
ov session get <SESSION_ID>
```

**Example:**

```bash theme={null}
ov session get abc123
```

### session delete

Delete a session.

```bash theme={null}
ov session delete <SESSION_ID>
```

**Example:**

```bash theme={null}
ov session delete abc123
```

### session add-message

Add message to session.

```bash theme={null}
ov session add-message [OPTIONS]
```

**Options:**

| Option              | Description                                    |
| ------------------- | ---------------------------------------------- |
| `--session-id <ID>` | Session ID (required)                          |
| `--role <ROLE>`     | Message role: `user` or `assistant` (required) |
| `--content <TEXT>`  | Message content (required)                     |

**Example:**

```bash theme={null}
ov session add-message \
  --session-id $SESSION \
  --role user \
  --content "Hello, OpenViking!"
```

### session commit

Commit session (archive and extract memories).

```bash theme={null}
ov session commit <SESSION_ID>
```

**Example:**

```bash theme={null}
ov session commit $SESSION
```

## Relations

### relations

List relations for a resource.

```bash theme={null}
ov relations <URI>
```

**Example:**

```bash theme={null}
ov relations viking://resources/doc.md
```

### link

Create relation link.

```bash theme={null}
ov link <FROM_URI> <TO_URI> [OPTIONS]
```

**Options:**

* `--reason <TEXT>` - Reason for linking

**Example:**

```bash theme={null}
ov link \
  viking://resources/doc1.md \
  viking://resources/doc2.md \
  --reason "Related documentation"
```

### unlink

Remove relation link.

```bash theme={null}
ov unlink <FROM_URI> <TO_URI>
```

**Example:**

```bash theme={null}
ov unlink viking://resources/doc1.md viking://resources/doc2.md
```

## System Commands

### system wait

Wait for processing queue to complete.

```bash theme={null}
ov system wait [OPTIONS]
```

**Options:**

* `--timeout <SECONDS>` - Max wait time

**Example:**

```bash theme={null}
# Wait for all processing
ov system wait --timeout 300
```

### system status

Get system status.

```bash theme={null}
ov system status
```

**Example:**

```bash theme={null}
ov system status
ov -o json system status | jq '.result.is_healthy'
```

### system health

Quick health check.

```bash theme={null}
ov system health
```

### observer queue

Get queue status.

```bash theme={null}
ov observer queue
```

### observer vikingdb

Get VikingDB status.

```bash theme={null}
ov observer vikingdb
```

### observer vlm

Get VLM status.

```bash theme={null}
ov observer vlm
```

## Configuration Commands

### config show

Show current configuration.

```bash theme={null}
ov config show
```

### config validate

Validate configuration file.

```bash theme={null}
ov config validate
```

## Scripting Examples

### Batch Processing

```bash theme={null}
#!/bin/bash

# Add multiple resources
for url in $(cat urls.txt); do
  ov add-resource "$url" --wait --timeout 120
done

# Wait for all processing
ov system wait --timeout 600

# Export backup
ov export viking://resources --to ./backup-$(date +%Y%m%d).ovpack
```

### Search and Extract

```bash theme={null}
#!/bin/bash

# Search and get URIs
URIS=$(ov -o json find "installation guide" | jq -r '.result.resources[].uri')

# Read content from each result
for uri in $URIS; do
  echo "=== $uri ==="
  ov read "$uri"
  echo
done
```

### Session Workflow

```bash theme={null}
#!/bin/bash

# Create session
SESSION=$(ov -o json session new | jq -r '.result.session_id')
echo "Session: $SESSION"

# Add messages
ov session add-message \
  --session-id "$SESSION" \
  --role user \
  --content "What is OpenViking?"

ov session add-message \
  --session-id "$SESSION" \
  --role assistant \
  --content "OpenViking is an agent-native context database."

# Context-aware search
ov search "how to install" --session-id "$SESSION"

# Commit session
ov session commit "$SESSION"
```

### Monitoring Script

```bash theme={null}
#!/bin/bash

# Check system health
if ov -o json system health | jq -e '.result.healthy' > /dev/null; then
  echo "✓ System healthy"
else
  echo "✗ System unhealthy"
  ov -o json system status | jq '.result.errors'
  exit 1
fi

# Check queue
QUEUE_SIZE=$(ov -o json observer queue | jq -r '.result.queue_size // 0')
echo "Queue size: $QUEUE_SIZE"

if [ "$QUEUE_SIZE" -gt 100 ]; then
  echo "WARNING: Large queue backlog"
fi
```

## Output Format

<Tabs>
  <Tab title="Table (Default)">
    ```bash theme={null}
    ov ls viking://resources
    ```

    ```
    ┌────────────────┬──────┬──────────┐
    │ Name           │ Type │ Size     │
    ├────────────────┼──────┼──────────┤
    │ docs/          │ dir  │ -        │
    │ README.md      │ file │ 1.2 KB   │
    └────────────────┴──────┴──────────┘
    ```
  </Tab>

  <Tab title="JSON">
    ```bash theme={null}
    ov -o json ls viking://resources
    ```

    ```json theme={null}
    {
      "status": "ok",
      "result": [
        {"name": "docs", "isDir": true},
        {"name": "README.md", "isDir": false, "size": 1234}
      ]
    }
    ```
  </Tab>
</Tabs>

<Tip>
  Use JSON output (`-o json`) for scripting and pipe to `jq` for processing:

  ```bash theme={null}
  ov -o json find "query" | jq '.result.resources[].uri'
  ```
</Tip>

## Related Resources

<CardGroup cols={2}>
  <Card title="Python SDK" icon="python" href="/guides/python-sdk">
    Complete Python SDK reference
  </Card>

  <Card title="Configuration" icon="gear" href="/guides/configuration">
    CLI configuration reference
  </Card>

  <Card title="Authentication" icon="key" href="/guides/authentication">
    API key setup
  </Card>

  <Card title="Deployment" icon="rocket" href="/guides/deployment">
    Deploy OpenViking Server
  </Card>
</CardGroup>