Skip to Content

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 framework

Description

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

FlagDescription
--target <runtime>Override auto-detected runtime target (e.g., claude-code, cursor, raw)
--output <dir>Output directory (default: .)
--registryRegistry URL
--qualified-namesInstall 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-runWith 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-config

The 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.md

It 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.

KeyValuesEffect
namingplain (default), qualifiedInstall packages as {namespace}-{name} (see below)
sddnamespace/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 presentDetected target
CLAUDE.mdclaude-code
.cursorrulescursor
.github/copilot
AGENTS.mdopenai-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 kindInstall 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.md on the copilot target)
  • any other kind → .claude/includes/{name}.md (.github/includes/{name}.md on copilot, .lore/{name}/includes.md on raw)

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.md

This 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: qualified

Qualified 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.

© 2025 Lore · Built by M1 Cloud