Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix: allow --sudo for ov admin commands (#1589)

MaojiaSheng09ab814af5c3
diff --git a/crates/ov_cli/src/client.rs b/crates/ov_cli/src/client.rs
index 178409fc9..9e934f07d 100644
--- a/crates/ov_cli/src/client.rs
+++ b/crates/ov_cli/src/client.rs
@@ -53,6 +53,10 @@ impl HttpClient {
self.agent_id.as_deref()
}
+ pub fn api_key(&self) -> Option<&str> {
+ self.api_key.as_deref()
+ }
+
/// Zip a directory to a temporary file
fn zip_directory(&self, dir_path: &Path) -> Result<NamedTempFile> {
if !dir_path.is_dir() {
diff --git a/crates/ov_cli/src/config.rs b/crates/ov_cli/src/config.rs
index f53e1ce14..d22217f26 100644
--- a/crates/ov_cli/src/config.rs
+++ b/crates/ov_cli/src/config.rs
@@ -27,6 +27,7 @@ pub struct Config {
#[serde(default = "default_url")]
pub url: String,
pub api_key: Option<String>,
+ pub root_api_key: Option<String>,
#[serde(alias = "account_id")]
pub account: Option<String>,
#[serde(alias = "user_id")]
@@ -63,6 +64,7 @@ impl Default for Config {
Self {
url: "http://localhost:1933".to_string(),
api_key: None,
+ root_api_key: None,
account: None,
user: None,
agent_id: None,
@@ -184,6 +186,21 @@ mod tests {
assert!(config.upload.exclude.is_none());
}
+ #[test]
+ fn config_deserializes_root_api_key() {
+ let config: Config = serde_json::from_str(
+ r#"{
+ "url": "http://localhost:1933",
+ "api_key": "user-key",
+ "root_api_key": "root-key"
+ }"#,
+ )
+ .expect("config should deserialize with root_api_key");
+
+ assert_eq!(config.api_key.as_deref(), Some("user-key"));
+ assert_eq!(config.root_api_key.as_deref(), Some("root-key"));
+ }
+
#[test]
fn config_deserializes_account_id_and_user_id_aliases() {
let config: Config = serde_json::from_str(
diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rs
index f3ff888fb..5913696da 100644
--- a/crates/ov_cli/src/main.rs
+++ b/crates/ov_cli/src/main.rs
@@ -18,6 +18,7 @@ pub struct CliContext {
pub config: Config,
pub output_format: OutputFormat,
pub compact: bool,
+ pub sudo: bool,
}
impl CliContext {
@@ -27,6 +28,7 @@ impl CliContext {
account: Option<String>,
user: Option<String>,
agent_id: Option<String>,
+ sudo: bool,
) -> Result<Self> {
let config = Config::load()?;
Ok(Self::from_config(
@@ -36,6 +38,7 @@ impl CliContext {
account,
user,
agent_id,
+ sudo,
))
}
@@ -46,6 +49,7 @@ impl CliContext {
account: Option<String>,
user: Option<String>,
agent_id: Option<String>,
+ sudo: bool,
) -> Self {
if account.is_some() {
config.account = account;
@@ -60,6 +64,7 @@ impl CliContext {
config,
output_format,
compact,
+ sudo,
}
}
@@ -68,9 +73,14 @@ impl CliContext {
}
pub fn get_client_with_timeout(&self, timeout_secs: Option<f64>) -> client::HttpClient {
+ let api_key = if self.sudo {
+ self.config.root_api_key.clone()
+ } else {
+ self.config.api_key.clone()
+ };
client::HttpClient::new(
&self.config.url,
- self.config.api_key.clone(),
+ api_key,
self.config.agent_id.clone(),
self.config.account.clone(),
self.config.user.clone(),
@@ -105,6 +115,10 @@ struct Cli {
#[arg(long = "agent-id", global = true)]
agent_id: Option<String>,
+ /// Use root API key for admin privileges
+ #[arg(long, global = true)]
+ sudo: bool,
+
#[command(subcommand)]
command: Commands,
}
@@ -425,6 +439,26 @@ enum Commands {
/// Target URI to unlink
to_uri: String,
},
+ /// [Data] Export context as .ovpack
+ Export {
+ /// Source URI
+ uri: String,
+ /// Output .ovpack file path
+ to: String,
+ },
+ /// [Data] Import .ovpack into target URI
+ Import {
+ /// Input .ovpack file path
+ file_path: String,
+ /// Target parent URI
+ target_uri: String,
+ /// Overwrite when conflicts exist
+ #[arg(long)]
+ force: bool,
+ /// Disable vectorization after import
+ #[arg(long)]
+ no_vectorize: bool,
+ },
// --- Interactive Tools ---
/// [Interactive] Interactive TUI file explorer
Tui {
@@ -489,26 +523,6 @@ enum Commands {
#[command(subcommand)]
action: SystemCommands,
},
- /// [Admin][Data] Export context as .ovpack
- Export {
- /// Source URI
- uri: String,
- /// Output .ovpack file path
- to: String,
- },
- /// [Admin][Data] Import .ovpack into target URI
- Import {
- /// Input .ovpack file path
- file_path: String,
- /// Target parent URI
- target_uri: String,
- /// Overwrite when conflicts exist
- #[arg(long)]
- force: bool,
- /// Disable vectorization after import
- #[arg(long)]
- no_vectorize: bool,
- },
/// [Admin] Reindex content at URI (regenerates .abstract.md and .overview.md)
Reindex {
/// Viking URI
@@ -522,6 +536,18 @@ enum Commands {
},
}
+impl Commands {
+ /// Returns true if this is an admin command that supports --sudo
+ fn is_admin_command(&self) -> bool {
+ match self {
+ Self::Admin { .. }
+ | Self::System { .. }
+ | Self::Reindex { .. } => true,
+ _ => false,
+ }
+ }
+}
+
#[derive(Subcommand)]
enum SystemCommands {
/// Wait for queued async processing to complete
@@ -684,6 +710,7 @@ async fn main() {
cli.account.clone(),
cli.user.clone(),
cli.agent_id.clone(),
+ cli.sudo,
) {
Ok(ctx) => ctx,
Err(e) => {
@@ -692,6 +719,18 @@ async fn main() {
}
};
+ // Check if --sudo is used but root_api_key is not configured
+ if ctx.sudo && ctx.config.root_api_key.is_none() {
+ eprintln!("Error: --sudo requires root_api_key to be configured in ~/.openviking/ovcli.conf");
+ std::process::exit(2);
+ }
+
+ // Check if --sudo is used with non-admin command
+ if ctx.sudo && !cli.command.is_admin_command() {
+ eprintln!("Error: --sudo is only supported for admin commands (admin, system, reindex)");
+ std::process::exit(2);
+ };
+
let result = match cli.command {
Commands::AddResource {
path,
@@ -934,6 +973,7 @@ mod tests {
let config = Config {
url: "http://localhost:1933".to_string(),
api_key: Some("test-key".to_string()),
+ root_api_key: None,
account: Some("from-config-account".to_string()),
user: Some("from-config-user".to_string()),
agent_id: Some("from-config-agent".to_string()),
@@ -950,6 +990,7 @@ mod tests {
Some("from-cli-account".to_string()),
Some("from-cli-user".to_string()),
Some("from-cli-agent".to_string()),
+ false,
);
assert_eq!(ctx.config.account.as_deref(), Some("from-cli-account"));
@@ -957,6 +998,48 @@ mod tests {
assert_eq!(ctx.config.agent_id.as_deref(), Some("from-cli-agent"));
}
+ #[test]
+ fn cli_context_uses_root_api_key_with_sudo() {
+ let config = Config {
+ url: "http://localhost:1933".to_string(),
+ api_key: Some("user-key".to_string()),
+ root_api_key: Some("root-key".to_string()),
+ account: None,
+ user: None,
+ agent_id: None,
+ timeout: 60.0,
+ output: "table".to_string(),
+ echo_command: true,
+ upload: Default::default(),
+ };
+
+ // Without sudo: use api_key
+ let ctx = CliContext::from_config(
+ config.clone(),
+ OutputFormat::Json,
+ true,
+ None,
+ None,
+ None,
+ false,
+ );
+ let client = ctx.get_client();
+ assert_eq!(client.api_key(), Some("user-key"));
+
+ // With sudo: use root_api_key
+ let ctx = CliContext::from_config(
+ config,
+ OutputFormat::Json,
+ true,
+ None,
+ None,
+ None,
+ true,
+ );
+ let client = ctx.get_client();
+ assert_eq!(client.api_key(), Some("root-key"));
+ }
+
#[test]
fn cli_write_rejects_removed_semantic_flags() {
let result = Cli::try_parse_from([
diff --git a/docs/en/guides/04-authentication.md b/docs/en/guides/04-authentication.md
index 5e0428952..90fd009ac 100644
--- a/docs/en/guides/04-authentication.md
+++ b/docs/en/guides/04-authentication.md
@@ -118,6 +118,40 @@ When you use a regular user key, `account` and `user` are optional because the s
openviking --account acme --user alice --agent-id my-agent ls viking://
```
+### Using --sudo with Root API Key
+
+The CLI supports configuring both `api_key` (for regular user operations) and `root_api_key` (for admin operations) in `ovcli.conf`:
+
+```json
+{
+ "url": "http://localhost:1933",
+ "api_key": "<user-key>",
+ "root_api_key": "<root-key>",
+ "account": "acme",
+ "user": "alice",
+ "agent_id": "my-agent"
+}
+```
+
+When you need to perform admin commands (`admin`, `system`, `reindex`), use the `--sudo` flag to elevate privileges:
+
+```bash
+# List all accounts (requires root privileges)
+ov --sudo admin list-accounts
+
+# Reindex content
+ov --sudo reindex viking://
+
+# System commands
+ov --sudo system status
+```
+
+The `--sudo` flag:
+- Only works with admin commands: `admin`, `system`, `reindex`
+- Will error if used with non-admin commands
+- Will error if `root_api_key` is not configured in `ovcli.conf`
+- Uses `root_api_key` instead of `api_key` for the request
+
### Accessing Tenant Data with Root Key
When using the root key to access tenant-scoped data APIs (e.g. `ls`, `find`, `sessions`), you must specify the target account and user. The server will reject the request otherwise. Admin API and system status endpoints are not affected.
diff --git a/docs/zh/guides/04-authentication.md b/docs/zh/guides/04-authentication.md
index d1e1d80e1..903df6b30 100644
--- a/docs/zh/guides/04-authentication.md
+++ b/docs/zh/guides/04-authentication.md
@@ -118,6 +118,40 @@ client = ov.SyncHTTPClient(
openviking --account acme --user alice --agent-id my-agent ls viking://
```
+### 使用 --sudo 和 Root API Key
+
+CLI 支持在 `ovcli.conf` 中同时配置 `api_key`(用于普通用户操作)和 `root_api_key`(用于管理员操作):
+
+```json
+{
+ "url": "http://localhost:1933",
+ "api_key": "<user-key>",
+ "root_api_key": "<root-key>",
+ "account": "acme",
+ "user": "alice",
+ "agent_id": "my-agent"
+}
+```
+
+当需要执行管理员命令(`admin`、`system`、`reindex`)时,使用 `--sudo` 标志提升权限:
+
+```bash
+# 列出所有账户(需要 root 权限)
+ov --sudo admin list-accounts
+
+# 重新索引内容
+ov --sudo reindex viking://
+
+# 系统命令
+ov --sudo system status
+```
+
+`--sudo` 标志:
+- 仅适用于管理员命令:`admin`、`system`、`reindex`
+- 用于非管理员命令时会报错
+- `ovcli.conf` 中未配置 `root_api_key` 时会报错
+- 请求时使用 `root_api_key` 替代 `api_key`
+
### 使用 Root Key 访问租户数据
使用 root key 访问租户级数据 API(如 `ls`、`find`、`sessions` 等)时,必须指定目标 account 和 user,否则服务端将拒绝请求。Admin API 和系统状态端点不受此限制。
diff --git a/examples/ovcli.conf.example b/examples/ovcli.conf.example
index e9d8c0b37..73d272b2e 100644
--- a/examples/ovcli.conf.example
+++ b/examples/ovcli.conf.example
@@ -1,6 +1,7 @@
{
"url": "http://localhost:1933",
"api_key": null,
+ "root_api_key": null,
"account": null,
"user": null,
"agent_id": null,
diff --git a/openviking/server/auth.py b/openviking/server/auth.py
index ec4b6f021..eaa1120cb 100644
--- a/openviking/server/auth.py
+++ b/openviking/server/auth.py
@@ -230,7 +230,7 @@ _TRUSTED_MODE_ADMIN_API_MESSAGE = (
_DEV_MODE_ADMIN_API_MESSAGE = (
"Admin API requires api_key mode with root_api_key configured. Development mode does not "
- "support account or user management."
+ 'support account or user management. You should set server.auth_mode = "api_key" in ov.conf'
)