CLI reference

Three commands. This is the whole surface, as the built binary prints it.

`lore --help`

$ lore --help
Lorekeeper 0.1.0
Pathfinder finds the way; Lorekeeper remembers the journey.

Usage:
  lore init <dir>              Create a brain, or adopt an existing vault
  lore capture <brain> <item>  Write a thought or a URL into that brain
  lore search <brain> <query>  Rank the spans of that brain against a query
  lore --help                  Show this message
  lore --version               Print the version

A captured thought lands in inbox/ as YYYYMMDD-HHMMSS-subject.md, with the
same name as its id. Two captures in one second never collide: the second
one takes the next free -2, -3 suffix.

A captured URL lands in sources/ instead, named for the stable source id it
carries. URLs that name the same thing are one source, so capturing one you
already have reports the file that holds it and writes nothing. The URL is
identified, never visited.

Search ranks spans, not files: each result names a path, the heading it sits
under, its line range, and its score, and prints the lines themselves. Add
--json for that same result shape as JSON, or --limit to change how many
come back. A score ranks; it never proves an answer is absent.

Give several wordings of one question, each in its own quotes, and search
fuses their rankings into one list. Three wordings find what one misses,
so ask in other words rather than trusting a single phrasing. Spans that
repeat the same text in several files are reported once.

Search reads. It writes nothing, builds no index file, and works on any
directory of Markdown, whether or not lore init has run there.
Lorekeeper runs offline and takes no credentials.

`lore --version`

$ lore --version
0.1.0

Prints the version and nothing else, so scripts can read it.

`lore init <dir>`

Creates a brain at dir, or adopts the vault already there. It is safe to run again. See Knowledge structure and Existing vaults.

$ lore init
lore init: name the directory to initialize.
  lore init <target>
[exit 2]

`lore capture <brain> <item>`

Files one thought into inbox/, or one http or https URL into sources/. Quote the item. See Capture.

$ lore capture
lore capture: name the brain and what to capture.
  lore capture <brain> <item>
[exit 2]

`lore search <brain> <query>…`

Ranks the spans of brain against one or more wordings, each in its own quotes. It reads any directory of Markdown and writes nothing. See Retrieval.

$ lore search
lore search: name the brain and what to search for.
  lore search <brain> "<wording>" ["<wording>" ...] [--limit <n>] [--json]
[exit 2]

Flag	Effect
`--json`	The same results as JSON: `path`, `anchor`, `startLine`, `endLine`, `score`, `text` per result.
`--limit <n>`	How many results come back. A whole number, at least 1.

Exit codes

Code	Meaning	For example
`0`	It did what was asked. This includes a capture that found the URL already filed, and a search that matched nothing.	`lore --version`
`1`	It refused, and wrote nothing. The message says why and what to do.	`lore capture brain "a thought"`
`2`	The command was incomplete or malformed. The message repeats the usage line.	`lore search`

An argument lore does not know exits 1:

$ lore frobnicate
lore: unknown argument "frobnicate"
Run 'lore --help' to see what is available.
[exit 1]

Colour and output

At a terminal that can show colour, lore --help sets the name in the accent and closes with the serial LK-047. Nothing else is coloured, and nothing a script reads is touched: --version, --json, every error, and every run that is piped or has NO_COLOR or TERM=dumb set keeps the same bytes. Results go to standard output; refusals go to standard error.

lore runs offline, takes no credentials, and makes no network call.