OpenViking Control Plane (ov-cp)

ov-cp is the CLI for the OpenViking control plane (topapi). It manages OV collections (libraries) and shares its core with the mcp-server-openviking-controlplane MCP server, so behavior is identical.

Setup

Install once (from the package dir): uv sync (or pip install -e .).

Configure via env vars (CLI flags -k / -e / --project override them):

Env var	Meaning	Default
AGENTPLAN_API_KEY	Ark AgentPlan ApiKey (sent as Authorization: Bearer)	— (required)
VIKING_ENDPOINT	Control-plane base URL	https://api.vikingdb.cn-beijing.volces.com/openviking
OPENVIKING_PROJECT	Default project	default
VIKING_EXTRA_HEADERS	Extra request headers, comma-separated Key: Value	—

export AGENTPLAN_API_KEY=ark-xxxxxxxx
# VIKING_ENDPOINT defaults to the public gateway — leave it unset for normal use.

The default endpoint is the reserved public gateway (not open yet). Override VIKING_ENDPOINT (or -e) only for testing — e.g. point it at a kubectl port-forward of the data-plane service. The full request URL is {endpoint}/api/openviking/{Action}.

Commands

ov-cp list                       # list collections (optionally --project X)
ov-cp get     <ResourceID>       # collection info (Status, models, version, ...)
ov-cp usage   <ResourceID>       # file counts / hourly CNY and AgentPlan AFP estimate
ov-cp usage   <ResourceID> --account-id team-alpha
ov-cp usage   <ResourceID> --user-id alice  # user in account default
ov-cp usage   <ResourceID> --account-id team-alpha --user-id alice
ov-cp api-key <ResourceID>       # default user's plaintext data-plane key
ov-cp api-key <ResourceID> --user-id alice  # selected user's plaintext key
ov-cp api-key <ResourceID> --account-id team-alpha --user-id alice
ov-cp create  --name my_kb       # create a collection (see below)
ov-cp update  <ResourceID> --description "..."   # update fields / switch billing
ov-cp update  <ResourceID> --model-api-key ark-xxx  # overwrite AgentPlan model key
ov-cp delete  <ResourceID> --yes # delete (irreversible; uninstalls the Helm release)

# users of an enterprise-tier library (key must be associated with the library):
ov-cp user list     <ResourceID>                     # users (ApiKey is masked)
ov-cp user list     <ResourceID> --role user --page 1 --limit 20
ov-cp user register <ResourceID> alice            # new users always get role=user
ov-cp user update   <ResourceID> alice --regenerate-key
ov-cp user delete   <ResourceID> alice --yes      # revoke a user's credential

# target a non-default data space with --account-id:
ov-cp user list     <ResourceID> --account-id team-alpha
ov-cp user register <ResourceID> alice --account-id team-alpha
ov-cp user update   <ResourceID> alice --account-id team-alpha --regenerate-key
ov-cp user delete   <ResourceID> alice --account-id team-alpha --yes

# data spaces (accounts) of an enterprise-tier library:
ov-cp account list   <ResourceID> --keyword team --page 1 --limit 20
ov-cp account create <ResourceID> team-alpha
ov-cp account delete <ResourceID> team-alpha  # prompts before cascading deletion

After user update --regenerate-key, fetch the replacement with api-key <ResourceID> --user-id <UserID>; the update response only confirms success and does not contain the new key. Include --account-id <OpenVikingAccountID> when the user is outside account default.

update --model-api-key <ark-key> overwrites the library's AgentPlan MODEL credential; VLM and Embedding always share one key, and the library's other credentials are replayed unchanged. Only pass a key the user gave you for this purpose — it REPLACES what is stored. A library with no AgentPlan model credential is refused rather than reshaped.

Without that flag update sends no model configuration at all. Against a control plane that still rebuilds both models on every update (it rejects a metadata-only request with apikey is empty), update reads the library's own credentials back and replays them once, reporting it in the response Note. A non-AgentPlan credential stored without an ApiKeyID cannot be replayed — the update is refused rather than guessed at.

In a terminal, output defaults to structured Rich views. Pipes and redirects automatically receive standard JSON, so ov-cp list | jq ... and command substitution remain safe. Use the global --json, --output json-compact, or --output pretty flags to force a mode. Errors print Error [Code]: Message to stderr with exit code 1. ov-cp --help and ov-cp <cmd> --help work without any config.

Library-wide usage keeps EstimatedCosts for compatibility and adds EstimatedBilling. That object identifies the hourly period and CNY estimate; AgentPlan-paid collections also include the AFP amount and business scenario. Account- or user-scoped usage omits both library-wide fields. --user-id may be used alone for a user in account default.

Data spaces (accounts)

Treat an account as an enterprise-tier library's first-level isolation boundary for users, credentials, memories, resources, sessions, and skills. Treat default as the released backend's default account, so omitting --account-id preserves existing behavior. Every account-aware action sends the scope as OpenVikingAccountID. Expect a newly created data space to contain an automatically created default admin user.

Validate OpenVikingAccountID locally before sending a request; reject invalid input without a backend request or cost. Apply all of these naming rules:

• Require 1-64 characters.
• Allow only ASCII letters, digits, _, ., @, and -; reject spaces and Chinese characters.
• Reject an ID that starts with _.
• Reject . and ...
• Allow at most one @.

Respect the backend-configured per-library account quota. Treat 100 as the current default, not as a fixed limit. Treat CreateTime from account list as an opaque backend timestamp string. Never delete account default.

Use this confirmation workflow before deleting any other data space:

1. First restate the target library ResourceID, exact OpenVikingAccountID, and full destruction scope: every user, credential, memory, resource, session, and skill in the data space. Ask the user to confirm that scope.
2. After that confirmation, require the user to repeat the exact OpenVikingAccountID.
3. Compare the repeated OpenVikingAccountID exactly with the target. Never infer an OpenVikingAccountID from a keyword or partial match in account list.
4. Only after both confirmations, run ov-cp account delete <ResourceID> <OpenVikingAccountID> --yes.

Never use --yes on the first deletion step. Stop if either confirmation is missing or the repeated OpenVikingAccountID does not match exactly.

Creating a collection

⚠️ Billable + requires the account to have AgentPlan deduction activated (else ProductUnordered). Confirm with the user before creating. Max 20 libraries/account.

The public create command always uses the AgentPlan model path and the configured AgentPlan key. It does not expose model source, model parameters, model credentials, or an OpenViking image-version override.

ov-cp create --name my_kb
# enterprise tier (higher capacity, enterprise billing rates):
ov-cp create --name my_kb --version enterprise

--version is developer (default) or enterprise; any other value is rejected locally before the request.

Billing (--pay-type / --seat-id)

--version and billing are orthogonal: the tier sets the hourly RATE (developer 5 AFP baseline, enterprise 25 AFP baseline), --pay-type sets WHO PAYS. Both create and update take the same two flags (update is how you switch billing later, or re-bind after a seat was unbound).

ov-cp create --name my_kb                                    # default: personal AFP pays
ov-cp create --name my_kb --version enterprise \
  --pay-type agentplan_enterprise --seat-id seat-2026xxxx    # that seat's AFP pays
ov-cp create --name my_kb --pay-type volc_pay                # explicit website PAYG
ov-cp update <RID> --pay-type volc_pay                       # switch billing later

• Omitting --pay-type on create defaults to agentplan_personal (AFP deduction from the account's personal AgentPlan) — volc_pay (billed to the Volcano account) must be an explicit choice. ⚠️ Accounts with no personal plan (e.g. enterprise seat keys) must not rely on the default: the library binds a non-existent personal plan, deduction fails and the library is disabled. The CLI prints a note.
• The personal/enterprise choice is otherwise explicit — never guess it from the key.
• --seat-id is required with agentplan_enterprise and forbidden otherwise. The user must copy it manually from the Ark console seat-management page (no lookup API). The server does NOT verify the seat exists — a typo only surfaces at the next hourly deduction, which then disables the library.
• empty_pay (unbound) exists server-side but is not offered: such a library is unusable and auto-cleaned after 30 days.

Cold-start chain (create → use the library)

RID=$(ov-cp create --name my_kb | python3 -c 'import sys,json;print(json.load(sys.stdin)["ResourceID"])')
# Poll until provisioned; api-key times out while Status is INIT.
ov-cp get "$RID"        # wait for "Status": "READY"
ov-cp api-key "$RID"    # -> the plaintext data-plane key for the library

The returned ApiKey is the library's data-plane key. Use it as Authorization: Bearer <key> against the library's data-plane (e.g. GET {endpoint}/health, GET {endpoint}/api/v1/system/status, GET {endpoint}/api/v1/fs/ls?uri=viking://).

Notes

• Only Authorization: Bearer is accepted (no X-API-Key).
• list / get / usage are read-only; delete is destructive. Operations on an existing library may require the AgentPlan key to be associated with it.
• get/usage/api-key/delete/update and all user * take a ResourceID (e.g. ov-xxxxxxxx).
• user * manages the multiple users of an enterprise-tier library and needs the AgentPlan key to be associated with that library (else the backend rejects it). user list returns each user's masked ApiKey; for a plaintext data-plane key use api-key <ResourceID> --user-id <UserID>.
• Account operations also require the AgentPlan key to be associated with the target library.
• --account-id applies to api-key, usage, and every user * command; omitting it selects account default. usage --user-id <UserID> is valid without it.
• Scoped usage omits both EstimatedCosts and EstimatedBilling. Treat account-list CreateTime as opaque.
• Extra headers: pass -H 'Key: Value' (repeatable) or set VIKING_EXTRA_HEADERS to a comma-separated Key: Value list — e.g. -H 'x-tt-env: <swimlane>' for swim-lane routing. Authorization / Content-Type are protected and ignored.