CLI

The grounded command stands the service up, manages its lifecycle, prints the snippets that wire agents in, and turns add-ons on.

// A deliberate boundary

What the CLI is #

Grounded is service-first. The CLI never reads or writes your memory — that would be a second way to touch the store, drifting from the one the service enforces. Humans use the console, agents use MCP, scripts use the HTTP API, and grounded manages the process behind all three.

Getting the command

On macOS and Linux the install script puts grounded in ~/.local/bin. On Windows, Grounded Companion does the same jobs from the tray, so most people never need the command there.

// The surface

Commands #

Command	Does
`install`	Detect what the host can run, pick a backend (Docker, systemd, or a Windows scheduled task), create the cabinet, start the service and wait for `/health`. See installation.
`status`	Whether it's running, how, and its `/health`. `--port` probes another port.
`start` / `stop` / `restart`	Lifecycle for whichever backend install used.
`logs`	Service logs (`-f` to follow) via docker logs, journalctl, or the log file on Windows.
`uninstall`	Remove the service and keep the data. `--purge` also deletes the cabinet (`~/Grounded`) and config (`~/.grounded`); `-y` skips the prompt.
`init`	Create the cabinet (`~/Grounded/Cabinet`) and a default `~/.grounded/config.toml` and run migrations, without starting anything.
`migrate-cabinet`	Move an older install's data from `~/.grounded/cabinet` to `~/Grounded/Cabinet`: stops the service, moves, verifies, starts it again. Refuses if the target already holds files. `-y` skips the prompt.
`mcp install [target]`	Print a ready-to-paste MCP config (`claude-code`, `codex`, `cursor`, `generic`). Changes no files. `mcp targets` lists them.
`hooks print [target]`	Print a SessionStart hook that loads the brief at startup. Changes no files. `hooks targets` lists them.
`addon status` / `addon add <name>`	Show or turn on the optional add-ons: `embeddings` and `databox`.

// Optional extras

grounded addon #

add-ons ~

>grounded addon status

>grounded addon add embeddings

>grounded addon add databox --box cars=$HOME/boxes/cars

Option	Effect
`--device <d>`	Embeddings: `auto` (the GPU when usable, the default), `cpu` or `gpu`.
`--box <name=folder>`	Databox: add or replace a box. Repeatable.
`--description <text>`	Databox: one line about the box(es) added with `--box`.
`--no-restart`	Databox: write the config but don't restart the service.
`--port <n>`	The service port, if not 7437.
`-y`, `--yes`	No confirmation prompt.

The Embeddings add-on runs inside the service, so the service must be running. To turn an add-on off, use Companion's Add-ons page or POST /addons/:id/disable.

// Everywhere

Global flags #

--home <path> — use a Grounded home other than the default ~/.grounded (overrides GROUNDED_HOME). The default home holds config only, with your data in ~/Grounded/Cabinet; any other folder is self-contained, with its data in cabinet/ inside it.
--json — machine-readable output for scripting.
--version — print the CLI version.

Errors print error: <message> to stderr and exit non-zero.