@dotdotgod/cli

Without an explicit project or global embedding profile, search uses keywords without loading/downloading models or creating vector indexes. Configured profiles enable hybrid retrieval; --search keyword always skips embeddings and unconfigured --search vector fails with setup guidance. Graph impact follows the same opt-in.

Command-line tools for dotdotgod project memory.

Use this package when you want to initialize a docs-first project scaffold, validate project-memory docs, build a local graph/cache, search full documentation and code outlines locally, expand project references, or ask what should be checked after a file changes.

These commands support dotdotgod's project-memory loop with initialization, documentation query, validation, and impact analysis for shells, scripts, CI, and agents that use the CLI directly.

What Changes

• Repository knowledge becomes navigable memory. Hybrid query finds full-document and code-outline/comment evidence and keeps the cache under .dotdotgod/.
• Project references become actionable context. resolve and expand connect explicit [[...]] references and high-signal natural-language requests to maintained files; --with-impact adds related evidence.
• Changes carry their verification neighborhood. Multi-file graph impact combines structural, traceability, package, and optional semantic evidence while preserving a per-file explanation.
• Large repositories reveal natural domains. graph communities groups the maintained project graph to help teams inspect documentation and source boundaries.
• Different knowledge shapes can share one workflow. Editable config templates initialize software or research-oriented memory policies.

Start Here

Run one command without installing globally:

npx @dotdotgod/cli validate .

Install only if you want a persistent dotdotgod command:

npm install -g @dotdotgod/cli

Common first commands:

dotdotgod init .
dotdotgod validate .
dotdotgod query . "project documentation"
dotdotgod graph impact . --changed <path> --compact
dotdotgod graph serve .

What It Does

• init creates AGENTS.md, thin agent entrypoints, docs indexes, active-plan space, archive map, local cache ignores, and the complete editable default config.
• validate checks docs/project-memory rules; --check-index also checks graph and outline freshness without parsing, embedding or repair.
• index builds graph shards and .dotdotgod/outlines.json with source hashes, declarations, comments and exact ranges.
• query defaults to hybrid vector/keyword search over full Markdown and code outlines/comments, not implementation bodies. Use --scope docs|code|all, --search hybrid|keyword|vector and --limit 30. Keyword mode works without embeddings; hybrid reports vector failures and retains keyword results. Selecting a remote embedding provider authorizes sending documentation and code metadata (names, signatures, and comments), without implementation bodies or an additional consent flag. Local E5 remains the default when its optional runtime is installed. Tree-sitter coverage and boundaries: CODE_OUTLINES.md.
• resolve and expand map explicit or high-signal prompt references to project files and can include related impact evidence.
• graph impact ranks likely related specs, tests, docs, commands, and source files for one or more changed paths, with a combined ranking and per-file top five. Non-seed scores use fixed weighted PPR connection 80 plus memory policy 20. A bounded request-local multilingual vector overlay participates in PPR when the query cache is available; vector preparation failures degrade to structural-only results.
• graph serve starts a standalone read-only traceability graph without Obsidian. It uses resolved project configuration, relation filters, document-group colors, and optional weighted line widths.
• graph export writes .dotdotgod/traceability.json for the desktop Obsidian plugin. Run it in the project/vault, then reload traceability in Obsidian. Exported paths are relative; referenced files must exist in the vault. See plugin setup.
• traceability links checks or repairs generated Markdown traceability-link sections.

Commands

dotdotgod --help
dotdotgod --version
dotdotgod init .
dotdotgod validate .
dotdotgod validate . --check-index
dotdotgod config .
dotdotgod config init .
dotdotgod config init . --template research
dotdotgod status .
dotdotgod index .
dotdotgod query . "plan mode tools"
dotdotgod resolve . PLAN_MODE
dotdotgod expand . "Update [[PLAN_MODE]] and [[HOOKS]]"
dotdotgod expand . "PLAN_MODE 수정하자" --fuzzy
dotdotgod expand . "Update [[PLAN_MODE]]" --with-impact
dotdotgod traceability links . --check
dotdotgod traceability links . --write
dotdotgod graph impact . --changed <path>
dotdotgod graph impact . --changed <path> --changed <another-path> --compact
dotdotgod graph impact . --changed <path> --changed <another-path> --yml
dotdotgod graph serve .
dotdotgod graph serve . --port 4313
dotdotgod graph communities .

Which Command Should I Use?

Changed-File Impact

$ dotdotgod graph impact . --changed packages/cli/src/core.mjs --compact

docs:
- docs/spec/CONFIG_COMMAND.md (56.8; incoming:links_to, incoming:implemented_by)
- docs/spec/cli/TRACEABILITY_LINKS.md (26.3; vector_similarity)

tests:
- packages/cli/test/core.test.mjs (6.5; verified_by)

files:
- packages/cli/src/core.mjs (100; changed-file)

graph impact needs at least one --changed <path> and accepts repeated options. Multi-file output preserves input order, deduplicates repeated paths, returns a bounded combined ranking, and includes the top five non-seed results for each changed file. Use --compact for short text, --yml or --yaml for compact structured agent-facing output, and --json for machine-readable detail.

The indexed graph is built from maintained project files: Markdown links, README routes, headings, configured traceability relations, package metadata, scripts and packaged resources, dependencies, and memory-area membership. Impact analysis can add request-local vector edges for candidate discovery and PPR without mutating that indexed graph.

Local Impact Graph Explorer

dotdotgod graph serve .

graph serve prints a local URL and binds to 127.0.0.1 by default. Set --port 4313 for a fixed port. Only loopback hosts are accepted. Use graph impact --changed <path> for changed-file ranking; the web command no longer accepts --changed. Reload refreshes project config and index data.

The explorer includes only shared indexed nodes structurally connected to a retained changed-file root. Connectivity treats stored structural edges as undirected so incoming evidence remains discoverable, while rendered arrows preserve each relation's original direction. Local-memory nodes, disconnected nodes, and request-local vector edges are excluded from the canvas and search.

Use Node reveal to choose:

• Instant — place the complete connected graph immediately.
• By hop layer — reveal the root first and then each minimum-hop layer.
• One by one — reveal nodes in deterministic breadth-first order with an automatically bounded total delay.

The browser remembers the selected mode. Skip reveal completes an active sequence immediately. Re-rooting and relation filters morph surviving nodes toward their new positions, while prefers-reduced-motion resolves every mode to immediate placement. Graph distance is layout-only and never represents impact score.

Validation and Verification Boundaries

Most users start with validate. Use traceability links --write only when generated traceability output needs repair, and use verify before release-style handoff in this repository.

Memory, Specs, and Config

The default scaffold gives docs explicit roles:

• docs/spec/**: product behavior and requirements. This path is traceability-enforced by default.
• docs/arch/**: architecture rationale, boundaries, conventions, and decisions.
• docs/test/**: verification strategy, regression coverage, fixtures, and commands.
• docs/plan/**: local active-task intent.
• docs/archive/README.md: local archive map included by default.
• docs/archive/**: local archive bodies excluded by default unless targeted.

Use memory.areas to customize memory classification and retrieval priority. Use traceability.required and traceability.exclude to select which Markdown paths need json dotdotgod blocks, and use ordered traceability.keys definitions to configure string-array labels, path or command targets, graph relations, and PPR weights. Use validation.markdown for size budgets and referenceExpansion for fuzzy prompt matching. The complete impactRanking namespace is non-blocking compatibility input: valid semantic candidate controls apply, malformed values fall back to defaults, and retired or unknown fields are ignored without changing fixed scoring. Legacy load.pinnedPaths and load.pinnedBodies values are also ignored.

Indexing Scope

dotdotgod index is gitignore-aware by default. It uses git ls-files --cached --others --exclude-standard when possible, then filters to supported text, source, script, config, web, and infrastructure files.

Default exclusions include dependency, generated, cache, and secret-like paths such as .git/, .dotdotgod/, node_modules/, dist/, build/, coverage/, .next/, target/, vendor/, .venv/, and .env. Example env templates such as .env.example remain indexable.

Learn More

See the root README, Context curation, Context mechanics, Memory area config, and Traceability config.