ovdb

command module
v0.17.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 17, 2026 License: Apache-2.0 Imports: 39 Imported by: 0

README

ovdb

ovdb is the OpenVaultDB command-line interface — the canonical developer/admin tool for creating, running, and operating an OpenVaultDB instance: user-owned, portable databases with pluggable storage engines (SQLite, inGitDB, ...).

The reference implementation and Go libraries backing this CLI live at github.com/openvaultdb/openvaultdb-go.

Install

Via Homebrew (macOS/Linux):

brew install --cask openvaultdb/tap/ovdb

Via go install (requires a Go toolchain):

go install github.com/openvaultdb/ovdb@latest

Usage

ovdb --help
  • ovdb init — create a database manifest (--id, --engine, --schema-mode, --path, --out).
  • ovdb serve — run the OpenVaultDB HTTP API server over the manifests in --dir and/or listed with --manifest. With --data-dir, new databases can also be created at runtime.
  • ovdb status — show the status of a running ovdb serve instance.
  • ovdb databases — list, and (databases create) create, databases on a running server.
  • ovdb token — manage revocable, scoped API tokens against a running server (create, list, revoke).
  • ovdb cloud — sign in to OpenVaultDB Cloud through a browser, inspect the current login, revoke it, or list safe database registration metadata (login, status, logout, databases). Credentials use the operating system keyring by default. Plaintext storage requires the explicit --insecure-storage flag.
  • ovdb self-update — check for or install a newer CLI release (alias: ovdb update). Homebrew-managed installs confirm, then run brew upgrade --cask ovdb directly without a shell; manual installs are checksum-verified and replaced atomically. --yes skips confirmation, --dry-run shows the exact action without executing it, and --version pins are supported only for manual installs because Homebrew does not guarantee arbitrary historical cask releases. Built on github.com/strongo/cli-helpers/selfupdate; its release identity (GitHub repository, supported platforms, flat checksums.txt naming, and the executable brew upgrade --cask ovdb manager) comes from ovdb's own entry in cli-helpers' compiled-in cliinstall catalog (cliinstall.ByID("ovdb").Config(...)), the single source every other fleet CLI's own install ovdb also resolves releases from.
  • ovdb install — list, show details for, and install fleet CLIs relevant to ovdb (ingitdb, datatug); see Installing related CLIs below.
  • ovdb upgrade — the fleet-wide counterpart to self-update: report or apply upgrades for every installed catalog CLI plus ovdb itself. No update alias — that alias stays reserved for self-update alone. ovdb self-update is exactly ovdb upgrade ovdb, built from the same HostConfig, so the two never disagree; see Upgrading related CLIs below.
ovdb self-update --check
ovdb self-update --check --format json
ovdb self-update
ovdb self-update --yes
ovdb self-update --dry-run
# Manual installs only:
ovdb self-update --version v0.3.0 # github.com/openvaultdb/ovdb release

ovdb install lists the other fleet CLIs relevant to OpenVaultDB (currently ingitdb, whose inGitDB engine ovdb runs directly, and datatug, which queries a running ovdb serve database as an openvaultdb catalog), each with its live installed status. ovdb install <name>... shows fuller details and installs the named CLIs the same way ovdb itself was installed: brew install --cask on a Homebrew host whose target publishes a cask for the host OS, otherwise a checksum-verified direct release download placed beside a manually installed ovdb or in the per-user bin directory. Both are entirely offline and read-only until an install is actually confirmed. Built on github.com/strongo/cli-helpers/cliinstall, whose compiled-in catalog and host → target relevance texts are the single source every other fleet CLI's own install ovdb also resolves from.

ovdb install
ovdb install --all --format json
ovdb install ingitdb --dry-run
ovdb install ingitdb datatug --yes

ovdb upgrade reports current/latest/verdict for every installed catalog CLI plus ovdb itself (not merely the relevance matrix install lists — a target that is relevant but not installed has nothing to upgrade). ovdb upgrade --all and ovdb upgrade <name>... upgrade what the report showed, after one confirmation. --check reports without applying anything; --dry-run walks the same decision path without asking. ovdb itself is always upgraded last, classified and versioned from its own self-update configuration — never a PATH probe of its own binary — so ovdb self-update and ovdb upgrade ovdb reach the exact same library call and report the same verdict. Built on github.com/strongo/cli-helpers/cliinstall's upgrade command.

ovdb upgrade
ovdb upgrade --all --check --format json
ovdb upgrade --all --dry-run
ovdb upgrade ovdb --check   # identical outcome to `ovdb self-update --check`
Owner token and access policies

For a manifest with no declared access policies (every manifest ovdb supports today), the owner token behaves exactly as before: full, unrestricted access to everything.

openvaultdb-go also supports databases that declare access policies (a layered ACL, not yet exposed by any ovdb manifest or flag). On those databases the owner token still satisfies every admin/capability check — ovdb token create|list|revoke, runtime databases create, and the --auth capability gate all keep working for the owner exactly as before — but the database's own declared access policies are still evaluated against every request, including the owner's. In other words, the owner token stops meaning "bypass all data rules" and starts meaning "administrative authority, plus whatever the declared policies allow"; a policy an owner declares on a database's data can restrict what even that owner's requests may read or write. Legacy manifests, which never declare policies, are unaffected either way.

Cloud database catalogue

ovdb cloud databases list (or ls) lists registrations in every accessible Space. Use --space personal for the personal Space, --space <id> for one Space, and --json for machine-readable data. ovdb cloud databases get <id> shows one registration. These commands need the explicit databases:read scope, which grants registration metadata only—not records or credentials. If you signed in before this scope was requested, run ovdb cloud login again.

Run ovdb <command> --help for the full flag reference of any subcommand, or ovdb version for build version/commit/date.

Development

go build -o ovdb .
go test ./...

Documentation

Overview

Command ovdb is the OpenVaultDB CLI — the canonical developer/admin interface for managing, exploring, validating and operating OpenVaultDB instances. `ovdb serve` runs the local API server.

Source Files

View all Source files

Directories

Path Synopsis
Package uicopy is the single source of every user-facing string ovdb's CLI, TUI and web console show.
 Package uicopy is the single source of every user-facing string ovdb's CLI, TUI and web console show.
internal
browser
Package browser opens a URL in the person's default browser with the platform's own opener: xdg-open on Linux and the BSDs, open on macOS, and url.dll's FileProtocolHandler through rundll32 on Windows (which, unlike `cmd /c start`, needs no quoting of & in a URL).
 Package browser opens a URL in the person's default browser with the platform's own opener: xdg-open on Linux and the BSDs, open on macOS, and url.dll's FileProtocolHandler through rundll32 on Windows (which, unlike `cmd /c start`, needs no quoting of & in a URL).
cli
Package cli is ovdb's command-line presentation of the onboarding and configuration capabilities: `ovdb server …`, `ovdb open`, `ovdb config …` and the preview `ovdb status`.
 Package cli is ovdb's command-line presentation of the onboarding and configuration capabilities: `ovdb server …`, `ovdb open`, `ovdb config …` and the preview `ovdb status`.
client
Package client is how every presentation (CLI now, TUI in 1c, and the shared rules the web console relies on) reaches the local OVDB server.
 Package client is how every presentation (CLI now, TUI in 1c, and the shared rules the web console relies on) reaches the local OVDB server.
datapath
Package datapath is the file-like path people and agents type to name a place inside a database: `/lists/to-buy/items`.
 Package datapath is the file-like path people and agents type to name a place inside a database: `/lists/to-buy/items`.
envelope
Package envelope is the one error shape every ovdb interface shares: the local API writes it, the CLI prints it (as JSON with --json, or as the "Couldn't …/Why/What you can do" problem pattern otherwise), and later the TUI and web console render it.
 Package envelope is the one error shape every ovdb interface shares: the local API writes it, the CLI prints it (as JSON with --json, or as the "Couldn't …/Why/What you can do" problem pattern otherwise), and later the TUI and web console render it.
localserver
Package localserver is the HTTP side of the local OVDB server: the hardening middleware chain, the local API (/api/local/v1/…), the landing page, and the openvaultdb-go data API (/v1/…) mounted behind them.
 Package localserver is the HTTP side of the local OVDB server: the hardening middleware chain, the local API (/api/local/v1/…), the landing page, and the openvaultdb-go data API (/v1/…) mounted behind them.
parity
Package parity is the capability registry: per row of the capability matrix in spec/features/configuration-parity, the CLI command, TUI screen, web route and local API endpoints that implement it, and the documented exceptions for the cells that are missing on purpose.
 Package parity is the capability registry: per row of the capability matrix in spec/features/configuration-parity, the CLI command, TUI screen, web route and local API endpoints that implement it, and the documented exceptions for the cells that are missing on purpose.
paths
Package paths resolves where ovdb keeps its configuration, runtime state and data, and creates those directories owner-only — but only the ones it creates itself.
 Package paths resolves where ovdb keeps its configuration, runtime state and data, and creates those directories owner-only — but only the ones it creates itself.
preview
Package preview is the single switch for ovdb's unreleased onboarding surface.
 Package preview is the single switch for ovdb's unreleased onboarding surface.
redact
Package redact removes credentials from text before it leaves the server process: error reasons, status, mounts.json and server.log lines.
 Package redact removes credentials from text before it leaves the server process: error reasons, status, mounts.json and server.log lines.
runtime
Package runtime owns the local OVDB server's process lifecycle and the files in the runtime directory: server.json, the instance secret, the home lock and server.log.
 Package runtime owns the local OVDB server's process lifecycle and the files in the runtime directory: server.json, the instance secret, the home lock and server.log.
setup
Package setup holds the onboarding and configuration services: the documents the local API returns and the pure reads that build the same documents from state files when no server is running.
 Package setup holds the onboarding and configuration services: the documents the local API returns and the pure reads that build the same documents from state files when no server is running.
setup/dbcontext
Package dbcontext is the one resolver for "which database and path does this command act on" (decision 0008, spec/features/database-context-navigation REQ:use-sets-scoped-context and REQ:context-lookup).
 Package dbcontext is the one resolver for "which database and path does this command act on" (decision 0008, spec/features/database-context-navigation REQ:use-sets-scoped-context and REQ:context-lookup).
setup/demo
Package demo is the built-in TODO demo service (spec/features/todo-demo, decision 0010): two lists, To buy and To watch, in a schemaless inGitDB database registered as `todo` at <data home>/demos/todo, and the documents `ovdb demo install|open|status`, the TUI, the web console and the TODO app render.
 Package demo is the built-in TODO demo service (spec/features/todo-demo, decision 0010): two lists, To buy and To watch, in a schemaless inGitDB database registered as `todo` at <data home>/demos/todo, and the documents `ovdb demo install|open|status`, the TUI, the web console and the TODO app render.
setup/explore
Package explore is Explore data (spec/features/explore-data-handoff): the intent-first menu that hands database access to DataTug CLI or names DataTug.app's honest limitation, never running DataTug itself.
 Package explore is Explore data (spec/features/explore-data-handoff): the intent-first menu that hands database access to DataTug CLI or names DataTug.app's honest limitation, never running DataTug itself.
setup/skills
Package skills is the AI agent skills service (spec/features/ai-agent-skills, capabilities 20 and 21): the two Agent Skills embedded from skills/, where each AI agent (harness) keeps them, and installing one skill with github.com/strongo/cli-helpers/skillsync.
 Package skills is the AI agent skills service (spec/features/ai-agent-skills, capabilities 20 and 21): the two Agent Skills embedded from skills/, where each AI agent (harness) keeps them, and installing one skill with github.com/strongo/cli-helpers/skillsync.
tui
Package tui is ovdb's terminal UI: one root Model with named screens (Home, OVDB server, Settings, Result, Problem) that call internal/client.Local exactly as the CLI does — client.Local is the single place that decides server-vs-files and mismatch rules, and every screen here goes through it rather than duplicating that logic.
 Package tui is ovdb's terminal UI: one root Model with named screens (Home, OVDB server, Settings, Result, Problem) that call internal/client.Local exactly as the CLI does — client.Local is the single place that decides server-vs-files and mismatch rules, and every screen here goes through it rather than duplicating that logic.
Package skills embeds the Agent Skills `ovdb skills install` installs (spec/features/ai-agent-skills): each directory is one skill, named as it is installed into an AI agent's skills directory.
 Package skills embeds the Agent Skills `ovdb skills install` installs (spec/features/ai-agent-skills): each directory is one skill, named as it is installed into an AI agent's skills directory.
Package web embeds the Vue console and TODO app that `pnpm -C web build` produces, so a released ovdb binary serves them with no Node runtime and no separate asset directory to ship alongside it.
 Package web embeds the Vue console and TODO app that `pnpm -C web build` produces, so a released ovdb binary serves them with no Node runtime and no separate asset directory to ship alongside it.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.