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 --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.(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 ) 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] [ARGS]. The repository is the cwd unless you pass the global --repository . 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 --repository --offline — the URL is positional (e.g. lore://local/name for an offline local repo).
• lore stage — directory paths stage only files already marked dirty; pass --scan to walk the filesystem, or mark first with lore dirty.
• lore commit '' --identity — 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 '' --identity ) requires →
2. staged files (lore stage ; check with lore status) requires →
3. a repository (lore repository create or lore clone ) requires →
4. the CLI installed (lore --version).

Online goals add: push (lore push) requires a remote + authentication (lore login ). 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 --repository --offline | | Clone a remote repo | lore clone [path] | | Show working-tree status | lore status [path...] (add --scan to reconcile from disk) | | Mark files changed (no read) | lore dirty | | Stage changes | lore stage (or lore stage --scan ) | | Stage a move/rename | lore stage move | | Unstage / reset a path | lore unstage / lore reset | | Commit staged changes | lore commit '' --identity | | Show revision history | lore history | | Diff a file (vs current revision) | lore diff | | List / create / switch branches | lore branch list / lore branch create / lore branch switch | | Push commits to remote | lore push [branch] | | Sync to a repository state | lore sync [revision] | | Lock a file | lore lock acquire | | 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 |

Quick reference — SDK

SDK operations only. These are Lore.(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 LoreArgs (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 ). When unsure, run lore --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.(...).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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ABostrom
• Source: ABostrom/lore-skill
• License: MIT
• Homepage: https://lore.org

Install and usage instructions live in the source repository linked above.