openviking

$27

# Semantic search

ov search "dependency injection" --uri viking://resources/fastapi --limit 10

ov search "how tokens are refreshed" --uri viking://resources/fastapi/fastapi/security

ov search "JWT authentication" --limit 10          # across all repos

ov search "error handling" --limit 5 --threshold 0.7  # filter low-relevance results

# Keyword search — exact match or regex

ov grep "verify_token" --uri viking://resources/fastapi

ov grep "class.*Session" --uri viking://resources/requests/requests

# File enumeration — by name pattern (always specify --uri to scope the search)

ov glob "**/*.py" --uri viking://resources/fastapi

ov glob "**/test_*.py" --uri viking://resources/fastapi/tests

ov glob "**/*.py" --uri viking://resources/   # across all repos

Narrowing scope: once you identify a relevant directory, pass it as --uri to restrict subsequent searches to that subtree — this is faster and more precise than searching the whole repo.

Query formulation: write specific, contextual queries rather than single keywords.

ov search "API"                                                       # too vague

ov search "REST API authentication with JWT tokens"                   # better

ov search "JWT token refresh flow" --uri viking://resources/backend   # best

Read Content

# Directories: AI-generated summaries

ov abstract viking://resources/fastapi/fastapi/dependencies/   # one-line summary

ov overview viking://resources/fastapi/fastapi/dependencies/   # detailed breakdown

# Files: raw content

ov read viking://resources/fastapi/fastapi/dependencies/utils.py

ov read viking://resources/fastapi/fastapi/dependencies/utils.py --offset 100 --limit 50

abstract / overview only work on directories. read only works on files.

Browse

ov ls viking://resources/                        # list all indexed repos

ov ls viking://resources/fastapi                 # list repo top-level contents

ov ls viking://resources/fastapi --simple        # paths only, no metadata

ov ls viking://resources/fastapi --recursive     # list all files recursively

ov tree viking://resources/fastapi               # full directory tree (default: 3 levels deep)

ov tree viking://resources/fastapi -L 2          # limit depth to 2 levels

ov tree viking://resources/fastapi -l 200        # truncate abstract column to 200 chars

ov tree viking://resources/fastapi -L 2 -l 200   # combined: 2 levels deep, 200-char summaries

-L controls how many levels deep the tree expands. -l controls the length of the AI-generated summary per directory. Use ov tree -L 2 -l 200 as a good starting point to understand a repo's structure before diving in.

Add a Repository

ov add-resource https://github.com/owner/repo --to viking://resources/repo --timeout 300

--timeout is required (seconds). Use 300 (5 min) for small repos, increase for larger ones.

After submitting, run ov observer queue once and report status to user. Indexing runs in background — do not poll or wait.

Repo Size

Files

Est. Time

Small

< 100

2–5 min

Medium

100–500

5–20 min

Large

500+

20–60+ min

Remove a Repository

ov rm viking://resources/fastapi --recursive

This permanently deletes the repo and all its indexed content. Confirm with the user before running.

Error Handling

**command not found: ov** → Tell user: pip install openviking --upgrade. Stop.

**url is required / CLI_CONFIG error** → Auto-create config and retry:

mkdir -p ~/.openviking && echo '{"url": "http://localhost:1933"}' > ~/.openviking/ovcli.conf

**CONNECTION_ERROR / failed to connect:**

• ~/.openviking/ov.conf exists → auto-start server, wait until healthy, retry:

openviking-server > /tmp/openviking.log 2>&1 &

for i in $(seq 1 10); do ov health 2>/dev/null && break; sleep 3; done

• Does not exist → Tell user to configure ~/.openviking/ov.conf first. Stop.

More Help

For other issues or command details, run:

ov help

ov <command> --help   # e.g. ov search --help