Context

The native codedb CLI is useful today for quick local checks, admin commands, snapshots, and debugging, but the primary product surface is MCP. The current CLI/docs make that distinction blurry and expose several inconsistencies.

This came up while reviewing whether the CLI is genuinely useful compared with MCP and the daemon-backed scripts/codedb-cli wrapper.

Current useful parts

• codedb mcp: primary agent interface and main product surface.
• codedb snapshot: useful for pre-indexing/reindexing and startup checks.
• codedb search, word, outline, tree: useful one-shot terminal checks.
• codedb update / nuke: useful install/admin commands.
• scripts/codedb-cli: useful as a daemon-backed human/script CLI when a warm HTTP daemon is running.

Confusing or low-value parts

• Native CLI find means symbol lookup, while MCP codedb_find means fuzzy filename search. This is confusing. Prefer symbol as the visible command and keep find as a compatibility alias.
• Native codedb --help exposes only tree, outline, find, search, word, hot, serve, mcp, update, and nuke, while README/docs mention a broader command surface.
• Native CLI does not expose several useful MCP/HTTP concepts directly: read, deps, status, changes, projects, index, glob, ls, possibly remote.
• hot is probably more useful for agents than humans; for terminal users, git status, git diff, and editor recents often cover this better.
• tree can be noisy on real repos and lacks obvious --depth, --prefix, or summary options.
• search lacks obvious terminal knobs like --max, --path, --glob, --literal, and --regex documentation beyond the README table.
• Port docs appear inconsistent: help says serve is on :7719, docs/cli.md uses CODEDB_PORT=7719, but src/main.zig currently defaults serve to 6767 when CODEDB_PORT is unset.
• The README's native CLI examples use codedb tree /path/to/project, but the implemented parser expects codedb [root] <command>, so that example order appears wrong. It should be codedb /path/to/project tree or codedb tree from the root.
• .codedb.ignore should be mentioned in user-facing help/docs once that feature lands.

Proposed direction

Position the surfaces explicitly:

codedb          one-shot/admin/debug commands
codedb mcp      primary agent interface
codedb-cli      optional daemon-backed human/script CLI

Then either:

1. Expand native codedb to include the most useful daemon/MCP commands (read, deps, status, symbol, glob, maybe ls), or
2. Keep native codedb intentionally small and make codedb-cli the documented human CLI for warm daemon usage.

Acceptance criteria

• Decide whether native codedb or scripts/codedb-cli is the preferred human CLI.
• Align README, docs/cli.md, and codedb --help around one command model.
• Fix command ordering examples for root vs command.
• Fix/document the default HTTP port for serve consistently.
• Add symbol as a visible alias for symbol lookup, or rename docs away from ambiguous find.
• Add missing useful CLI commands or explicitly document that they are MCP/daemon-only.
• Add path/scope/depth/max options where they materially improve terminal usability.
• Document .codedb.ignore in user-facing docs/help after the ignore feature lands.