CLI Usage - OpenViking

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

Installation

Quick Install (Linux/macOS)
From Source
Via Python Package

curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/crates/ov_cli/install.sh | bash

# Requires Rust >= 1.88
cargo install --path crates/ov_cli

pip install openviking
# CLI binary is bundled in the wheel

Configuration

Create ~/.openviking/ovcli.conf:

{
  "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`

You can also set OPENVIKING_CLI_CONFIG_FILE environment variable to use a custom config path.

Quick Start

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

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:

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

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

Examples

# 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

add-skill

Add a skill to OpenViking.

ov add-skill <DATA> [OPTIONS]

Options:

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

export

Export resource as .ovpack file.

ov export <URI> --to <PATH>

Example:

ov export viking://resources/docs --to ./backup/docs.ovpack

import

Import .ovpack file.

ov import <FILE> --target <URI> [OPTIONS]

Options:

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

Example:

ov import ./backup/docs.ovpack --target viking://resources/restored

File System Operations

ls

List directory contents.

ov ls <URI> [OPTIONS]

Options:

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

Examples

# 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

tree

Get directory tree structure.

ov tree <URI>

Example:

ov tree viking://resources
ov tree viking://resources/docs

mkdir

Create a directory.

ov mkdir <URI>

Example:

ov mkdir viking://resources/new-folder

rm

Remove a resource.

ov rm <URI> [OPTIONS]

Options:

--recursive - Remove directory recursively

Examples

# Delete file
ov rm viking://resources/example.md

# Delete directory
ov rm viking://resources/old-docs --recursive

mv

Move or rename a resource.

ov mv <FROM_URI> <TO_URI>

Example:

ov mv viking://resources/old.md viking://resources/new.md

stat

Get resource metadata.

ov stat <URI>

Example:

ov stat viking://resources/example.md

Content Access

read

Read L2 (full content).

ov read <URI> [OPTIONS]

Options:

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

Examples

# Read entire file
ov read viking://resources/example.md

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

abstract

Read L0 abstract (~100 token summary).

ov abstract <URI>

Example:

ov abstract viking://resources/docs

overview

Read L1 overview (~2k token overview).

ov overview <URI>

Example:

ov overview viking://resources/docs

Search Operations

find

Semantic search (quick retrieval).

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)

Examples

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

search

Context-aware search with session.

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:

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

ov grep <URI> <PATTERN> [OPTIONS]

Options:

--case-insensitive - Case-insensitive search

Examples

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

glob

File pattern matching.

ov glob <PATTERN> [OPTIONS]

Options:

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

Examples

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

Session Management

session new

Create a new session.

ov session new

Example:

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

session list

List all sessions.

ov session list

session get

Get session details.

ov session get <SESSION_ID>

Example:

ov session get abc123

session delete

Delete a session.

ov session delete <SESSION_ID>

Example:

ov session delete abc123

session add-message

Add message to session.

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:

ov session add-message \
  --session-id $SESSION \
  --role user \
  --content "Hello, OpenViking!"

session commit

Commit session (archive and extract memories).

ov session commit <SESSION_ID>

Example:

ov session commit $SESSION

Relations

relations

List relations for a resource.

ov relations <URI>

Example:

ov relations viking://resources/doc.md

link

Create relation link.

ov link <FROM_URI> <TO_URI> [OPTIONS]

Options:

--reason <TEXT> - Reason for linking

Example:

ov link \
  viking://resources/doc1.md \
  viking://resources/doc2.md \
  --reason "Related documentation"

unlink

Remove relation link.

ov unlink <FROM_URI> <TO_URI>

Example:

ov unlink viking://resources/doc1.md viking://resources/doc2.md

System Commands

system wait

Wait for processing queue to complete.

ov system wait [OPTIONS]

Options:

--timeout <SECONDS> - Max wait time

Example:

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

system status

Get system status.

ov system status

Example:

ov system status
ov -o json system status | jq '.result.is_healthy'

system health

Quick health check.

ov system health

observer queue

Get queue status.

ov observer queue

observer vikingdb

Get VikingDB status.

ov observer vikingdb

observer vlm

Get VLM status.

ov observer vlm

Configuration Commands

config show

Show current configuration.

ov config show

config validate

Validate configuration file.

ov config validate

Scripting Examples

Batch Processing

#!/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

#!/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

#!/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

#!/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

Table (Default)
JSON

ov ls viking://resources

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

ov -o json ls viking://resources

{
  "status": "ok",
  "result": [
    {"name": "docs", "isDir": true},
    {"name": "README.md", "isDir": false, "size": 1234}
  ]
}

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

ov -o json find "query" | jq '.result.resources[].uri'

Python SDK

Complete Python SDK reference

Configuration

CLI configuration reference

Authentication

API key setup

Deployment

Deploy OpenViking Server

​Installation

​Configuration

​Quick Start

​Global Options

​Resource Management

​add-resource

​add-skill

​export

​import

​File System Operations

​ls

​tree

​mkdir

​rm

​mv

​stat

​Content Access

​read

​abstract

​overview

​Search Operations

​find

​search

​grep

​glob

​Session Management

​session new

​session list

​session get

​session delete

​session add-message

​session commit

​Relations

​relations

​link

​unlink

​System Commands

​system wait

​system status

​system health

​observer queue

​observer vikingdb

​observer vlm

​Configuration Commands

​config show

​config validate

​Scripting Examples

​Batch Processing

​Search and Extract

​Session Workflow

​Monitoring Script

​Output Format

​Related Resources

Python SDK

Configuration

Authentication

Deployment

Installation

Configuration

Quick Start

Global Options

Resource Management

add-resource

add-skill

export

import

File System Operations

ls

tree

mkdir

rm

mv

stat

Content Access

read

abstract

overview

Search Operations

find

search

grep

glob

Session Management

session new

session list

session get

session delete

session add-message

session commit

Relations

relations

link

unlink

System Commands

system wait

system status

system health

observer queue

observer vikingdb

observer vlm

Configuration Commands

config show

config validate

Scripting Examples

Batch Processing

Search and Extract

Session Workflow

Monitoring Script

Output Format

Related Resources