examples/skills/ov-resources/docs/add-resource.md
ov add-resource)The ov add-resource command imports external resources into OpenViking's context database. By default it writes shared account resources under viking://resources/, and it can also target current-user or peer-scoped resource roots.
| Type | Examples |
|---|---|
| Local file | ./docs/api.md, ./team_building.jpg, /User/volcengine/Documents/profile.pdf |
| Local directory | /User/volcengine/Photo/Travels/2026/ |
| ZIP archive | ./docs-of-project.zip (unzipped on server) |
| URL | https://example.com/guide.md, https://arxiv.org/pdf/2602.09540 |
| Git repo | https://github.com/volcengine/OpenViking, [email protected]:viking/viking.git |
# From URL
ov add-resource https://github.com/volcengine/OpenViking
ov add-resource https://arxiv.org/pdf/2602.09540
# From local file
ov add-resource ./docs/api-spec.md
ov add-resource ./team_building.jpg
ov add-resource /User/volcengine/Documents/project.docx
# From local directory
ov add-resource /User/volcengine/Photo/Travels/2026/ --include "*.jpg,*.jpeg,*.png"
# From ZIP
ov add-resource ./docs-of-project.zip
By default resources go under shared viking://resources/. Use --to or --parent to override:
# Exact target (must not exist)
ov add-resource ./docs --to "viking://resources/2026/2026-01-01/"
# Place under existing parent directory
ov add-resource ./docs --parent "viking://resources/docs/"
# Place under the current user's private resource root
ov add-resource ./docs --parent "viking://user/resources/docs/"
# Place under a specific peer's private resource root
ov add-resource ./docs --parent "viking://user/alice/peers/web-visitor-alice/resources/docs/"
# Auto-create parent if missing
ov add-resource ./docs --parent-auto-create "viking://resources/docs/2026/05/07"
ov add-resource ./docs -p "viking://resources/docs/{calendar:today}"
viking://user/resources/... is current-user shorthand and resolves to viking://user/{user_id}/resources/.... peer_id path segments must be safe single-segment identifiers such as web-visitor-alice; values with :, +, ., .., or path separators are rejected.
Semantic processing runs asynchronously. Use --wait to block until complete:
# Wait for completion
ov add-resource ./docs --wait
# Wait with timeout
ov add-resource ./docs --wait --timeout 60
# Fire and forget (default)
ov add-resource ./docs
When wait=false, the CLI returns after upload/parse/finalize (non-Git sources) or after preflight (Git sources). Use the returned task_id with GET /api/v1/tasks/{task_id} or ov observer queue to track progress.
--watch-interval)Create a watch task to re-import periodically:
# Refresh every 60 minutes, bound to a fixed URI
ov add-resource https://github.com/volcengine/OpenViking \
--to "viking://resources/repos/OpenViking" \
--watch-interval 60
# Refresh every 30 minutes, bound to imported root_uri
ov add-resource https://example.com/spec.md --watch-interval 30
# Cancel watch for the same target
ov add-resource https://github.com/volcengine/OpenViking \
--to "viking://resources/repos/OpenViking" \
--watch-interval 0
--watch-interval is in minutes. > 0 creates/updates; <= 0 cancels. Prefer --to for stable long-term watches.
# Include only matching files
ov add-resource ./project --include "*.py,*.md"
# Exclude patterns
ov add-resource ./project --exclude "*.tmp,*.log"
# Ignore specific directory names
ov add-resource ./project --ignore-dirs "node_modules,target,.git"
# Preserve directory structure
ov add-resource ./project --preserve-structure
For local directories, scanning respects .gitignore with standard Git semantics; ignore_dirs, include, and exclude further refine ingestion.
Default table format:
Note: Resource is being processed in the background.
Use 'ov wait' to wait for completion, or 'ov observer queue' to check status.
status success
root_uri viking://resources/01-overview
task_id uuid-xxx
JSON format (-o json):
{
"status": "success",
"root_uri": "viking://resources/01-overview",
"task_id": "uuid-xxx"
}
With --wait, the response includes queue_status with pending, processing, completed counts.
| Parameter | Description |
|---|---|
--to | Exact target URI (mutually exclusive with --parent) |
--parent / -p | Parent directory URI |
--parent-auto-create | Auto-create parent if missing |
--reason | Reason for adding (experimental) |
--instruction | Processing instructions (experimental) |
--wait | Block until semantic processing completes |
--timeout | Timeout in seconds when --wait is used |
--strict | Use strict mode |
--ignore-dirs | Directory names to ignore (comma-separated) |
--include | File patterns to include (glob) |
--exclude | File patterns to exclude (glob) |
--watch-interval | Scheduled refresh interval in minutes |
path and temp_file_id are mutually exclusive.to and parent are mutually exclusive.to points to an existing resource, the call triggers an incremental update.wait=false, OpenViking validates the repo, resolves the target URI, reserves root_uri, and returns immediately; clone/parse/finalize continues in background.ov write instead of add_resource.