ovdb

command module

v0.10.0 Latest Latest Go to latest Published: Sep 17, 2026 License: Apache-2.0 Imports: 36 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/openvaultdb/ovdb

Links

Open Source Insights

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.

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

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 ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
copy 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.
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.
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.
web 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.