Add 'bm config' command group (get/set/list) for managing config.json from the CLI

[groksrc]

Problem

Every user-facing config option today requires hand-editing ~/.config/basic-memory/config.json or knowing the BASIC_MEMORY_* env-var naming convention. There is no CLI surface for configuration at all — the immediate trigger was cli_output_style (#967): the answer to "how do I default to plain output?" is "open a JSON file in an editor."

This also hurts agents and support: docs and issue replies have to explain JSON editing instead of giving a one-line command.

Proposal

A bm config command group:

bm config list                        # all settings with current values, env overrides marked
bm config get cli_output_style
bm config set cli_output_style plain
bm config unset cli_output_style      # revert to default

Design notes:

• Validate through the model: set should round-trip through BasicMemoryConfig so invalid values fail with the Pydantic error (e.g. cli_output_style only accepts rich|plain), not get written blindly.
• Show effective values: get/list should surface when an env var is overriding the file value, since that is a classic support footgun.
• Guardrails: refuse (or require a flag) to set complex/structured fields like projects — those have dedicated commands. A small allowlist of scalar user-facing settings is fine for v1.
• Atomic writes: reuse the atomic config write path (b3bdd59 made config.json writes atomic).
• bm config list overlaps nicely with the feat(mcp): add basic_memory_diagnostics tool for version and system info #963 diagnostics tool (same redaction rules should apply: never print cloud_api_key, mask database_url credentials).

Related

• Normalize the CLI / MCP tool argument surface for v1.0 #977 (v1.0 surface normalization) — bm config should land with names that match wherever Normalize the CLI / MCP tool argument surface for v1.0 #977 settles, and a config command makes deprecation messaging easier ("set X instead").
• feat(mcp): add basic_memory_diagnostics tool for version and system info #963 — shares the redaction requirements.
• feat(cli): add Rich human-readable output to bm tool commands #967 — cli_output_style, the motivating setting.

🤖 Generated with Claude Code

[claude]

Claude finished @groksrc's task in 2m 15s —— View job

---

Triage Analysis

• Read and understand the issue
• Check for duplicate issues
• Explore codebase to assess complexity
• Add appropriate labels
• Provide triage summary

---

Classification

Dimension	Assessment
Type	Feature request — new bm config command group
Priority	Medium — usability pain point, not blocking; affects new users and agent-driven support
Component	CLI (src/basic_memory/cli/)
Complexity	Medium

Labels applied: enhancement

---

Duplicate Check

No duplicates found. Related issues explicitly referenced in the proposal are distinct:

• Normalize the CLI / MCP tool argument surface for v1.0 #977 — CLI surface normalization (this feature should land after Normalize the CLI / MCP tool argument surface for v1.0 #977 settles naming)
• feat(mcp): add basic_memory_diagnostics tool for version and system info #963 — Diagnostics tool (shared redaction requirements, not the same feature)
• feat(cli): add Rich human-readable output to bm tool commands #967 — cli_output_style (the motivating use case)

---

Codebase Assessment

The infrastructure for this feature is already in good shape:

What already exists:

• BasicMemoryConfig (Pydantic v2 BaseSettings) in src/basic_memory/config.py — ~40 scalar fields covering logging, sync, search, cloud, file handling, formatting
• ConfigManager.save_config() with atomic writes via os.replace() (added in b3bdd59)
• ConfigManager.load_config() with mtime-validated cache
• Exact command pattern in cloud/core_commands.py: load → mutate → save
• Existing command group scaffolding (see project.py, cloud/) as reference

What needs to be built:

• src/basic_memory/cli/commands/config.py — new Typer app with list, get, set, unset subcommands
• A scalar allowlist (suggest ~15 high-value user-facing fields to start: log_level, cli_output_style, kebab_filenames, disable_permalinks, sync_delay, default_search_type, format_on_save, etc.)
• Pydantic round-trip validation for set (create a temporary model to validate the value before writing)
• Env-var override indicator for get/list (check os.environ for BASIC_MEMORY_<FIELD> pattern)
• Redaction for sensitive fields: never print cloud_api_key, mask credentials in database_url
• Register the new app in src/basic_memory/cli/app.py and add "config" to the skip-init list

Design recommendation:
For v1, restrict set to the scalar allowlist and fail with a clear message for projects, formatters, and other complex types — those have dedicated commands. The allowlist also serves as a natural documentation surface.

---

Suggested Implementation Steps

1. Define the scalar allowlist as a frozenset[str] constant alongside the command
2. Add config_app = typer.Typer(...) and app.add_typer(config_app, name="config") in app.py
3. Implement list — rich table with field name, current value (masked if sensitive), and [env override] marker
4. Implement get — single field lookup with the same masking/env logic
5. Implement set — validate through BasicMemoryConfig.model_validate({field: value}) before writing
6. Implement unset — remove key from serialized dict (falls back to Pydantic default) and save
7. Add unit tests in tests/ and at least one integration test in test-int/
8. Coordinate with Normalize the CLI / MCP tool argument surface for v1.0 #977 for naming consistency before finalizing the allowlist

[phernandez]

@claude please implement this and open a PR.

Add a bm config command group exactly as specified in the issue.

Commands

• bm config list — show all user-facing scalar settings with their effective values; mark when a BASIC_MEMORY_* env var is overriding the file value.
• bm config get <key>
• bm config set <key> <value> — round-trip through BasicMemoryConfig so invalid values fail with the Pydantic validation error (e.g. cli_output_style only accepts rich|plain), never written blindly.
• bm config unset <key> — revert to the default.

Constraints

• Reuse the existing atomic config-write path (config.json writes were made atomic in b3bdd591). Do not hand-roll a new writer.
• Guardrail: refuse (or require an explicit flag) to set complex/structured fields like projects — those have dedicated commands. A small allowlist of scalar user-facing settings is fine for v1; derive it from the model where practical rather than maintaining a divergent hardcoded list.
• Redaction: never print cloud_api_key; mask credentials in database_url. Same rules as the feat(mcp): add basic_memory_diagnostics tool for version and system info #963 diagnostics work.
• Motivating setting is cli_output_style (feat(cli): add Rich human-readable output to bm tool commands #967): bm config set cli_output_style plain must work end-to-end.

Relevant code

• src/basic_memory/config.py — BasicMemoryConfig, ConfigManager, and the atomic write path.
• src/basic_memory/cli/commands/ — add a new config.py Typer command group and register it; follow an existing command like project.py for structure and registration.

Tests + docs

• Unit tests for get/set/unset/list including the validation-failure path, the env-override display, and the redaction of cloud_api_key/database_url.
• Update CLI help/docs.

Conventions: sign commits (git commit -s); PR title feat(cli): <summary>; run just fast-check and the new tests before opening the PR.

[claude]

Claude finished @phernandez's task in 20m 8s —— View job • claude/issue-991-20260716-1949 • Create PR ➔

---

Done

Todo list

• Explore codebase (config.py, cli/commands/, cli/app.py, existing command patterns)
• Design scalar allowlist derived from BasicMemoryConfig (69 fields auto-derived; only projects, formatters, auto_update_last_checked_at excluded as structured/non-scalar)
• Implement src/basic_memory/cli/commands/config.py (list, get, set, unset)
• Register command group in cli/app.py + commands __init__.py
• Implement redaction (cloud_api_key, database_url) and env-override detection
• Add unit tests (get/set/unset/list, validation failure, env override, redaction)
• Run ruff check / ruff format
• Run new tests + diagnostics regression tests + full tests/cli/tests/mcp suites
• Update docs/help (README + AGENTS.md/CLAUDE.md)
• Commit, push, open PR

Summary

Implemented bm config list|get|set|unset per the issue spec:

• src/basic_memory/cli/commands/config.py — the allowlist of settable fields (CONFIGURABLE_FIELDS) is derived from BasicMemoryConfig at import time rather than hand-maintained: any field whose type reduces to a scalar (str/int/float/bool/Literal/Enum, optionally wrapped in Optional) is included. Only 3 fields are excluded automatically: projects, formatters (dict-typed — have dedicated commands), and auto_update_last_checked_at (datetime). This yields 69 configurable settings without drifting from the model.
  • set round-trips the candidate value through BasicMemoryConfig.model_validate(...), so invalid values (e.g. bm config set cli_output_style bogus) fail with the real Pydantic error and nothing is written.
  • get/list show the effective value and flag BASIC_MEMORY_* env overrides (env always wins, matching ConfigManager.load_config's existing precedence).
  • unset reverts to the field's Pydantic default via model_fields[key].get_default().
  • Writes reuse ConfigManager.save_config, i.e. the existing atomic os.replace path from b3bdd59 — no new writer.
• src/basic_memory/redaction.py (new) — factored the secret/URL redaction rules (cloud_api_key/semantic_embedding_api_key never printed, database_url/semantic_embedding_api_base credentials masked) out of the basic_memory_diagnostics MCP tool (feat(mcp): add basic_memory_diagnostics tool for version and system info #963) into a shared module. basic_memory_diagnostics.py now imports from it (existing diagnostics tests still pass unchanged), and bm config applies the identical rules.
• Registered config in cli/app.py's skip_init_commands (like project) since it only touches config.json, not the API/DB.
• 24 new tests in tests/cli/test_config_command.py covering: allowlist derivation, get/set/unset/list happy paths, validation failures leave config.json untouched, bool coercion from CLI strings, unknown-key errors, structured-field rejection, env-override display and masking, and enum-value rendering (database_backend shows sqlite, not DatabaseBackend.SQLITE).
• Updated the CLI essentials section in README.md and the command reference in AGENTS.md/CLAUDE.md.

Verification

• ruff check / ruff format --check: clean.
• ty check (targeted + full repo): clean for all touched files; pre-existing unrelated errors elsewhere (missing markdown_it/yaml stubs, one pre-existing loguru typing issue) are untouched by this change.
• New tests: 24/24 passed.
• tests/mcp/test_tool_basic_memory_diagnostics.py: 36/36 passed (redaction refactor is behavior-preserving).
• tests/cli/: 527 passed. 18 failures are sandbox artifacts from this CI job lacking the uv binary and from an ad-hoc pip install --user substituting for uv sync (subprocess tests that spawn uv run ... or re-exec python -m basic_memory.cli.main under a monkeypatched HOME) — unrelated to this change; I don't have uv/just available in this sandbox to run the canonical just fast-check/just test-sqlite.
• tests/mcp/, tests/test_config.py, tests/test_config_load_side_effects.py: all passed (823 passed, 8 skipped).

— branch: claude/issue-991-20260716-1949