CLI Command Overview

Command Tree

lore <command> [options]

Setup:
  lore init                        Initialize .lore/ config in repository
  lore doctor                      Health check: broken refs, config issues

Query (path-scoped):
  lore context <target>            Full lore summary for a code region
  lore constraints <target>        Active constraints (superseded filtered)
  lore rejected <target>           Previously rejected alternatives
  lore directives <target>         Active forward-looking warnings
  lore tested <target>             Test coverage: what was and wasn't verified
  lore why <file>:<line>           Decision context for a specific line

Query (cross-cutting):
  lore search [filters]            Search across all lore with filters
  lore log [git-log-args]          Lore-enriched git log
  lore stale [options]             Flag potentially outdated knowledge
  lore trace <lore-id>             Follow decision chain from a starting atom

Authoring:
  lore commit [options]            Create a Lore-enriched commit
  lore validate [revision-range]   Validate commits for protocol compliance

Maintenance:
  lore squash <revision-range>     Merge atoms for squash-merge preparation

Global Flags

--json                 Shorthand for --format json
--format <text|json>   Output format (default: text)
--limit <n>            Limit number of results
--since <ref|date>     Only consider commits since ref/date
--no-color             Disable colored output
--help                 Show help for command
--version              Show CLI version

Path-Scoped Query Flags

These apply to context, constraints, rejected, directives, tested:

--scope <name>         Filter by conventional commit scope instead of path
--follow               Transitively follow Related/Supersedes/Depends-on links
--all                  Include superseded/invalidated entries
--author <email>       Filter by commit author

Setup Commands

`lore init`

Creates .lore/config.toml with sensible defaults. Does not require an existing git repo (but warns if not in one). If config already exists, prints current config and exits.

$ lore init
Created .lore/config.toml with protocol version 1.0

`lore doctor`

Health check for Lore data integrity.

$ lore doctor

Checking .lore/config.toml... OK
Checking Lore-id uniqueness... OK
Checking references...
  WARNING: Lore-id 'deadbeef' referenced by a7f3b2c1 not found
Checking for orphaned atoms...
  INFO: 3 atoms have Depends-on references to superseded atoms
Checking for duplicate Lore-ids... OK

Summary: 0 errors, 2 warnings, 1 info

Query Commands

`lore context <target>`

The primary query command. Returns the full lore summary for a target: all trailer types, ordered reverse-chronologically, with superseded atoms filtered out.

This is the command an agent runs before modifying any file.

lore context src/auth/interceptor.ts --json --limit 20

`lore constraints <target>`

Returns only Constraint: trailers. Superseded atoms are filtered out by default. Use --all to see full history.

`lore rejected <target>`

Returns only Rejected: trailers. Prevents agents from re-exploring dead ends.

`lore directives <target>`

Returns only Directive: trailers. Superseded directives filtered by default.

`lore tested <target>`

Returns Tested: and Not-tested: trailers grouped together.

`lore why <file>:<line>`

Combines git blame with Lore trailer extraction for a specific line:

$ lore why src/auth/interceptor.ts:47

Line 47: } catch (err) {
── a7f3b2c1 (2026-03-15, [email protected]) ──────────────
   Intent: Prevent silent session drops during long-running operations
   Constraint: Auth service does not support token introspection
   Directive: [until:auth-v3] Error handling is intentionally broad (all 4xx)
   Confidence: high

Accepts a line range: lore why src/auth/interceptor.ts:45-80

`lore search [filters]`

Cross-cutting query with filters. Unlike other query commands, search is project-scoped, not path-scoped.

lore search --confidence low                    # all low-confidence atoms
lore search --reversibility irreversible        # all irreversible changes
lore search --scope-risk wide --since v1.2      # wide-risk since v1.2
lore search --has Directive                     # all atoms with directives
lore search --author [email protected]            # all atoms by a specific agent
lore search --text "rate limit"                 # full-text search

Search filters:

--confidence <low|medium|high>
--scope-risk <narrow|moderate|wide>
--reversibility <clean|migration-needed|irreversible>
--has <trailer-name>              Atoms that contain this trailer type
--author <email>                  Filter by commit author
--scope <name>                    Filter by conventional commit scope
--text <query>                    Full-text search across all trailer values
--since <ref|date>                Lower time/revision bound
--until <ref|date>                Upper time/revision bound
--limit <n>                       Max results

`lore log`

Lore-aware git log. Shows commits that contain Lore trailers. Passes through standard git log arguments.

lore log                          # all Lore-enriched commits
lore log --since v1.2             # since tag
lore log -- src/auth/             # scoped to path

`lore stale`

Multi-signal staleness detection. Returns atoms whose knowledge may be outdated.

lore stale                                # default heuristics
lore stale --older-than 6m                # time-based only
lore stale --drift 20                     # file had 20+ commits since atom
lore stale --low-confidence               # flag low-confidence atoms
lore stale src/auth/                      # scoped to path

Staleness signals (combined by default):

Signal	What it detects
Age	Atom older than threshold (default: 6 months, configurable)
Drift	File has had N+ commits since the atom (default: 20, configurable)
Low confidence	Atom was `Confidence: low` when written
Expired hints	Directive contains `[until:...]` with a passed date
Orphaned dependency	Atom has `Depends-on:` pointing to a superseded atom

`lore trace <lore-id>`

Follows the chain of relationships from a starting atom:

$ lore trace a7f3b2c1

a7f3b2c1 Prevent silent session drops during long-running operations
├── Related: 9c8b7a6e  Add Redis-backed session store
│   └── Supersedes: 1a2b3c4d  Use in-memory session store
└── Depends-on: e6f7a8b9  Implement auth interceptor base class

Authoring Commands

`lore commit`

Agent-first design. Default mode accepts JSON from stdin. Interactive mode via -i flag.

JSON stdin (default — agent path):

echo '{
  "intent": "Add rate limiting to token refresh",
  "trailers": {
    "Constraint": ["Rate limit: 10 req/s per client ID"],
    "Confidence": "high",
    "Scope-risk": "narrow",
    "Reversibility": "clean"
  }
}' | lore commit

Flags (quick human path):

lore commit \
  --intent "Add rate limiting to token refresh" \
  --constraint "Rate limit: 10 req/s per client ID" \
  --confidence high

Interactive (guided human path):

lore commit -i

Exit codes:

Code	Meaning
0	Commit created successfully
1	Validation error (invalid input)
2	Git error (hook failure, merge conflict)
3	No staged changes

`lore validate`

Validates commits for Lore protocol compliance. Designed for CI/CD integration. See Validation & CI for full details.

lore validate                     # validate last commit
lore validate HEAD~5..HEAD        # validate a range
lore validate --since main        # all commits since branching from main

Maintenance Commands

`lore squash <revision-range>`

Prepares a merged Lore atom for squash-merge workflows.

lore squash main..HEAD > /tmp/squash-msg.txt
# Review/edit, then:
git checkout main
git merge --squash feature-branch
git commit -F /tmp/squash-msg.txt

Merge rules:

Intent: uses the newest atom’s intent, or accepts --intent override
Array trailers: union of all values, deduplicated
Enum trailers: takes the most conservative value (lowest confidence, widest scope-risk, least reversible)
References within squash range: dropped (atoms no longer exist separately)
References outside range: preserved