CLI Reference

vaultguardian is the CLI wrapper installed alongside Observer. It's a thin shell around systemctl and journalctl that covers the day-to-day operations without needing to remember service names or flags.

Commands

`vaultguardian status`

Shows the current systemd service state plus the last 5 log entries.

$ vaultguardian status

● observer.service - VaultGuardian Observer
     Loaded: loaded (/etc/systemd/system/observer.service; enabled; preset: enabled)
     Active: active (running) since Tue 2026-04-22 18:40:07 UTC; 4h 12min ago
   Main PID: 2847 (observer)
      Tasks: 14 (limit: 9450)
     Memory: 42.3M
        CPU: 1.284s

Use this to confirm Observer is running and check when it last started.

`vaultguardian logs`

Tails the journalctl output for the Observer service. Equivalent to sudo journalctl -u observer -f.

$ vaultguardian logs

Apr 22 22:51:14 host observer[2847]: [ALERT] EventID=evt_0ac2...
Apr 22 22:51:14 host observer[2847]:   Source=docker:srv-captain--webapp
Apr 22 22:51:14 host observer[2847]:   Reason=SQL injection probe
Apr 22 22:51:14 host observer[2847]: [COORDINATOR] holding 3s for REC evidence
Apr 22 22:51:17 host observer[2847]: [REC] response captured: status=404
Apr 22 22:51:17 host observer[2847]: [DOWNGRADE] server returned 404, email suppressed

Exit with Ctrl+C to stop tailing. Observer's logs follow a consistent format: [STAGE] prefixes mark pipeline stages, EventID values correlate lines belonging to the same finding.

`vaultguardian stats`

Prints the most recent pipeline performance line, pattern cache stats, and REC counter.

$ vaultguardian stats

Pipeline: 174,283 events | 517 LLM calls | 0.30% miss rate
Patterns: 412 cached | 97.5% hit rate
REC: 1,847 responses captured | 29 downgrades
CatchAll: 12 verified | 3 active fingerprints

Good sanity check for whether the pipeline is healthy. A rising miss rate usually means a new application is generating novel log lines that haven't been cached yet — normal during first deployment, should plateau within hours.

`vaultguardian update [version]`

Updates the Observer binary to the latest GitHub release (default) or a specific version, then restarts the service.

$ vaultguardian update
[vaultguardian] Updating Observer...
[vaultguardian] Downloaded observer v1.0 from GitHub
[vaultguardian] Installed /usr/local/bin/observer
[vaultguardian] Observer updated and restarted

Pin a specific version:

vaultguardian update v1.0

The update preserves all state in the data directory — pattern cache, SQLite findings, trusted IPs, catch-all fingerprints. Downgrades are generally safe but not tested across schema migrations; check release notes before going backwards across a minor version.

`vaultguardian restart`

Restarts the Observer service and then tails its logs (so you see the startup sequence).

$ vaultguardian restart
[vaultguardian] Observer restarted
Apr 22 23:00:14 host observer[3012]: Observer starting (version v1.0)
Apr 22 23:00:14 host observer[3012]: Pattern store loaded: 412 patterns
Apr 22 23:00:14 host observer[3012]: Journald watcher attached
Apr 22 23:00:14 host observer[3012]: Docker socket connected: 7 containers
Apr 22 23:00:15 host observer[3012]: Pipeline ready

Use after editing /etc/vaultguardian/observer.env, or if Observer appears to be stuck.

`vaultguardian version`

Shows the currently installed Observer version plus the 5 most recent GitHub releases.

$ vaultguardian version
observer version v1.0

Recent releases:
v1.0    2026-04-22    React2Shell validation, exfil seeds
v0.37.1    2026-04-21    Fix non-HTTP dispatch
v0.37.0    2026-04-20    Hardening sprint
v0.36.3    2026-04-18    VIP lane fixes
v0.36.2    2026-04-17    Body hash migration

Useful before running vaultguardian update — you can see what you're about to get.

`vaultguardian uninstall`

Stops the service, removes the systemd unit and binary, and prompts about whether to keep state.

$ vaultguardian uninstall
[vaultguardian] This will remove Observer from this server.
[vaultguardian] Keep findings database at /var/lib/observer? [Y/n] y
[vaultguardian] Service stopped and disabled
[vaultguardian] Binary removed from /usr/local/bin/observer
[vaultguardian] systemd unit removed
[vaultguardian] Config file preserved at /etc/vaultguardian/observer.env
[vaultguardian] Data directory preserved at /var/lib/observer

Saying "keep" preserves the findings database and pattern cache, so a future reinstall starts from the same state. Saying "delete" removes everything.

Common workflows

Check that Observer is working after install

vaultguardian status      # is it running?
vaultguardian logs        # what is it doing right now?
vaultguardian stats       # is the pipeline processing events?

Update to a specific version and watch the startup

vaultguardian update v1.0
vaultguardian logs

Troubleshoot an alert that didn't fire

vaultguardian logs | grep evt_xxx          # find the event
vaultguardian logs | grep -A 5 "ALERT"     # see alert-adjacent context

Check LLM cost trend

vaultguardian stats
# Compare the LLM call count to your OpenAI usage dashboard.
# Rule of thumb: at gpt-5-nano pricing, 1000 calls ≈ $0.03

Exit codes

Code	Meaning
0	Success
1	Command syntax error or unknown subcommand
2	systemd/service error (Observer not installed or service name wrong)
3	GitHub CLI error (for `update` / `version` — usually auth)

Where the CLI lives

The vaultguardian script is installed at /usr/local/bin/vaultguardian by the installer. It's a small shell script that wraps systemctl, journalctl, and gh — nothing exotic. Read it if you want to know exactly what each command does:

cat /usr/local/bin/vaultguardian

CLI Reference

On this page