Lore

lore

Lore is Epic's open-source, content-addressed version control system for code and large binary assets. Every payload, tree node, and revision is keyed by its BLAKE3 hash, so a repository is a Merkle DAG: one 32-byte root hash verifies the whole tree. Workspaces are sparse by default and hydrate fragments on demand. Lore is exposed through a single lore CLI and through Python/JavaScript/C#/Go SDKs that all bind to one C ABI — the CLI is just another consumer of that API, not a privileged one.

Verified against Lore CLI 0.8.3+201 on 2026-06-18. SDK repos: lore-python @ 4f90b7f, lore-js @ 396ad34, lore-dotnet @ a56df73, lore-go @ 91ea1c5.

Iron rules

1. Every CLI command accepts --help. Run lore <cmd> --help before guessing flags — flags differ per subcommand and Lore is pre-1.0 (it changes between minor versions).
2. Don't invent commands or SDK operations. If a verb isn't in the Quick Reference below (or reference/cli.md), or an op isn't in reference/sdk/model.md, look it up. CLI verb names are NOT the same as SDK operation names — never assume lore commit maps to a method called commit (it's revision_commit).
3. Know whether you're offline or online before acting. The --offline global flag (CLI) / offline=True global arg (SDK) is load-bearing. Local-only work (create, stage, commit, branch, diff against cached data) needs no network; push/clone/sync against a remote do. Offline mode never makes network round-trips and never lazy-fetches.
4. SDK calls bracket their lifecycle: log_configure first, shutdown last. Every operation is Lore.<op>(globals, args).callback(handler).wait(). Skipping shutdown leaks the native runtime.

Detection gate

Before doing anything, confirm the environment. If a precondition is missing, stop and tell the user — never silently fall back to git or Perforce.

• CLI work: is lore on PATH? (lore --version → expect lore 0.8.3+...). If not, it's not installed → reference/setup.md.
• In a repo? Is the cwd (or --repository <path>) a Lore repo? A repo has a .lore/ directory. lore status confirms it. If not, the user needs lore repository create / lore clone first.
• SDK work: is the language binding installed (e.g. pip install lore-vcs for Python)? The native lib must be reachable — building the Python types from source needs LORE_BUILD_PATH set to the liblore install. If the binding/lib is absent → stop and tell the user; do not hand-roll FFI.

Invocation & exit behavior

CLI. lore [GLOBAL OPTIONS] <command> [ARGS]. The repository is the cwd unless you pass the global --repository <path>. Globals (--offline, --remote, --local, --identity, --log-level, --dry-run, -f/--force, --no-pager, --non-interactive) go before the subcommand. Note real shapes that differ from git/p4:

• lore repository create <url> --repository <path> --offline — the URL is positional (e.g. lore://local/name for an offline local repo).
• lore stage <paths> — directory paths stage only files already marked dirty; pass --scan to walk the filesystem, or mark first with lore dirty.
• lore commit '<message>' --identity <id> — the message is a positional argument, not -m. A fresh install has no default identity, so --identity is required unless set in .lore/config.toml.

Exit 0 = success, non-zero = failure (commit without identity exits 1, etc.). Report the verbatim error and stop.

SDK lifecycle (Python shown; other languages share the model — see reference/sdk/model.md):

from lore import Lore
from lore.types import LoreLogConfig
from lore.types.args import LoreGlobalArgs, LoreRepositoryCreateArgs
from lore.types.enums import LoreEventTag

Lore.log_configure(LoreLogConfig(file=True, file_path=LOG))   # 1. first
Lore.global_callback(LoreEventTag.LOG, logger)                # optional: process-wide handler
g = LoreGlobalArgs(repository_path=PATH, offline=True)        # globals (offline!)
a = LoreRepositoryCreateArgs(repository_url="lore://local/x") # op-specific args
result = Lore.repository_create(g, a).callback(handler).wait()# operation: globals, args
# ... file_stage, revision_commit, (branch_push / repository_clone online) ...
Lore.shutdown()                                               # last

Goal-directed planning

When the user states a goal, work backwards to a precondition that already holds, then execute forward verifying each step:

1. Commit (lore commit '<msg>' --identity <id>) requires →
2. staged files (lore stage <path>; check with lore status) requires →
3. a repository (lore repository create <url> or lore clone <url>) requires →
4. the CLI installed (lore --version).

Online goals add: push (lore push) requires a remote + authentication (lore login <remote-url>). Verify each precondition (lore status, lore --version, .lore/ exists) rather than assuming; if one is unreachable, stop and report.

Quick reference — CLI

CLI verbs only (captured live from lore --help; full flag detail in reference/cli.md). Globals like --repository, --offline, --identity apply to all.

Want to…	Command
Check the CLI version	lore --version
Create a local (offline) repo	lore repository create <url> --repository <path> --offline
Clone a remote repo	lore clone <url> [path]
Show working-tree status	lore status [path...] (add --scan to reconcile from disk)
Mark files changed (no read)	lore dirty <paths>
Stage changes	lore stage <paths> (or lore stage --scan <dir>)
Stage a move/rename	lore stage move <src> <dst>
Unstage / reset a path	lore unstage <path> / lore reset <path>
Commit staged changes	lore commit '<message>' --identity <id>
Show revision history	lore history
Diff a file (vs current revision)	lore diff <file>
List / create / switch branches	lore branch list / lore branch create <name> / lore branch switch <name>
Push commits to remote	lore push [branch]
Sync to a repository state	lore sync [revision]
Lock a file	lore lock acquire <file>
Authenticate the CLI	lore login [remote-url]
Manage auth tokens/identities	lore auth (e.g. lore auth list)
Run / start / stop a service process	lore service run / lore service start / lore service stop
Manage links (versioned deps)	lore link (e.g. lore link list)
Manage layers (local overlays)	lore layer (e.g. lore layer list)
Manage the shared store	lore shared-store
Subscribe to notifications	lore notification subscribe
Generate shell completions	lore completions <shell>

Quick reference — SDK

SDK operations only. These are Lore.<op>(globals, args) methods — names are NOT the CLI verbs. Full surface in reference/sdk/model.md.

Want to…	Call
Configure logging (always first)	Lore.log_configure(LoreLogConfig(...))
Register a global event handler	Lore.global_callback(LoreEventTag.X, fn)
Create a repository	Lore.repository_create(g, LoreRepositoryCreateArgs(...))
Clone a repository	Lore.repository_clone(g, LoreRepositoryCloneArgs(...))
Show status	Lore.repository_status(g, LoreRepositoryStatusArgs(...))
Stage files	Lore.file_stage(g, LoreFileStageArgs(paths=...))
Unstage files	Lore.file_unstage(g, LoreFileUnstageArgs(...))
Commit a revision	Lore.revision_commit(g, LoreRevisionCommitArgs(message=...))
Revision history	Lore.revision_history(g, LoreRevisionHistoryArgs(...))
Create / switch a branch	Lore.branch_create(...) / Lore.branch_switch(...)
Push a branch	Lore.branch_push(g, LoreBranchPushArgs(...))
Sync a revision	Lore.revision_sync(g, LoreRevisionSyncArgs(...))
Acquire a file lock	Lore.lock_file_acquire(g, LoreLockFileAcquireArgs(...))
Log in interactively / with token	Lore.auth_login_interactive(...) / Lore.auth_login_with_token(...)
Start / stop a service	Lore.service_start(...) / Lore.service_stop(...)
Tear down (always last)	Lore.shutdown()

Concept clarifications

• Offline vs online mode. Offline (CLI --offline, SDK offline=True) works entirely against the local mutable + immutable store: create, stage, commit, branch, diff, switch — no round-trips, no lazy fetch (it declines rather than reaching the network). Online (--remote, a real remote URL, or default when a remote is configured) is needed for clone, push, sync, and on-demand hydration. Push converges local and remote via compare-and-swap: it succeeds atomically only if the remote still matches what the client expected.
• Global args vs op args. Every SDK operation takes two argument objects: LoreGlobalArgs (repository path, offline, connection limits — the same things the CLI's pre-command global flags set) and a per-operation Lore<Op>Args (e.g. LoreFileStageArgs(paths=...)). Don't put op-specific fields on globals or vice-versa.
• Callback / event model. Operations are asynchronous and stream typed events. You attach a handler with .callback(fn) (per-op) or Lore.global_callback(tag, fn) (process-wide), then .wait() for completion. Events are tagged by LoreEventTag (PROGRESS, ERROR, COMPLETE, LOG, END, plus hundreds of operation-specific tags); read payloads off the event object. Log verbosity is LoreLogLevel (NONE…ERROR).

Load reference when…

• Learning Lore — architecture, content-addressing/Merkle DAG, offline/online, hydration & sparse workspaces (.lore/view, .loreignore), links vs layers, glossary → reference/concepts.md
• Installing the CLI, initializing/cloning, local-vs-server setup, auth, building from source → reference/setup.md
• Full CLI command + flag detail for daily VCS work → reference/cli.md
• A CLI or SDK command failed or behaves oddly → reference/troubleshooting.md
• The universal SDK model — globals/op-args, the op(globals, args).callback().wait() lifecycle, the event/callback system, logging, shutdown → reference/sdk/model.md
• A language-specific SDK quickstart + worked example → reference/sdk/python.md, reference/sdk/javascript.md, reference/sdk/dotnet.md, reference/sdk/go.md

Anti-patterns

• Don't assume git/Perforce syntax. No -m for commit messages (positional), no git add/p4 add (it's lore dirty + lore stage, and bare directory staging needs --scan or prior lore dirty), no git init (it's lore repository create <url>). When unsure, run lore <cmd> --help.
• Don't skip shutdown. Every SDK session ends with Lore.shutdown() (and starts with log_configure), or the native runtime leaks.
• Don't forget offline mode for local-only work. If there's no remote (or you don't want network), pass --offline / offline=True; otherwise operations may try to reach a server and stall or fail.
• Don't hand-roll FFI (lore.native / the raw C ABI) when the fluent Lore.<op>(...).callback().wait() API covers the task. Drop to native only for operations the high-level API genuinely doesn't expose.
• Don't invent CLI verbs or SDK ops. If it isn't in the Quick Reference, reference/cli.md, or reference/sdk/model.md, it doesn't exist — and don't assume a CLI verb and an SDK op share a name.