CLI commands

@plur-ai/cli is the universal bridge. Every other adapter delegates to the same engine, so anything you can do in MCP or OpenClaw you can do from the shell. Current verified release: @plur-ai/cli@0.9.4.

This page walks each command in depth — not just signatures, but when you’d reach for it and what to expect when it works.

Install

npm install -g @plur-ai/cli@0.9.4
# or, without installing:
npx @plur-ai/cli@0.9.4 <command>

The global install is recommended for daily use — npx re-resolves every invocation, costing ~300 ms each time.

plur init

Bootstrap PLUR on this machine. This is the first command you run after installing. It is idempotent — safe to run again to repair a half-installed setup.

plur init                                            # global setup
plur init --domain myapp --scope project:my-app      # project setup

What it does

1. Initialises ~/.plur/ if missing — creates engrams.yaml, episodes.jsonl, config.yaml, and the index/ directory.
2. Detects Claude Code and installs hooks in ~/.claude/settings.json for automatic injection on SessionStart and capture on UserPromptSubmit.
3. Drops a local hook binary into ~/.plur/bin/plur-claude-hook (used by the registered hooks).
4. With --scope and/or --domain, writes .plur.yaml in the current directory so adapters pick it up automatically when you start a session here.

Flags

Flag	Default	Effect
--domain <name>	none	Default domain for engrams captured in this directory.
--scope <s>	global	Default scope, e.g. project:my-app.
--no-hooks	false	Skip Claude Code hook installation. Use when integrating manually.
--store <path>	~/.plur	Override the storage location.

Gotchas

• If ~/.plur/ exists but is corrupted, plur doctor is the right tool — init doesn’t repair.
• Running init again after a Claude Code upgrade is a quick way to refresh the hook binary.

plur learn

Save an engram. The most-used write command.

plur learn "Always validate user input at API boundaries"
plur learn "Deploys must run migrations first." \
  --type procedural \
  --domain software.deployment \
  --scope group:platform
echo "..." | plur learn -          # stdin

The CLI prints the new engram’s ID, type, and resolved scope. Save the ID if you want to give feedback or forget it later.

When to reach for it

Most of the time you don’t run plur learn by hand — the adapter’s capture hooks notice corrections and stage candidates automatically. Hand-run it when:

• You’re seeding a fresh PLUR install with conventions from a colleague’s brain dump.
• You want to commit something before a session ends (the hook only stages candidates; explicit learn creates an active engram immediately).
• You’re scripting bulk imports (pipe from a meeting transcript through to plur learn).

Flags

Flag	Default	Notes
--type	inferred	behavioral / terminological / procedural / architectural. Inference is okay; override when ambiguous.
--domain	none	Topic tag, e.g. software.git. Boosts ranking on related queries.
--scope	global (or .plur.yaml)	Where the engram applies.
--tags	none	Comma-separated keywords. Each one is a BM25 token.
--commitment	leaning	exploring (try it out) → leaning → decided → locked (pinned).
--pinned	false	Always-load. Bypasses relevance gating. Use sparingly.
--rationale	none	The “why” — surfaces alongside the statement on recall.
--locked-reason	none	Meaningful only with --commitment locked.

Gotchas

• A self-contained statement embeds better. “Always validate input at API boundaries” beats “Always do that.”
• The CLI doesn’t deduplicate — plur learn with a near-identical statement creates a separate engram. Use plur recall first if you suspect a duplicate exists.

plur recall

BM25 keyword search. Instant; no embedder needed.

plur recall "deploy migrations"
plur recall "auth" --scope project:my-app --limit 5

Use when:

• You know roughly which words appear in the engram.
• You want sub-100ms latency (no embedding pass).
• You’re scripting and need predictable token-match results.

For most queries, use plur recall-hybrid instead — it adds embedding similarity and almost always returns better results at a small latency cost.

plur recall-hybrid

The default search. BM25 + local embeddings + Reciprocal Rank Fusion.

plur recall-hybrid "how do we handle migrations"
plur recall-hybrid "auth bug" --scope project:my-app --limit 5 --json

The embeddings part means queries that don’t share keywords with the engram statement still find it: “how do we deploy?” matches an engram that says “always run migrations before rolling pods.”

Flags (shared with recall)

Flag	Default	Notes
--scope <s>	resolved from .plur.yaml or global	Filter to a scope.
--limit <n>	20	Number of results.
--domain <d>	none	Boost results in this domain.
--include-episodes	false	Also search episode summaries.
--json	false	Machine-readable output.

Gotchas

• First-ever hybrid call downloads bge-small-en-v1.5 (~50 MB). Allow a few seconds.
• If --limit is huge (>500), embedding scoring dominates latency. Stay under 100 for interactive use.

plur inject

Get the relevant engrams for a task — what an agent’s session-start hook would pre-load.

plur inject "fix the auth bug in the login flow"
plur inject "add POST /users endpoint" --json
plur inject "deploy frontend" --max-engrams 8

inject differs from recall: recall returns engrams by relevance to a query string; inject returns engrams that would be useful for a task, with budget-aware diversity (it doesn’t return five engrams that all say the same thing).

When to reach for it

• Wiring a custom agent: pipe plur inject "<task>" into the system prompt.
• Debugging what your adapter’s hook would have injected.
• Pre-flighting a query without paying for an LLM call.

Flags

Flag	Default	Notes
--max-engrams <n>	12	Hard cap on result count.
--max-tokens <n>	~2000	Token budget across the result.
--scope <s>	from .plur.yaml	Restrict to a scope.
--json	false	Structured response with score breakdown per engram.
--mode hybrid|fast	hybrid	Same modes as recall.

plur list

Enumerate engrams. A read-only inventory tool — useful for audits, migrations, and curating packs.

plur list
plur list --scope project:my-app
plur list --status candidate --limit 50
plur list --type behavioral --domain plur.brand
plur list --sort activation --json

When to reach for it

• Before a pack export: see what’s in scope.
• After a sprint: scan --status candidate to promote what stuck.
• Periodically: plur list --sort activation to see what’s actually being used.

Flags

Flag	Default	Notes
--scope, --domain, --type	none	Filters. Combine freely.
--status	active	active / dormant / retired / candidate.
--sort	last_accessed	last_accessed / activation / created / id.
--limit	100	Cap. Default is enough for inspection; set higher for full inventory.
--since 30d	none	Filter by access date. Useful for “what’s stale?” audits.
--json	false	Machine-readable.

plur forget

Retire an engram. History is preserved — forget is reversible.

plur forget ENG-2026-0525-001
plur forget --query "outdated rule" --reason "superseded by ENG-2026-0530-002"

forget doesn’t delete. The engram moves to retired and is excluded from injection; it stays on disk so you can audit it later or restore with plur engram restore <id>.

When to reach for it

• An engram is wrong, not just outdated. (Outdated engrams decay naturally; you don’t need to forget them.)
• A correction supersedes a previous one and you want the negative feedback signal to be explicit.
• You’re cleaning up after a botched bulk import.

Flags

Flag	Notes
--query <q>	Forget by content match instead of ID. Asks confirmation if multiple match.
--reason <r>	Free text. Stored on the retired engram for audit.
--yes	Skip the confirmation prompt. Use in scripts.

plur feedback

Rate an engram. The signal that trains recall.

plur feedback ENG-2026-0329-001 positive
plur feedback ENG-2026-0329-001 negative

feedback increments feedback_signals.positive or feedback_signals.negative and adjusts activation. Three positive signals roughly cancel one negative; the asymmetry is intentional — you want negative signals to be costly to override.

When to reach for it

• The engram was injected and the agent visibly used it well → positive.
• The engram was injected and was completely off-topic → negative.
• An engram surfaced ten times but only helped twice → 8 negative, 2 positive (be honest; the loop only works with truthful signal).

The implicit channel

Adapter hooks emit implicit feedback automatically — if you correct the agent right after a turn, the engrams injected for that turn get a negative implicit signal. You don’t need to also call plur feedback for the obvious cases; reserve manual feedback for nuanced calls.

plur capture

Record an episode — a timestamped event you want to remember.

plur capture "Deploy succeeded after migration fix"
plur capture "Customer X reported login issue" --channel incident
plur capture "Decided to merge PR #42" --links ENG-2026-0525-001

Episodes differ from engrams: episodes are history (what happened when), engrams are knowledge (what’s always true). Use capture to log incidents, decisions, deploys, anything you might want a timeline of later.

Flags

Flag	Notes
--channel	session / hook / incident / mcp / webhook. Filters in timeline.
--agent	Who emitted it. Defaults to the running user.
--links	Comma-separated engram IDs to associate.

plur timeline

Query the episode history.

plur timeline
plur timeline --from 2026-05-20 --to 2026-05-25
plur timeline --agent claude-code --channel incident
plur timeline --session s_8f3a92

When to reach for it

• Post-mortems: what did the agent do in the lead-up to an incident?
• Daily/weekly reviews: what got captured in the last 24 hours?
• Debugging an adapter: was plur_session_start actually called?

Flags

Flag	Notes
--from <date> / --to <date>	ISO dates or relative (7d, 1mo).
--agent <name>	Filter by emitter.
--channel <c>	Filter by channel.
--session <id>	All episodes in one session.
--limit <n>	Default 50.
--json	Structured.

plur status

Quick health check. First thing to run when something feels off.

plur status
plur status --json | jq .

Output covers: store path and size, engram count, episode count, embedder health, index status, hook installation. If any of those is red, run plur doctor for the detailed fix.

plur doctor

Detailed diagnostic with fixes. Where status says what’s wrong, doctor says how to fix it.

plur doctor

Doctor checks:

• Storage permissions on ~/.plur/.
• Embedder model present and loadable.
• Hook binary installed and executable.
• MCP config in the right place (.mcp.json, ~/.claude/settings.json, .cursor/mcp.json).
• Index consistency (rebuilds if drift detected).
• Sync remote reachable (if configured).

Each red line includes the exact command to fix it. Run doctor before opening an issue.

plur sync

Cross-machine sync via git.

plur sync --remote git@github.com:you/plur-memory.git    # first time
plur sync                                                # routine pull + push
plur sync --status                                       # show pending changes / conflicts
plur sync --resolve <id> --prefer-local                  # conflict resolution

sync is just git under the hood — ~/.plur/ is a git repo with engrams as YAML files. The CLI handles initialisation, gitignore, and conflict surfacing; you can also use bare git commands inside ~/.plur/ if you want fine-grained control.

Flags

Flag	Notes
--remote <url>	Set on first sync; remembered after.
--status	Pending changes, conflicts. Doesn’t push.
--resolve <id> --prefer-local|--prefer-remote|--fork	Manual conflict resolution.
--dry-run	Show what would be pushed/pulled.

See Sync across machines for the conceptual walkthrough.

plur packs

Knowledge Pack lifecycle — install, uninstall, export, discover.

plur packs list
plur packs install ./my-pack
plur packs install https://packs.plur.ai/community/python-style-1.0.0
plur packs install @plur-ai/datacore-conventions
plur packs uninstall my-pack
plur packs export --scope project:my-app --out ./my-pack-1.0.0 --version 1.0.0
plur packs preview <pack-url>
plur packs discover

install

Accepts a local path, URL, or scoped npm name. Verifies the pack’s integrity hash before importing. Conflicts (same engram ID already present) prompt for review — install never silently overwrites.

export

Bundles the engrams in --scope (or by --ids ENG-...,ENG-...) into a directory with a manifest. The integrity hash is computed and embedded in the manifest. See Building a Knowledge Pack.

discover

Hits the community static index. PLUR doesn’t ship a centralised registry; discovery is a list of pack URLs anyone can submit to.

preview

Lists the engrams in a pack without installing. Always preview before installing from an untrusted source.

plur stores

Remote store connections — primarily for PLUR Enterprise.

plur stores list
plur stores add --name acme --url https://plur.acme.com --token plur_sk_...
plur stores remove <name>

Remote stores let your local CLI read from and write to a PLUR Enterprise server with proper authentication. Useful even for solo use against your team’s Enterprise — you keep your global and user: engrams local, while shared group: and org: scopes live server-side. See Migrating local → Enterprise.

plur ingest

Bulk-extract engrams from arbitrary text. Meeting notes, ADRs, slack exports, transcripts.

plur ingest --from ./meeting-notes.md --domain backend
plur ingest --from ./transcript.txt --domain incident
cat transcript.txt | plur ingest -

ingest runs the extractor LLM (locally or via the configured provider) on the input, surfaces candidate engrams, and writes them with status: candidate. You then review and promote the ones worth keeping with plur promote <id>.

Flags

Flag	Notes
--from <path>	Input file. - for stdin.
--domain <d>	Apply to extracted engrams.
--scope <s>	Apply to extracted engrams.
--auto-promote	Skip the candidate stage. Risky — only on trusted input.
--dry-run	Print candidates without writing.

plur promote

plur promote ENG-2026-0525-001
plur promote --status candidate --since 7d   # bulk promote recent candidates

Moves candidate engrams to active. Bulk promotion is useful after plur ingest.

Global flags

These apply to most commands:

Flag	Effect
--json	Machine-readable output (where supported).
--quiet	Suppress non-essential output.
--verbose	Verbose logging (useful with --debug in your shell).
--store <path>	Override ~/.plur/. Sometimes useful in CI.
--scope <s>	Override scope for this invocation.
--help	Show command help.

Exit codes

Code	Meaning
0	Success
1	General failure
2	Validation error (bad input)
3	Not found
4	Permission denied
5	Embedder unavailable
64+	Adapter-specific failures

These are stable — safe for CI healthchecks like plur status --json | jq -e '.embedder.healthy' >/dev/null || exit 1.