OpenViking CLI Setup

This guide helps you install the OpenViking CLI, configure it, and verify that it can connect to OpenViking.

ov is the client CLI. It connects to an existing OpenViking server or to OpenViking Service (VolcEngine Cloud). It does not replace server setup. If you still need to install or start a custom OpenViking server, follow the Quick Start or the Server Mode guide first.

Use this page in either of two ways:

If you are setting up ov yourself, follow Manual Setup.
If you are asking an agent to set it up for you, give the agent this page and ask it to follow Agent-Assisted Setup.

The CLI evolves quickly. Use ov --help and ov <command> --help as the source of truth for the commands available in your installed version.

What This Configures

The CLI uses ~/.openviking/ovcli.conf as the active client connection config.

When you create named configs, ov stores them next to the active file as ~/.openviking/ovcli.conf.<name>. Switching configs copies the chosen saved config into ~/.openviking/ovcli.conf.

ov config is the human-friendly interactive manager. It can add, edit, delete, validate, and switch configs.

ov config add, ov config edit, ov config list, ov config switch <name>, and ov config delete are deterministic commands for scripts and agents.

Choose a Target

Choose the OpenViking target before running setup commands.

Agents should ask the user which target they want unless it has already been specified. Existing configs, active configs, local files, default ports, and running services can inform follow-up questions, but they are not consent for the agent to choose a target, switch or replace configs, probe local services, start servers, or write data.

OpenViking Service (VolcEngine Cloud)

Choose this when you want OpenViking hosted as a managed service on VolcEngine Cloud.

Server endpoint used by ov: https://api.vikingdb.cn-beijing.volces.com/openviking
Console page for API keys: https://console.volcengine.com/vikingdb/openviking/region:openviking+cn-beijing
In the console, go to User Management → API Key to view and copy your key.
API key is required.
Standard setup only needs the API key. Do not ask for --account or --user unless the user's administrator specifically provides identity override values.

Remote Custom

Choose this when you connect to a custom OpenViking server hosted somewhere other than the current machine.

Server URL is provided by the user or server administrator.
API key may be required.
Root-key-only configs require --account and --user.

Local Custom

Choose this only when the user wants to connect to a custom OpenViking server on the current machine.

Default local URL: http://127.0.0.1:1933
API key is usually not needed for a local unauthenticated server.
Agents should not probe local ports, curl local health endpoints, or start server commands unless the user chose local custom setup.

Note: Recent CLI versions (v0.3.23+) require a saved display language before most commands will run. In an interactive terminal the CLI prompts you on first use; in a non-interactive shell (agent or CI) any non-exempt command exits 2 until you run ov language en or ov language zh-CN. Only ov language/ov lang, ov config add|edit|delete|list, and ov config switch <name> are exempt, so run ov language <code> before the ov config validate, ov health, and ov status checks above.

Before You Start

You need:

A way to install the CLI:
- Node.js and npm for the standalone @openviking/cli package, or
- Python tooling if you install the full openviking package.
A reachable OpenViking target:
- OpenViking Service (VolcEngine Cloud), or
- a custom OpenViking server.
An API key if your target requires authentication.

API keys are sensitive. Prefer entering them through the interactive ov config prompt when you configure ov yourself. Only provide API keys to an agent through a channel you intentionally trust. The agent should pass the key through stdin and must not put it in shell commands, logs, long-term memory, or raw config output. Use an environment variable only when the key is already present in the shell environment.

Install `ov`

Check whether ov is already installed:

bash

command -v ov
ov --version

If ov --version or any other ov command says OpenViking needs a display language, choose one and retry:

bash

ov language en
# or
ov language zh-CN

Install or upgrade the npm package:

bash

npm i -g @openviking/cli

The npm package is the simplest standalone CLI install. If you also want the Python SDK or server package, the Python package exposes ov too:

bash

uv tool install openviking --upgrade
# or
pip install openviking --upgrade --force-reinstall

Verify:

bash

ov --help

If ov is still not found, close and reopen the shell, or check the npm global prefix:

bash

npm prefix -g

On macOS and Linux, the global npm binary directory is usually $(npm prefix -g)/bin. Make sure that directory is on PATH.

Key Types

OpenViking CLI configs can hold a user key, a root key, or both.

User key: use this for normal data commands such as ov add-resource, ov find, and ov tree. The server derives the identity from the key, so you usually do not pass --account or --user. This is what most users want.
Root key: use this for admin work and commands that require --sudo. A root key has no built-in tenant identity. If a config only has a root key, it must also include --account and --user; that root key then serves normal commands for that identity and --sudo commands.
User key plus root key: use this when the same config should support daily data work and occasional admin work. Normal commands use the user key. --sudo commands use the root key with the configured account and user.

Manual Setup

Use this path when you are reading the guide and configuring ov yourself.

Run:

bash

ov config

Then choose:

Add config
OpenViking Service (VolcEngine Cloud) or Custom
A config name, or leave it empty to generate one
The required URL and API key values for the target you chose above
Save the config after validation

If you manage more than one OpenViking target, use:

bash

ov config switch

to choose the active config later.

After setup, continue to Verify The Setup.

Agent-Assisted Setup

Use this path when an agent is setting up ov for a user. The agent should read this whole page. The manual setup path above is the fallback when deterministic commands do not fit the user's environment.

Agent Checklist

Ask which target the user wants unless it has already been specified: OpenViking Service (VolcEngine Cloud), remote custom, or local custom.
Do not infer the intended setup from existing configs, active configs, local files, default ports, or running services.
Ask before switching configs, replacing configs, probing local services, starting servers, or writing data.
Run ov --help, ov config --help, and the relevant config subcommand help before choosing commands.
If you have long-term memory and the user permits it, store a short summary of the current ov --help command surface. Do not store API keys or other secrets.
Use non-interactive ov config commands when the required values are known.
Always pass --name for agent setup so retries target the same saved config.
If the agent already holds the API key through a trusted channel, pass it with --api-key-stdin or --root-api-key-stdin and write only the key bytes to stdin. Use --api-key-env or --root-api-key-env only when that environment variable already exists. Do not ask the user to open a separate shell just to export a key for the agent.
Use -o json and branch on the JSON result plus the process exit code.
Validate the active config with ov config validate, then check ov health and ov status.
If non-interactive setup fails because values are missing, auth is unclear, or terminal input is safer, guide the user through ov config instead.

Inspect the Installed CLI

Run:

bash

ov --help
ov config --help
ov config add --help
ov config add ov-service --help
ov config add custom --help
ov config edit --help

Use the installed CLI help as the source of truth. If this page and the installed help disagree, follow the installed help and tell the user what changed.

If a help command says OpenViking needs a display language, run ov language en, or ov language zh-CN if the user wants Chinese, then retry. Non-interactive config subcommands such as ov config add, ov config list, ov config edit, ov config switch <name>, and ov config delete can run before the display language is set.

Use Stable Names for Retries

Always pass --name when an agent creates a config. If you omit it, ov generates a random name; a retry can create a second saved config instead of updating the intended one.

ov config add is safe to run again with the same --name when the values are identical. It exits 0, and --activate will make that saved config active again. If the same name already exists with different values, the command exits 3 and asks for --force.

In the examples below, replace placeholders such as <CONFIG-NAME> and <REMOTE-OPENVIKING-URL> with user-approved values before running commands. Do not include the angle brackets.

Reading Results

When you use -o json with the non-interactive config commands, successful results are printed to stdout:

json

{"status":"ok","result":{"action":"add","name":"<CONFIG-NAME>"}}

The result object depends on the subcommand. add and edit also include fields such as kind, url, saved_path, active_path, activated, and validation, so agents should not assume that only action and name are present.

Errors are printed to stderr:

json

{"status":"error","error":{"code":"bad_input","message":"..."}}

Agents should branch on the process exit code and the JSON error.code, not on human-readable prose.

Exit code	Meaning
`0`	Success, or already in the desired state
`2`	Bad input, missing value, invalid name, unreadable secret source, or no display language selected in a non-interactive shell (run `ov language <code>` first)
`3`	A config with that name already exists with different values; pass `--force` only if replacement is intended
`4`	Server unreachable or config validation failed
`5`	Authentication or key-role mismatch, such as passing a root key where a user key is expected
`6`	Refused operation, such as deleting the active config

List Existing Configs

bash

ov config list -o json

The list output shape is:

json

{"status":"ok","result":[{"name":"<CONFIG-NAME>","kind":"OpenViking Service","url":"https://api.vikingdb.cn-beijing.volces.com/openviking","active":true}]}

For an existence check, inspect result[].name. To decide whether a config already needs switching, inspect the matching entry's active flag.

If a suitable saved config already exists, activate it by name:

bash

ov config switch <CONFIG-NAME> -o json

Then run the verification commands.

Add OpenViking Service

If the agent already holds the API key through a trusted channel, run:

bash

ov config add ov-service --name <CONFIG-NAME> --api-key-stdin --activate -o json

A shell pipe has this shape:

bash

printf '%s' "$API_KEY" | ov config add ov-service --name <CONFIG-NAME> --api-key-stdin --activate -o json

$API_KEY stands for a trusted runtime secret source, not the literal key. Use stdin when the agent can supply the key without putting it in the command text, shell history, logs, or a long-lived exported environment variable.

Write only the API key bytes to stdin. Do not place the key in the shell command. This writes an OpenViking Service config using the fixed endpoint https://api.vikingdb.cn-beijing.volces.com/openviking. The ov-service target does not take a custom server URL.

Use an environment variable only if it already exists in the shell:

bash

ov config add ov-service --name <CONFIG-NAME> --api-key-env <API-KEY-ENV-VAR> --activate -o json

Do not pass --account or --user for standard OpenViking Service setup. Use them only when the user or their OpenViking administrator provides identity override values.

Add a Local Custom Server

Use this path only after the user chooses local custom setup.

For a local unauthenticated server:

bash

ov config add custom --name <CONFIG-NAME> --url http://127.0.0.1:1933 --activate -o json

If the local server is not running, guide the user to start it first. See the Server Mode guide.

Add a Remote Custom Server

For a hosted custom server with a normal API key:

bash

ov config add custom --name <CONFIG-NAME> --url <REMOTE-OPENVIKING-URL> --api-key-stdin --activate -o json

The stdin pipe form is:

bash

printf '%s' "$API_KEY" | ov config add custom --name <CONFIG-NAME> --url <REMOTE-OPENVIKING-URL> --api-key-stdin --activate -o json

Write the API key to stdin. If the key is already in the shell environment, use --api-key-env <API-KEY-ENV-VAR> instead.

For a custom server where the user gives you only a root API key, include the target account and user:

bash

ov config add custom --name <CONFIG-NAME> --url <REMOTE-OPENVIKING-URL> --root-api-key-stdin --account <ACCOUNT-ID> --user <USER-ID> --activate -o json

Write the root API key to stdin. Root keys require explicit --account and --user so normal CLI commands know which identity to use.

For a custom server where the user has both a user key and a root key, store both in one config:

bash

ov config add custom --name <CONFIG-NAME> --url <REMOTE-OPENVIKING-URL> --api-key-stdin --root-api-key-env <ROOT-API-KEY-ENV-VAR> --account <ACCOUNT-ID> --user <USER-ID> --activate -o json

This keeps normal commands on the user key and lets --sudo commands use the root key. Because one command has only one stdin stream, the second key must come from an existing environment variable. If neither key is already available in the environment, use ov config and guide the user through the interactive flow.

Edit or Replace a Config

List configs first:

bash

ov config list -o json

Rename and activate a saved config:

bash

ov config edit <CONFIG-NAME> --new-name <NEW-CONFIG-NAME> --activate -o json

Replace an API key:

bash

ov config edit <CONFIG-NAME> --api-key-stdin --activate -o json

Write the replacement API key to stdin.

Replace a custom server URL:

bash

ov config edit <CONFIG-NAME> --url <CUSTOM-OPENVIKING-URL> --activate -o json

Use --force only when you intentionally want to replace an existing saved config name.

Delete a Saved Config

Delete only non-active saved configs:

bash

ov config delete <OLD-CONFIG-NAME> -o json

If the config is active, switch to another config first:

bash

ov config switch <CONFIG-NAME> -o json
ov config delete <OLD-CONFIG-NAME> -o json

Verify the Setup

Run:

bash

ov config show
ov config list -o json
ov config validate
ov health
ov status

Use ov config show for inspection because it redacts secrets.

Do not print the raw config file unless you understand that it may contain secrets.

If a verification command says OpenViking needs a display language, run ov language en, or ov language zh-CN if the user wants Chinese, then rerun verification.

ov status includes broader server and data diagnostics. If ov config validate and ov health pass, a warning in ov status does not always mean CLI setup failed.

Learn the Rest of the CLI

After the config is working, use the built-in help to explore the rest of ov:

bash

ov --help
ov config --help
ov add-resource --help

Agents should refresh this help before running unfamiliar commands. If an agent keeps long-term memory for the user and the user allows it, the agent may store a concise summary of the command surface for future sessions. It should not store secrets, raw config files, or private server details unless the user explicitly asks.

Credential Safety

API keys may grant access to your OpenViking data.
Prefer the interactive ov config prompt for manual setup.
For agent-assisted setup, provide API keys only through a channel you intentionally trust.
Agents should pass keys through stdin. Use environment variables only when they already exist in the shell.
Do not include API keys directly in shell commands that may be saved in shell history.
Do not print raw ~/.openviking/ovcli.conf.
Do not share screenshots that reveal API keys.
Use temporary or revocable keys for demos and trials.

Troubleshooting

`ov` Is Not Found

Run:

bash

npm i -g @openviking/cli
npm prefix -g

Then reopen the shell or add the global npm binary directory to PATH. On macOS and Linux, that directory is usually $(npm prefix -g)/bin.

npm Global Install Fails

If npm reports a permission error, use your normal Node.js setup policy. Avoid sudo npm i -g unless you intentionally manage global npm packages with sudo.

Local Server Is Not Running

Use this only when the user chose local custom setup. Then verify the server:

bash

curl http://127.0.0.1:1933/health

If it fails, start the server before configuring ov. See the Server Mode guide.

API Key Validation Fails

Run ov config again and edit the config. For OpenViking Service, confirm the key came from the OpenViking console URL above. For custom servers, confirm whether the server requires authentication.

Agents should not keep retrying unknown keys. Ask the user to confirm the target type, server URL, key type, account, and user.

The Wrong Config Is Active

Inspect and switch:

bash

ov config show
ov config list
ov config switch
ov config validate

Agents can switch by name:

bash

ov config list -o json
ov config switch <CONFIG-NAME> -o json

Non-Interactive Setup Does Not Fit

Use the interactive wizard:

bash

ov config

This is the right fallback when a secret should be typed directly by the user, when the target is unclear, or when validation needs human judgment.

Old Setup Commands

Use ov config. Do not use old or removed setup commands such as ov config setup-cli.

Next Steps

Once the CLI is configured, use ov --help and ov <command> --help to learn the rest of the CLI.

Adding a resource writes data into the active OpenViking server. If you want a small demo, use a resource you are comfortable storing. Agents must ask the user for permission before running this kind of demo command.

bash

ov add-resource https://github.com/volcengine/OpenViking --wait
ov find "what is OpenViking"
ov tree viking://resources/ -L 2

For all commands:

bash

ov --help
ov config --help
ov add-resource --help

OpenViking CLI Setup ​

What This Configures ​

Choose a Target ​

OpenViking Service (VolcEngine Cloud) ​

Remote Custom ​

Local Custom ​

Before You Start ​

Install ov ​

Key Types ​

Manual Setup ​

Agent-Assisted Setup ​

Agent Checklist ​

Inspect the Installed CLI ​

Use Stable Names for Retries ​

Reading Results ​

List Existing Configs ​

Add OpenViking Service ​

Add a Local Custom Server ​

Add a Remote Custom Server ​

Edit or Replace a Config ​

Delete a Saved Config ​

Verify the Setup ​

Learn the Rest of the CLI ​

Credential Safety ​

Troubleshooting ​

ov Is Not Found ​

npm Global Install Fails ​

Local Server Is Not Running ​

API Key Validation Fails ​

The Wrong Config Is Active ​

Non-Interactive Setup Does Not Fit ​

Old Setup Commands ​

Next Steps ​

OpenViking CLI Setup

What This Configures

Choose a Target

OpenViking Service (VolcEngine Cloud)

Remote Custom

Local Custom

Before You Start

Install `ov`

Key Types

Manual Setup

Agent-Assisted Setup

Agent Checklist

Inspect the Installed CLI

Use Stable Names for Retries

Reading Results

List Existing Configs

Add OpenViking Service

Add a Local Custom Server

Add a Remote Custom Server

Edit or Replace a Config

Delete a Saved Config

Verify the Setup

Learn the Rest of the CLI

Credential Safety

Troubleshooting

`ov` Is Not Found

npm Global Install Fails

Local Server Is Not Running

API Key Validation Fails

The Wrong Config Is Active

Non-Interactive Setup Does Not Fit

Old Setup Commands

Next Steps