lore pull
Download and install a Lore package to the current project.
Usage
lore pull <namespace>/<name>:<version> [flags]
lore pull [--sdd <namespace/name[:version]>] [--dry-run] # the project's SDD frameworkDescription
Downloads the .lore archive from the registry, decompresses it, and writes platform-specific artifacts to the project directory. The target platform is auto-detected from the AI runtime present in the project.
Flags
| Flag | Description |
|---|---|
--target <runtime> | Override auto-detected runtime target (e.g., claude-code, cursor, raw) |
--output <dir> | Output directory (default: .) |
--registry | Registry URL |
--qualified-names | Install as {namespace}-{name}, so same-named packages from different namespaces coexist. Defaults to naming in .lore/config.yaml; --qualified-names=false overrides it |
--sdd <package> | With no package: install this SDD framework instead of the project’s, the org’s or the default |
--dry-run | With no package: print which SDD framework applies, install nothing |
Examples
# Pull latest version
lore pull m1cloud/azure-architect:1.0.0
# Pull with explicit target
lore pull m1cloud/azure-architect:1.0.0 --target cursor
# Pull to a specific directory
lore pull m1cloud/azure-architect:1.0.0 --output ./ai-configThe project’s SDD framework
With no package, lore pull installs the project’s SDD framework: the first one set among --sdd, the sdd key of the nearest .lore/config.yaml (up to the repository root), the org’s choice in the painel, and Lore’s default, lore/openspec.
The org is found as the governance hook finds it: --org, else the repository’s .lore.yaml (lore hooks pin --org=<org>), else LORE_ORG. This applies only to lore pull with no package; lore pull <package> scopes by --org or LORE_ORG as before.
$ lore pull
SDD framework: acme/bmad-method (org)
✓ Scaffold instruction → .claude/scaffolds/bmad-method.mdIt installs that Scaffold exactly as lore pull <package> would, on every detected target. It refuses a package that isn’t an SDD framework (a kind: Scaffold with spec.sddFramework: true) and exits non-zero. --dry-run prints the resolution without installing; lore sdd status shows every layer.
.lore/config.yaml
Project settings every lore command run in the project follows. The CLI reads it and never writes it.
| Key | Values | Effect |
|---|---|---|
naming | plain (default), qualified | Install packages as {namespace}-{name} (see below) |
sdd | namespace/name[:version] | The project’s SDD framework, overriding the org’s. The nearest file that sets it wins |
Runtime Targets
The CLI auto-detects the runtime from files in your project:
| File present | Detected target |
|---|---|
CLAUDE.md | claude-code |
.cursorrules | cursor |
.github/ | copilot |
AGENTS.md | openai-agents |
| (none) | raw |
.github/ is a weak signal — most GitHub-hosted repos have one for CI workflows or issue templates, whether or not they use Copilot customization. If a project has both .claude//.cursor/rules/ and .github/, lore pull installs for all detected targets. Use --target claude (or any other explicit target) to skip Copilot output in a repo where .github/ exists for unrelated reasons.
GitHub Copilot targets
Lore kind | Install path |
|---|---|
Skill | .github/skills/{name}/SKILL.md |
Rule | .github/instructions/{name}.instructions.md |
Spec | .github/instructions/{name}.instructions.md |
Template | .github/instructions/{name}.instructions.md |
Agent | .github/agents/{name}.agent.md |
Scaffold | .github/skills/{name}/SKILL.md (instruction only — see below) |
MCPServer | .vscode/mcp.json, under the servers key (see Authoring an MCPServer Package) |
Spec and Template collapse into the same .instructions.md format as Rule — Copilot has no native concept distinguishing them, the same reason cursor collapses all four into one .mdc format. Rule/Spec/Template/Agent get a name+description YAML frontmatter block; Skill does not (its content is already agentskills.io-compatible). Copilot instructions apply repo-wide — there’s no per-path applyTo scoping in this version.
spec.include packages
Packages whose manifest.yaml declares spec.include never get their included files extracted straight to disk. Instead, lore pull writes an instruction file alongside the package’s normal rendered output:
kind: Scaffold→.claude/scaffolds/{name}.md(.github/skills/{name}/SKILL.mdon thecopilottarget)- any other kind →
.claude/includes/{name}.md(.github/includes/{name}.mdoncopilot,.lore/{name}/includes.mdonraw)
That file lists every path declared in include: plus a lore extract command — it’s meant to be read by the AI, which runs that command to download and unpack the real files using your CLI’s own authenticated session (so private packages work too), then decides how to place them in your project (you can review the result as untracked files in git before committing, just like a normal scaffolding tool).
$ lore pull m1cloud/react-forms:1.0.0
.claude/skills/react-forms/SKILL.md
✓ Include instruction → .claude/includes/react-forms.mdThis is additive: a Skill/Rule/Agent/etc. package with spec.include still gets its normal rendered file (SKILL.md, RULE.md, …) exactly as before — the instruction file is written in addition, not instead of it.
The instruction file points at lore extract, not a bare download URL — a private package’s /raw endpoint requires authentication, and an AI correctly won’t (and shouldn’t) fetch an authenticated URL or read your credentials off disk on its own. lore extract handles that using the same session lore login/LORE_AUTH_TOKEN already set up. See lore extract.
Same-named packages from different namespaces
By default a package installs under its bare name, so nextjs/design-system and react-native/design-system both write .claude/skills/design-system/SKILL.md, and the last pull wins. To keep both, install with qualified names:
lore pull nextjs/design-system --qualified-names
lore pull react-native/design-system --qualified-names
# → .claude/skills/nextjs-design-system/SKILL.md (name: nextjs-design-system)
# → .claude/skills/react-native-design-system/SKILL.md (name: react-native-design-system)To make it the project’s default, so every later pull and every script that runs in the project follows it, add .lore/config.yaml:
naming: qualifiedQualified naming applies to every target and kind (skills, rules, specs, agents, scaffolds, include instructions) and to the dependencies installed by the same pull. A qualified Skill name must fit the 64-character limit of Claude and Copilot skill names: a longer one fails that package’s install instead of being truncated.
Provenance marker
Every file lore pull writes from a package records where it came from, right after its frontmatter (or on the first line when it has none):
<!-- lore: nextjs/design-system@1.0.1 org=laca -->org= appears only for packages from an org’s private namespaces. Files extracted from spec.include don’t get it.
Before writing, lore pull reads the marker of a file already at the target path and warns on stderr (with [WARN]) when:
- the file was installed from a different package, which it then overwrites;
- with qualified naming, the bare-name install of the same package is still there, for example from before you switched. Remove it; the CLI never deletes it;
- with qualified naming, a same-named file without a marker exists.
Upgrading the CLI adds one marker line to every file it installs, even without qualified naming. Repositories that commit installed files will see that one-time diff.