| name | forgetful-cli-setup |
| description | Set up the Forgetful CLI and connect from a terminal — install, local or remote mode, auth, and verification. Use when connecting a human or headless agent via shell, wiring CI with token auth, or operating a local server (serve, database selection, feature flags, re-embedding). Also covers the machine contract: --json output, exit codes, and the discovery ladder. |
| license | MIT |
| disable-model-invocation | true |
| tags | ["cli","setup","auth","operations","terminal"] |
| allowed-tools | ["Bash(forgetful:*)"] |
Setting up the Forgetful CLI
The CLI is the shell-native surface: same tool registry as MCP, reachable by anything that
can run a command. Setup ends with a verified round-trip, not an installed binary.
Install
uvx forgetful-ai --version
pip install forgetful-ai
Both forgetful and forgetful-ai invoke the same CLI.
Choose a mode
Connection precedence: --local > --server URL > FORGETFUL_SERVER env > local default.
- Local (default): runs in-process against the locally configured database — zero
config, no server needed. Right for a personal knowledge base on one machine.
- Remote: drives a deployed server. Interactive use:
forgetful auth login --server <url> (browser OAuth; tokens cached under ~/.config/forgetful/, server written to the
user config). Headless/CI use: set FORGETFUL_SERVER and FORGETFUL_TOKEN (bearer) in
the environment — no browser involved.
Config merges shell env over ~/.config/forgetful/.env. Check state anytime with
forgetful auth status.
Verify — the completion criterion
forgetful tools list
forgetful project list --json
Done when: both succeed against the intended target (local or the remote URL).
The machine contract
For scripts and agents, pass --json on data commands — tools, call, memory, and
project verbs: results are machine JSON, errors arrive as {"error": ...} on stderr. auth
subcommands are human-oriented and don't take --json. Exit codes are contractual — 0
success, 1 tool or runtime error, 2 usage error. Parse output, branch on exit code.
The discovery ladder
- Curated verbs for the common paths:
forgetful memory search|save|get|recent,
forgetful project list.
forgetful tools list [--category <c>] to discover every registry operation.forgetful tools info <operation> for the schema.forgetful call <operation> --args '<JSON>' to invoke anything the registry has.
The judgment for what to store, query, and link lives in the domain skills
(forgetful-remember, forgetful-recall, ...) — the ladder is how the CLI reaches the
same operations.
Operating a local server
forgetful serve --transport http --host 0.0.0.0 --port 8020 (or --transport stdio
for MCP clients that spawn a process).- Database via env:
DATABASE=SQLite with SQLITE_PATH (file) or SQLITE_MEMORY=true
(ephemeral), or DATABASE=Postgres with POSTGRES_HOST/PORT/DB/USER/PASSWORD.
- Feature flags (default off):
SKILLS_ENABLED, FILES_ENABLED, PLANNING_ENABLED —
discovery reflects whatever is enabled.
- After changing embedding provider or model:
forgetful re-embed --dry-run to preview,
then forgetful re-embed (batch size tunable via --batch-size).
Done when: /health answers (HTTP) or an MCP client lists the three meta-tools (stdio).
