ovcli Configuration

ovcli.conf is the client configuration file for the ov CLI. It stores the server connection, authentication identity, and command defaults.

Agent plugins for Codex, Claude Code, OpenCode, and other clients also read their own OPENVIKING_* environment variables for Recall, Capture, diagnostics, and other behavior. Those variables are not part of ovcli.conf; configure them in the corresponding Agent Integration documentation.

Use ov config to create and maintain configurations. Use ov config show to inspect the active configuration with secrets redacted.

Default path:

~/.openviking/ovcli.conf

To select another file:

export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf

Complete Example

{
  "url": "https://openviking.example.com",
  "api_key": "<user-or-admin-key>",
  "root_api_key": "<root-key>",
  "account": "acme",
  "user": "alice",
  "actor_peer_id": "agent:research-assistant",
  "timeout": 60,
  "output": "table",
  "echo_command": true,
  "show_progress": false,
  "verbose": false,
  "profile": false,
  "upload": {
    "ignore_dirs": "node_modules,.cache,dist",
    "include": "*.md,*.pdf",
    "exclude": "*.tmp,*.log"
  },
  "extra_headers": {
    "X-Tenant": "acme"
  },
  "gateway_token": "<gateway-token>"
}

Omit fields you do not need. A local server in dev mode usually needs only url.

Connection and Authentication

{
  "url": "https://openviking.example.com",
  "api_key": "<user-or-admin-key>",
  "root_api_key": "<root-key>",
  "account": "acme",
  "user": "alice",
  "actor_peer_id": "agent:research-assistant",
  "extra_headers": {
    "X-Tenant": "acme"
  },
  "gateway_token": "<gateway-token>"
}

Choosing API Keys

server.root_api_key in ov.conf is accepted by the server. When the CLI manages that server, root_api_key in ovcli.conf must match it.

Command Behavior

{
  "timeout": 120,
  "echo_command": true,
  "show_progress": true,
  "verbose": false,
  "profile": false
}

Command-line options such as --profile, --progress, --no-progress, and --verbose override the configuration for the current command.

Upload Filters

{
  "upload": {
    "ignore_dirs": "node_modules,.cache,dist",
    "include": "*.md,*.pdf",
    "exclude": "*.tmp,*.log"
  }
}

Local directory uploads also honor .gitignore. Command-line --include and --exclude rules are merged with the configuration.

Workspace Configuration

A repository can carry its own plugin settings, so the memory behavior of a project travels with the checkout instead of living in each contributor's home directory. Two files sit under the workspace root, and a third layer is kept per machine:

<repo-root>/.openviking/config.json         # committed, shared by the team
<repo-root>/.openviking/config.local.json   # private, not committed
~/.openviking/workspaces/<slot>.json        # per-machine registry, one file per workspace

The workspace root is the nearest ancestor directory holding a .git, or one holding .openviking/config.json (or config.local.json) — whichever the walk upward reaches first; $HOME and the filesystem root are never workspace roots. A directory that is neither is not a workspace at all: no configuration layer, no registry entry, and no peer of its own. The registry slot name combines the root's directory name with a hash of its full path, so two clones of one repository on one machine never share an entry. These layers are read by the Claude Code and Codex plugins, not by ov commands.

Precedence

Highest first:

A scalar from a higher layer replaces the lower one. Lists are unioned across layers; a leading "!reset" element drops everything the lower layers contributed, so ["!reset", "*/scratch/*"] is the whole list.

No command writes the registry file. Create it by hand at the path ov-memory-doctor prints, with version: 1 and the same schema as the workspace files.

Schema

version: 1 is required. A file declaring another version is skipped with a warning rather than guessed at.

{
  "version": 1,
  "peer": { "source": "git" },
  "recall": { "peer_scope": "actor", "max_items": 20 },
  "capture": { "commit_token_threshold": 20000 },
  "labels": { "team": "search" }
}

An out-of-range number is clamped to the nearest bound and reported; an unrecognized enum value is ignored. Keys outside this list are kept in the file and ignored.

Workspace Peer

A peer is a path prefix under your own user space — viking://user/<you>/peers/<peer>/memories — that keeps one project's memories together. By default only a git repository gets one: the normalized origin URL, else the repository root path. A directory that is not a repository sends no peer at all, and what is remembered there goes to your user-level space at viking://user/<you>/memories instead. That is deliberate: an application that opens a fresh directory for every task would otherwise mint a fresh, empty peer for every task.

peer.source decides the rule. The same setting is spelled OPENVIKING_PEER_SOURCE in the environment and plugin.peerSource or plugin.<harness>.peerSource in ovcli.conf.

Give a Directory Its Own Peer

Create .openviking/config.json in the directory:

{"version": 1, "peer": {"id": "my-project"}}

That directory and everything below it now writes to the peer my-project, repository or not. The id names no path, so it survives a move, a rename and a second machine — and two directories carrying the same id share one memory, which is how you merge them on purpose.

The other ways to set it, highest precedence first:

In /Users/x/Dev/OpenViking/examples/codex-memory-plugin with origin [email protected]:volcengine/OpenViking.git, the peer is github.com-volcengine-openviking — the same value from any subdirectory, worktree, machine, or clone. Every clone of one repository therefore shares one peer, while a fork has a different origin and stays separate. The derivation reads the repository's files directly instead of running git, so it also works where git is missing from PATH, and the URL is normalized so that the ssh and https spellings of one repository agree and a token embedded in the URL never reaches the peer id.

By Situation

Recall Isolation

peer.source decides where memories are written; recall.peer_scope decides what is read back. A peer is a path prefix, not a tenant boundary. The same setting is spelled plugin.recallPeerScope in ovcli.conf and OPENVIKING_RECALL_PEER_SCOPE in the environment.

User-level memories are read at full weight under both, and that is the cost of sending no peer outside a repository: what a throwaway task teaches is recalled in every project afterwards. For stronger separation, give such a directory a peer.id of its own, or switch to "actor".

Switching to the git default needs no migration and moves nothing: memories written under the earlier cwd-derived peer stay where they are, and recall keeps reaching them — through the cross-peer sweep under "all", and through the extra query under "actor". peer_scope is a per-request parameter; against a server too old to know it, the plugin records the downgrade once and warns rather than silently reading everything.

What a Workspace File May Not Set

A hook runs without a prompt, so these files are trusted; what is refused is structural instead:

• Connection and credential keys — url, api_key, root_api_key, account, user, extra_headers, and the rest — are stripped with a warning wherever they appear. Which server the data goes to stays answerable from ovcli.conf and the environment alone.
• ${VAR} is never expanded in these files.

What a committed file switches off is announced rather than blocked: the plugin's ov-memory-doctor reports every workspace-scoped value, the layer it came from, and what it shadowed.

.gitignore must not ignore all of .openviking/, or config.json can never be committed. Narrow the rule to the parser's scratch directories and the private file:

.openviking/media/
.openviking/downloads/
.openviking/config.local.json

ov-memory-doctor warns when a blanket rule is in effect.

Related Environment Variables

The ov CLI directly uses only a small set of environment variables:

The --api-key-env <name> and --root-api-key-env <name> options for ov config add and ov config edit read keys from a named environment variable and write them to the configuration.

Variables such as OPENVIKING_AUTO_RECALL, OPENVIKING_RECALL_LIMIT, OPENVIKING_AUTO_CAPTURE, and OPENVIKING_DEBUG are read by Agent plugin processes and are not ovcli.conf fields.

Multiple Servers

Normal ov commands, plus ov config show and ov config validate, resolve the effective configuration in this order:

1. When OPENVIKING_CLI_CONFIG_FILE is set, that path is authoritative; a missing file is an error.
2. When the variable is unset, the default active file:

~/.openviking/ovcli.conf

The interactive manager and ov config list, switch, add, edit, and delete always manage the default store. Named configurations in that store live next to the default active file:

~/.openviking/ovcli.conf.<name>

For example, a production configuration can contain:

{
  "url": "https://openviking.example.com",
  "api_key": "<production-api-key>",
  "timeout": 120
}

Common commands:

ov config
ov config list
ov config switch <name>
ov config validate
ov config show

ov config switch <name> copies the named configuration to the default active file. If OPENVIKING_CLI_CONFIG_FILE remains set, normal ov commands continue to use the environment-selected file; unset it to use the switched default. New ov commands reread the effective file, while already-running Agent clients must restart before reading changes.

See OpenViking CLI Setup for interactive and agent-assisted configuration workflows.