Lore

---
name: lore
description: Use when working in a Lore repository; installing the Lore CLI;
  initializing or cloning a repo; running status/stage/commit/branch/push/sync;
  hydrating or configuring sparse workspaces; choosing local-vs-online (server)
  mode; authenticating with `lore login`/`lore auth`; running a local Lore
  service; using the lore-vcs (Python), lore-js, lore-dotnet, or lore-go SDK
  over their shared C ABI; or diagnosing a Lore CLI/SDK failure.
---

# 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`):

```python
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.