@dotdotgod/cli

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 shared documentation 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. Local multilingual query finds focused documentation 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

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 the dotdotgod docs/project-memory structure, local links, traceability blocks, config validity, and optional index freshness.
• index builds .dotdotgod/manifest.json and compact graph shards from maintained project files.
• query locally embeds shared Markdown with Xenova/multilingual-e5-small, incrementally stores vectors under .dotdotgod/vectors/, and returns the best-ranked chunk from each relevant Markdown file.
• 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.
• 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 communities .

Which Command Should I Use?

| Need | Command | | --- | --- | | Add the dotdotgod scaffold to a repository | dotdotgod init . | | Check docs, links, config, traceability, and optional index freshness | dotdotgod validate . --check-index | | Refresh the local graph/cache | dotdotgod index . | | Search shared project documentation locally | dotdotgod query . "project documentation" | | Resolve [[...]] references from a prompt | dotdotgod expand . "Update [[PLAN_MODE]]" | | Repair generated traceability-link sections | dotdotgod traceability links . --write | | See what else to inspect after a change | dotdotgod graph impact . --changed <path> --compact |

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.

Validation and Verification Boundaries

| Command | Responsibility | | --- | --- | | dotdotgod validate <root> | Checks dotdotgod docs/project-memory structure, local links, traceability blocks, generated traceability-link drift, config validity, and optional index freshness. | | dotdotgod traceability links <root> --check | Runs only the generated traceability-link and compact JSON drift check. | | dotdotgod traceability links <root> --write | Repairs generated traceability-link sections and rewrites canonical json dotdotgod blocks as compact JSON. | | pnpm run verify | Runs this repository's quality gate: generated-resource checks, package verify contracts, tests, typecheck, and docs validation where each package defines it. |

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.