Name
groundhog: maintain a Groundhog append-only event log and its embedded analytical warehouse.
Synopsis
Description
groundhog is the Groundhog binary containing a durable event log, a rebuildable DuckDB
warehouse, a Unix-socket HTTP service, and operator lifecycle commands. Connectors and applications use the
HTTP interface; operators use the CLI to initialize, serve, publish, maintain, and verify one
deployment.
One deployment is selected by groundhog.toml. Its log is the durable truth. The warehouse is
derived state that may lag the log and can be replaced by replaying it.
The current binary is local and owner-controlled. It enforces only security mode open.
Operations that would extend or attest history support integrity anchor none; they refuse a
stronger configured anchor requirement.
Global options
--config <PATH>
Selects the instance configuration. The default is ./groundhog.toml.
The option is global and may appear before or after the subcommand. Every command except init
loads it. Relative paths inside the file resolve against the configuration file’s directory.
init accepts the option because it is global, but ignores its value and writes
<DIR>/groundhog.toml.
-h, --help
Print top-level or command-specific help and exit 0.
-V, --version
Print the package version and exit 0. A release build may include a stamped source revision as
<version>+<revision>.
Commands
The cohesive commands reference owns command behavior, concurrency, output,
exit status, and examples.
Ownership and concurrency
Only
serve and seal mutate the log in the current CLI. They never bypass the one-writer rule.
project and rebuild coordinate with a separate warehouse-publication lock and publish complete
files atomically. A query already in progress remains pinned to its original generation.
Standard streams
Human lifecycle output and diagnostics go to standard error. Its exact wording and line count are not stable interfaces.init, serve, seal, project, and rebuild have no machine-readable standard output.
verify writes exactly one JSON document to standard output on exit 0 or exit 3. Help and version
requests also use standard output.
Automation should use exit status, parse only documented standard-output documents, and treat
standard error as human context.
Exit status
Configuration errors are usage failures because validation happens before deployment state is
opened. A malformed storage format found by
verify is exit 3; a non-verification command that
cannot open corrupt state is operational exit 1. Exit 4 is for a structurally classifiable but
unsupported capability or compatibility state.
Configuration
groundhog.toml controls the data directory, security mode, anchor requirement, Unix socket,
optional bearer token, query bounds, and replay bounds. Unknown keys are rejected.
See the configuration reference.
Available HTTP surface
The current service exposes:
There are no current CLI wrappers for those client operations. See the
HTTP API reference.
Unavailable names
The binary does not acceptimport, query, catalog, erase-payload, export-key, or
verify --clean. Passing one is a usage error. Unsupported commands are rejected rather than
partially performed.