Reference

Commands

Eleven commands. Six read the notes, four write them, and init sets a repo up. Anywhere a command takes a note, give its name, spec/auth or decision/0002, or a filename, path, alias or number that names only one note.

Overview

Command	What it does
`context <file>…`	The notes that govern these files, most relevant first.
`show <note>`	A note with its history, links, backlinks, citations, anchors and checklist.
`list`	Every note, one per line.
`check`	Every problem with the notes. Exits 1 if there is one.
`next`	What to do next, and the skill that does it.
`graph [<note>]`	The notes as an interactive graph, one HTML page.
`new <type> <title>`	Create a note from the type’s template.
`set <note> <field>=<value>…`	Change fields, checked against the schema.
`tick <note>`	Tick the first open checklist item.
`freeze <note>`	Record the version of every spec a note links to.
`init`	Write `.lore/` and check the skills are installed.

Each command takes only the flags listed under it, and --json. Any other flag is an error, so a typo fails rather than being ignored:

lore list --sumaries
lore list: list takes no --sumaries (flags: --type, --summaries, --json)

`lore context <file>…`

The notes that govern one or more files: code citations, symbol anchors, path anchors from most specific, CONTEXT.md files from nearest, then notes one frontmatter link away. Each says why it matched.

--full: Include each note’s body.
--budget <tokens>: Cap the output. The default is 4000.
--session <id>: Only notes this session has not been shown, or that changed since. Prints nothing when there are none. Used by the agent hook.
--forget: With --session, start the session over.

~/app

lore context --full pkg/billing/charge.ts
pkg/billing/charge.ts: 1 note

Money is integer cents  (Decision, accepted)
  docs/decisions/0003-money-is-integer-cents.md
  matched: cited at charge.ts:1; anchor pkg/billing/**
  Money is a whole number of cents everywhere, converted to dollars only for display.

    # Money is integer cents

    ## Context
    Floating-point dollars round differently on the server and in the browser.

    ## Decision
    Money is a whole number of cents everywhere, converted to dollars only for display.

    ## Consequences
    Every price field is an integer, and its name ends in `Cents`.

`lore show <note>`

Everything lore knows about one note: its supersede history, links out, links in, the code that cites it, what its anchors match, and checklist progress.

~/app

lore show effort/due-dates
Due dates  (Effort, active)
docs/efforts/due-dates.md
Store the day as a real date column, sort in the query, and colour in the list view.
Checklist: 1 of 3 done

Links to:
  specs: spec/due-dates → docs/specs/due-dates.md

A decision with history shows the whole chain; see Superseding.

`lore list`

--type <type>: Only notes of this type.
--summaries: Add each note’s summary. With it, an agent can find notes by meaning without embeddings.

~/app

lore list --summaries
docs/decisions/0001-hard-expiry.md  Hard expiry  (Decision, superseded)
  Every session hard-expires after 15 minutes.

docs/decisions/0002-rotating-refresh-tokens.md  Rotating refresh tokens  (Decision, accepted)
  Refresh tokens rotate on every use; access tokens last 15 minutes.

docs/decisions/0003-money-is-integer-cents.md  Money is integer cents  (Decision, accepted)
  Money is a whole number of cents everywhere, converted to dollars only for display.

docs/efforts/due-dates.md  Due dates  (Effort, active)
  Store the day as a real date column, sort in the query, and colour in the list view.

docs/specs/auth.md  Auth  (Spec, accepted)
  Who can sign in, how, and for how long.

docs/specs/due-dates.md  Due dates  (Spec, accepted)
  A task can have a day it is due, and overdue tasks stand out.

pkg/auth/CONTEXT.md  Auth package
  Owns session issuance and validation. Never import from pkg/billing.

`lore check`

Reports broken or ambiguous links and citations, citations of superseded decisions, anchors that match nothing, schema violations, superseding mistakes, and specs that changed under an effort that is not done. Exits 1 when it finds a problem, so it belongs in CI.

~/app

lore check
docs/specs/search.md:3: 'status' is 'finished'; expected one of draft, accepted, retired
docs/specs/search.md:7: link 'spec/indexing' matches no note
pkg/billing/charge.ts:6: citation 'lore:decision/0009' matches no note

8 notes, 3 citations: 3 problems

And with nothing to report:

~/app

lore check
7 notes, 2 citations: no problems

`lore next`

Reads spec and effort state and ranks what to do, naming the lore-* skill that does it. In order: a spec that changed under an effort, an effort ready to ship, the next open task, an effort not yet planned or frozen, an accepted spec with no effort, a draft spec.

~/app

lore next
next: lore-build docs/efforts/due-dates.md
  Due dates  (Effort, active)
  1 of 3 done
  next item: Show a date picker when editing a task

When it says	It means
`lore-plan` … changed since it was planned	A spec moved under an effort; the tasks may be stale.
`lore-ship` … all items done	Every task is ticked; the effort needs closing.
`lore-build` … next item	Work to do: the first open task.
`lore-plan` … planned but not frozen	An effort exists but has not been agreed and frozen.
`lore-plan` … accepted spec with no effort	An accepted spec nobody has planned.
`lore-spec` … draft spec	A spec still being worked out.

`lore graph [<note>]`

Writes the notes as one HTML page you open in a browser: an interactive graph of specs, efforts and decisions and the links between them, for people who would rather look than run commands. It prints the page’s path. The page needs nothing else, no server and no network, so you can send it to someone or publish it.

--out <file>: Write the page here. Without it, lore-graph.html in the temp directory.
--depth <n>: With a note, how many links out from it to show (default 2).
--open: Open the page in the browser.

~/app

lore graph --open
/tmp/lore-graph.html
lore graph spec/due-dates --depth 1 --out docs/graph.html
/home/you/app/docs/graph.html

Notes are coloured by type. A superseded or retired note is faded, a draft is hollow, and an effort whose spec changed under it has a red ring. A link to a note that does not exist shows as a faint dashed node. The code layer, off until you tick it, adds the code that anchors claim and the files that cite notes.

Click a note to read it in the side panel, with what it links to and what links to it; Focus here narrows the graph to the notes near it. Given a note, lore graph opens focused on it. The address keeps what you are looking at, so you can share a link to it: #note=spec/due-dates, #focus=spec/due-dates&depth=1, #code. Press / to search, Esc to close the panel or leave focus, and the arrow keys and Enter to follow the open note’s links.

The same notes always give the same page, byte for byte, so a page published from CI changes only when the notes do. --json prints the graph’s nodes and edges instead, for other front ends.

`lore new <type> <title>`

Creates a note in the type’s directory from .lore/templates/<Type>.md (or .org), numbered if the type has an id, starting at the first status in its enum.

--supersedes <note>: Mark that note superseded and move its anchors to the new one. Repeatable.
--link <field>=<note>: Link a note in a field, for example specs=auth. Repeatable.

~/app

lore new Decision "Store due dates as dates"
created docs/decisions/0004-store-due-dates-as-dates.md
lore new Effort "Due dates" --link specs=spec/due-dates
created docs/efforts/due-dates.md

`lore set <note> <field>=<value>…`

Changes fields in place, after checking each value against the schema: enums, types, and links that must name exactly one note of the right type. field+=value adds to a list field. Superseding is left to lore new --supersedes.

~/app

lore set effort/due-dates status=active
updated docs/efforts/due-dates.md
  status: active

`lore tick <note>`

Ticks the first open checklist item and names the next, or says every item is done. Items inside code blocks are skipped.

~/app

lore tick effort/due-dates
ticked docs/efforts/due-dates.md: Add a due_date column to tasks, with a migration
next: Show a date picker when editing a task  (1 of 3 done)

`lore freeze <note>`

Records the current version of every spec the note links to, through the fields the schema lists under freeze. From then on check reports when one changes.

~/app

lore freeze effort/due-dates
froze docs/efforts/due-dates.md against:
  docs/specs/due-dates.md 34dd79dc3cec

`lore init`

Writes .lore/: the default schema, a template per type, and a WORKFLOW.md the skills read first. Keeps any file already there, and says how to install the skills if they are missing.

~/app

lore init
created .lore/schema.yml
created .lore/WORKFLOW.md
created .lore/templates/Spec.md
created .lore/templates/Decision.md
created .lore/templates/Effort.md

skills: found in ~/.claude/skills, ~/.agents/skills

Read .lore/WORKFLOW.md, then start a spec with lore-spec.

`--json`

Every command but help and version takes --json. It is the interface editors and scripts build on; the Emacs package uses nothing else. Every note in it, in list, context, next and show, has its path, name, title, type and status; a command adds its own fields beside them.

~/app

lore context --json pkg/billing/charge.ts
{
  "files": [
    "pkg/billing/charge.ts"
  ],
  "notes": [
    {
      "path": "docs/decisions/0003-money-is-integer-cents.md",
      "name": "decision/0003-money-is-integer-cents",
      "title": "Money is integer cents",
      "type": "Decision",
      "status": "accepted",
      "summary": "Money is a whole number of cents everywhere, converted to dollars only for display.",
      "matched": [
        "cited at charge.ts:1",
        "anchor pkg/billing/**"
      ],
      "supersedes": []
    }
  ]
}