OneGuard
ENAR

Getting started

The OneGuard CLI pulls your encrypted environment variables into a local .env file, pushes changes back, and manages vaults, secrets and team members — without leaving your terminal.

Install

macOS and Linux

OneGuard publishes from its own Homebrew repository (a "tap"), so you point Homebrew at it once:

brew tap oneguard-sa/oneguard
brew install oneguard

Or in a single command, which taps and installs together:

brew install oneguard-sa/oneguard/oneguard

Check it worked:

oneguard --version
oneguard --help
which oneguard

Windows

Chocolatey support is in progress:

choco install oneguard

Sign in

Generate an API key from the OneGuard dashboard — Vault → API Keys → Add — choose a permission and an expiry, then copy the key. It starts with og_ and is shown only once.

oneguard auth login og_your_key

The key goes into your operating system's own credential store — the Keychain on macOS, DPAPI on Windows, the Secret Service (GNOME Keyring, KWallet) on Linux. oneguard status tells you which one is in use.

Where no such store exists — a container, a bare server — the CLI falls back to ~/.oneguard/credentials.json at mode 600 and says so. On those machines, prefer the environment variable below, which stores nothing at all.

To sign out:

oneguard auth logout

In CI, containers and scripts

Set ONEGUARD_API_KEY and skip auth login entirely. Nothing is written to disk and nothing is read from it:

ONEGUARD_API_KEY=og_your_key oneguard env pull --id 84e1d2b3

This is also how the MCP server authenticates the CLI, which is why an agent session leaves no credential behind.

Key permissions

A key is created as either read or write, and the server enforces the difference:

| Permission | Can do | | --- | --- | | read | status, vault list, secrets list, env pull, env sync, teams list, logs list, and generate (which never leaves your machine) | | write | all of the above, plus creating, editing, archiving and deleting secrets and vaults, env sync --push, secrets generate, and inviting or removing members |

A read-only key used for a write is refused with a clear message. It does not sign you out — your session stays valid, you simply need a key with write permission for that action.

To see what the key you are currently using can do:

oneguard status

Machine-readable output

Any command takes a global --json flag, which replaces the prose with exactly one JSON object. The flag goes before the command:

oneguard --json vault list
oneguard --json status

{"ok":true,"vaults":[{"id":"0d8ac74c-…-…","id_prefix":"0d8ac74c","name":"oneguard-api"}],"count":1}

Three things are worth knowing:

  • Failures are JSON too, on stdout, with a non-zero exit status: {"ok":false,"error":{"code":"forbidden","message":"…"}}. The code is stable — it does not change when a message is reworded — so it is safe to branch on.
  • Ids come back whole. The human output truncates them to eight characters to stay readable; the JSON does not.
  • Values never appear. Commands that move a .env around report variable names and a count. The values go to the file and nowhere else.

oneguard env sync refuses to run its interactive vault picker under --json, since no script can answer a prompt — link the directory once without the flag, and every run after that works with it.

Upgrading

brew update
brew upgrade oneguard

To see what you are running against what is available:

oneguard --help
brew info oneguard

If brew upgrade reports nothing to do but you expect a newer version, Homebrew's copy of the tap may be stale — brew update refreshes it. To force a clean reinstall:

brew uninstall oneguard && brew install oneguard-sa/oneguard/oneguard

Running a local build

When you are working on the CLI itself, you can run your build without disturbing the installed one. Do not put it on PATH:

cd oneguard_cli
dart compile exe bin/oneguard.dart -o build/oneguard
./build/oneguard vault list

Every copy of the CLI on the machine shares one credential. To keep a test login separate, give your build a different home — the credential store entry is named after the config directory, so a different home means a different entry:

HOME=/tmp/oneguard-dev ./build/oneguard auth login og_test_key
HOME=/tmp/oneguard-dev ./build/oneguard status

Or, more simply, pass the key in the environment and store nothing:

ONEGUARD_API_KEY=og_test_key ./build/oneguard status

Either way your real session is untouched. (The first is exactly how the MCP server isolates itself.)