Synopsis
groundhog --help or groundhog <COMMAND> --help for the help in an installed build.
Behavior shared by all commands
Configuration
--config <PATH> is global and defaults to ./groundhog.toml.
It can occur before or after the command.
Every command except init loads and validates the selected file before it opens deployment state.
Relative paths in the file resolve against the file’s directory.
init accepts the global option but ignores it.
Initialization always writes <DIR>/groundhog.toml.
Unknown configuration keys and invalid limits are usage errors.
The binary serves only security mode open.
serve, seal, and verify --chain support only anchor mode none.
Plain verify checks storage without enforcing the configured anchor mode.
Groundhog 0.2 rejects the removed [query] section with an exact migration instruction.
See Configuration.
Ownership and concurrency
The log has one writer.
serve and seal never bypass the writer lock.
Output and exit status
Lifecycle output and diagnostics use standard error. They are not stable parsing interfaces. Lifecycle commands produce no machine-readable standard output.verify produces one JSON document on standard output after a complete result.
init
init creates a deployment that serve can open immediately.
DIR defaults to the current directory.
Initialization creates this layout:
groundhog.toml is the deployment commit point and is written last.
An exact retry validates the deployment and does not rewrite it.
The command refuses a non-empty log without committed configuration.
It preserves unrelated entries in DIR.
It refuses unrelated entries in DIR/data.
It also refuses unexpected symbolic links and special files in the deployment paths that it manages.
It permits known Groundhog 0.1 warehouse entries in DIR/data and leaves them unchanged.
Groundhog does not create a warehouse file.
It does not modify old warehouse files during an upgrade.
Standard error reports initialized <DIR> or already initialized <DIR>.
serve
serve acquires the log writer and serves HTTP/1.1 over the configured Unix socket.
It opens only the durable log.
It never opens a TCP listener.
The service provides these routes:
If
[server].token is not empty, every request needs Authorization: Bearer <token>.
The process reports serving <socket-path> before it starts the HTTP runtime.
This message is not a readiness check.
Supervisors must wait for a successful routed request.
A live or unclassified existing socket remains untouched.
The process removes and replaces only a socket that it proves is stale.
SIGINT or SIGTERM starts a graceful shutdown.
The server stops new work and resolves queued mutations before it releases the writer.
If an ingest response is lost, retry identical content with the same batch ID.
seal
seal rotates the append tail into immutable Parquet segments.
It does not change event values, IDs, order, batch commitments, or the chain head.
Stop serve before sealing because seal needs writer ownership.
For each new segment, standard error reports:
verify
verify analyzes one coherent log inventory without changing files.
The default pass checks storage structure, segment hashes, event ranges, batches, pending generations, tail framing, order, and idempotency commitments.
--chain also recomputes each content hash, event hash, and logical history-chain value.
This option reads and hashes all event content.
Exit code 0 or 3 writes one JSON report to standard output:
orphans as non-authoritative files.
remnants are incomplete state that compatible recovery can exclude or repair.
Verification can succeed when either list is not empty.
Operational, usage, and refusal exits do not produce a JSON report.
verify --clean is not available.
Removed and unavailable commands
Groundhog 0.2 does not acceptproject or rebuild.
It does not provide a local SQL warehouse.
The binary also rejects CLI import, query, catalog, erase-payload, export-key, and verify --clean.
Use the HTTP API for ingest, replay, follow, stream enumeration, and source retirement.