CLI: ov
ov: read, inject, run and rotate secrets from the command line.
Read, inject and rotate OpenVireo vault secrets from scripts, CI and servers, with a service
account (OPENVIREO_SERVICE_ACCOUNT_TOKEN=ov_sa_…) or your own login. Vaults are downloaded and
decrypted locally; writes use the same conditional PUT and merge/retry loop as Qt and the web app, so
concurrent edits are merged, not lost. Runs as one binary (Bun --compile, no Node needed), or on Node ≥ 20.
Install
Section titled “Install”Each release has ov as a single binary that needs
nothing else installed (no Node), for Linux (x64, arm64), macOS (x64, arm64) and Windows (x64), with a
SHA256SUMS file and its GPG signature SHA256SUMS.asc:
v=VERSION p=linux-x64 # VERSION: the release without the v, e.g. 1.0.0; p: linux-arm64 | darwin-x64 | darwin-arm64for f in "ov-$v-$p.tar.gz" SHA256SUMS SHA256SUMS.asc; do curl -fLO "https://github.com/OpenVireo/openvireo-sdk/releases/download/v$v/$f"donegpg --verify SHA256SUMS.asc SHA256SUMS # see Verifying the binariessha256sum --ignore-missing -c SHA256SUMS # macOS: shasum -a 256 --ignore-missing -c SHA256SUMStar -xzf "ov-$v-$p.tar.gz" && sudo install "ov-$v-$p/ov" /usr/local/bin/ov versionOn Windows, in PowerShell:
$v = "VERSION"$base = "https://github.com/OpenVireo/openvireo-sdk/releases/download/v$v"foreach ($f in "ov-$v-windows-x64.zip", "SHA256SUMS", "SHA256SUMS.asc") { Invoke-WebRequest "$base/$f" -OutFile $f }gpg --verify SHA256SUMS.asc SHA256SUMS # gpg from Gpg4win(Get-FileHash "ov-$v-windows-x64.zip").Hash # compare with its line in SHA256SUMSExpand-Archive "ov-$v-windows-x64.zip" ..\ov-$v-windows-x64\ov.exe version # or put that directory on your PATHThe binary is ~60 MB (the Bun runtime) and includes the SDK’s OPAQUE WASM module, so login works without Node.
Verifying the binaries
Section titled “Verifying the binaries”SHA256SUMS.asc is signed with the OpenVireo release key, the same one as the desktop app’s releases:
fingerprint FE27 78BF 0747 05E0 994B BAF9 FEBA 3556 2DE1 04CB, from
openvireo.com/openvireo-release.asc or keys.openpgp.org
(see Verifying Signatures):
curl -sSL https://openvireo.com/openvireo-release.asc | gpg --importgpg --verify SHA256SUMS.asc SHA256SUMS # "Good signature", and the primary key fingerprint aboveThe macOS binaries are signed with OpenVireo’s Developer ID (team DP5U2UP42V) and notarized by Apple, so
Gatekeeper runs them even when downloaded with a browser. A bare executable can’t carry its notarization
ticket, so the first run checks it online. To check by hand:
codesign --verify --strict --verbose=2 ov # valid on disk, satisfies its Designated Requirementcodesign -dv ov 2>&1 | grep TeamIdentifier # TeamIdentifier=DP5U2UP42Vspctl --assess --type install -vv ov # accepted, source=Notarized Developer IDThe Windows binaries are signed with Azure Artifact Signing, the same publisher as the desktop app’s installers:
Get-AuthenticodeSignature .\ov.exe | Format-List Status, SignerCertificate, TimeStamperCertificate # Status: ValidWith Node
Section titled “With Node”@openvireo/cli is also on GitHub Packages (see Install for the registry setup) and runs
on Node ≥ 20:
npm install -g @openvireo/cliov versionTo build ov yourself, see Building from source.
References
Section titled “References”ov://<vault>/[<group>/…]<entry>/<field><vault> is a vault id or name, <entry> an entry UUID (32 hex digits) or a unique title, with the
group path from the root group. Segments are percent-encoded (Team%20Infra). Fields are KeePass’s
(username, password, url, notes, title, any case) or custom field names. Item commands take the
reference without the field.
Commands
Section titled “Commands”export OPENVIREO_SERVICE_ACCOUNT_TOKEN=ov_sa_…
ov read ov://Team%20Infra/GitHub/password # value + newline (-n: none, -o file: mode 0600)
# templates: bare references, or {{ ov://… }} when text follows the referenceecho 'dsn: postgres://app:{{ ov://Team%20Infra/Deploy/Database/password }}@db/app' | ov injectov inject -i config.yml.tpl -o config.yml # output file mode 0600
# run a command with references resolved in its environment; its stdout/stderr are maskedcat .env.tpl# DB_PASSWORD=ov://Team%20Infra/Deploy/Database/password# DB_USER="ov://Team%20Infra/Deploy/Database/username"ov run --env-file .env.tpl -- ./migrate.sh # "echo $DB_PASSWORD" prints <concealed by openvireo>GH_TOKEN=ov://Team%20Infra/GitHub/password ov run -- gh auth status # variables already set work too
ov item get ov://Team%20Infra/GitHub [--reveal] [--json]ov item list "Team Infra"ov item create ov://Team%20Infra/Apps/Stripe username=billing url=https://stripe.com --generateov item edit ov://Team%20Infra/Apps/Stripe --stdin-field api_key < key.txtov rotate ov://Team%20Infra/Deploy/Database/password --generate [--length 40] [--charset letters,digits] [--print]printf %s "$NEW" | ov rotate ov://Team%20Infra/CI/token --stdin
ov vault listov whoamiov connect # the REST server, see connect.mdov runtakesKEY=valuelines (export,#comments,"…"with\nescapes,'…'literal). Masking replaces every resolved value, and every line (4+ characters) of a multi-line value, in the child’s output, also when a value is split across writes. Bytes that may be the start of a secret are held back until the next write, or for at most 100 ms. Masking pipes the child’s stdout/stderr (they are not TTYs);--no-maskinggives it the terminal directly. The child never receivesOPENVIREO_SERVICE_ACCOUNT_TOKEN,OPENVIREO_PASSWORDorOPENVIREO_SECRET_KEY. The exit code is the child’s.item createfails if the entry exists;item editfails if it doesn’t. Password and custom fields are stored protected. Every edit keeps the previous version in the entry’s history.--generatemakes 32 characters from letters, digits and!#$%&()*+,-./:;<=>?@[]^_{|}~, at least one of each chosen set (--charsettakesletters,lower,upper,digits,symbols).- A vault granted as
readrefusesrotateanditem create|editbefore anything is uploaded:ov: this service account can only read vault "Team Infra", exit code 1. The sync server enforces the same with 403. - Errors print
ov: <message>with exit code 1 (2 for usage errors), never a stack trace.
Human login
Section titled “Human login”ov login --email alice@example.com [--issuer https://accounts.openvireo.com]# Master password, then the Secret Key (K1-…) the first time on this machine, then a TOTP code if enabledov read ov://Private/Bank/password # asks for the master password every timeov logout # add --forget to also remove the Secret Key from this machineov account delete # lock the account now, erase it after 30 daysov account restore # after `ov login`, keep an account scheduled for deletionov account delete prints what happens to each vault, organization, plan and share link, then asks you to type
the account email (--yes --email E for scripts). It refuses while you are the only owner of an organization
that has other members: make someone else an owner, or delete the organization, in the web or desktop app.
A plan bought in the iOS app is billed by Apple and only you can cancel it: ov account delete says so, and
it keeps renewing until you cancel it on your iPhone or in your Apple ID settings.
Signed in as a user, ov whoami also prints the plan and who bills it, e.g.
plan: Premium, renews 8 November 2027, billed by Apple. Manage it on your iPhone or in your Apple ID settings (…),
or … Manage it at https://accounts.openvireo.com/subscription/pricing. for a plan bought on the website.
The session (refresh token, device id, trusted Secret Key and the encrypted vault base copies) lives in
$OPENVIREO_CONFIG_DIR, else $XDG_CONFIG_HOME/openvireo, else ~/.config/openvireo, in session.json with mode 0600.
The master password is never stored. OPENVIREO_PASSWORD, OPENVIREO_SECRET_KEY and OPENVIREO_ISSUER are read from the
environment for non-interactive use; prefer a service account for automation.
OPENVIREO_SERVICE_ACCOUNT_TOKEN (or OPENVIREO_SERVICE_ACCOUNT_TOKEN_FILE) always takes precedence over a login.
Share links
Section titled “Share links”Share links open in a browser without an account (see the share links guide). Only users make them, not service accounts.
ov share ov://Private/Wi-Fi # username, password and website; 7 daysov share ov://Private/Bank --field Password --once --expires 1dov share ov://Private/Bank --field otp --passcode # asks for a passcode (or OPENVIREO_SHARE_PASSCODE)echo "The alarm code is 4321" | ov share --text --title "Front door" --expires 1hov share list # add --json for everythingov share revoke <id>The link is printed on stdout; what it allows goes to stderr. --field takes KeePass field names (UserName,
Password, URL, Notes, a custom field) or otp for the one-time code, which shares the TOTP secret.
Building from source
Section titled “Building from source”You need Node ≥ 20 and npm, and Bun 1.3 or later for the single binary:
git clone https://github.com/OpenVireo/openvireo-sdk && cd openvireo-sdknpm cinpm run build:binary -w @openvireo/cli # builds the SDK and connect, then bun build --compile … src/bin.ts --outfile dist/ov./packages/cli/dist/ov version # ov 1.0.0npm run smoke -w @openvireo/cli # runs dist/ov against the in-memory servers over HTTPCheck out a release tag (git checkout v1.0.0) to build that release rather than develop. Without Bun,
npm run build builds every package for Node, and node packages/cli/dist/bin.js runs ov.
The release archives for every platform (both ov and openvireo-connect) come from one script, which
cross-compiles, so it works on any of them:
scripts/build-binaries.sh # every release platform, both binaries, archives and SHA256SUMS in dist-binaries/scripts/build-binaries.sh --compile-only dist-binaries # the same in two stages, signing in between (as the release does):scripts/macos/sign.sh dist-binaries [identity] # macOS: hardened runtime + JIT entitlement; ad hoc without an identityscripts/build-binaries.sh --pack-only dist-binaries # archives and SHA256SUMS next to them