Grim Usage

Grim Usage

Grimoire (binary: grim) is a package manager for AI-agent configuration. It distributes five artifact kinds — skills, rules, agents, MCP servers, and bundles — through any standard OCI registry (GHCR, Docker Hub, a private Distribution), with lockfile-pinned installs into a growing fleet of AI clients plus a vendor-neutral agents target. The current names are listed in references/registries.md; the set grows every minor release, so read it there rather than assuming. An MCP server artifact installs by registering an entry in each client's native MCP config file (never as a file of its own); uninstall removes only that entry, never the file.

Not every client can host every kind: a skill is the one kind every client hosts, but a rule needs a per-file scoping surface, an agent needs a shipped file format, and an MCP server needs a config file grim can splice — and many clients lack one or more of those. Where a client cannot faithfully host a kind, grim warns and skips it, writing zero files. Most of the fleet declines rules and agents, and the skills-only clients write no MCP config at all. The authoritative per-client support matrix is the Client Compatibility docs page — trust it over this summary, and check it rather than assuming.

Two consequences of that shape are worth knowing before your first install. When nothing is detected, grim targets the generic agents client — one copy into the shared .agents/skills pool — rather than writing a directory for every client it knows about; a lock holding only rules, agents, or MCP servers then has nowhere to go and exits 78. And a client that reads that shared pool can be moved into it deliberately with options.vendors.<name>.shared_skills. Both in references/registries.md.

Verify Before Acting

Before composing any non-trivial grim command:

1. Run grim --version. This guide tracks the release it ships beside; on a different minor, treat every flag mentioned here as a hypothesis.
2. Run grim <command> --help before using flags you have not verified this session — it is the authoritative, always-current flag list.
3. On any conflict between this skill and live --help output, trust --help. It ships with the binary; this guide can lag.

These pages teach workflows and semantics, never exhaustive flags. The full reference is --help plus the docs site linked below.

Command Map

Deprecation: a publisher can retire a package without unpublishing it; add and status flag it as deprecated (an add of a deprecated reference still succeeds). search and tui hide deprecated artifacts by default unless they are installed — reveal them with grim search --show-deprecated, the TUI h key, or by setting options.show_deprecated = true (grim config set options.show_deprecated true). A replaced-by successor reference, when the publisher named one, surfaces in grim search / grim describe. See Publishing.

Build provenance: build, release, and publish embed the publishing commit and its date as OCI annotations by default (never a wall-clock time, so re-release stays idempotent). --git additionally requires them and discloses the origin remote and commit author; --no-git suppresses every derived annotation. Confirm with grim release --help.

Global flags apply to every subcommand — --format, --global, --config, --registry, --offline, --log-level, and --color <auto|always|never> (default auto colorizes clap's help/error output and --format json only when stdout is a terminal; --color always colorizes unconditionally, so never pass it into a pipeline that parses the document. The JSON error document is never colorized in any mode). Confirm the set with grim --help.

Reference Syntax

An artifact is named registry/repository:tag (a floating tag — :1 follows the newest 1.x release) or registry/repository@sha256:… (an immutable digest). A bare reference defaults to :latest.

A third form skips the registry: a local path — ./skills/x, ../shared/rule.md, or an absolute path — names a directory or file on disk directly. The discriminant is used everywhere a reference is accepted (grim add, grim install, a [skills]/[rules]/[agents]/[mcp]/[bundles] value): a value starting with ./ or ../, or an absolute path, is a local path source; anything else is an OCI reference. See references/consume.md for how it is declared and installed.

A short reference with no registry resolves against the default registry — --registry flag, then GRIM_DEFAULT_REGISTRY, then config, then the built-in fallback registry ghcr.io/grimoire-rs; full precedence in references/registries.md. Browsing with nothing configured (grim search, grim tui, grim mcp) falls back to the public package index at https://index.grimoire.rs instead — see references/registries.md.

When a config declares [[registries]] with aliases, a qualified reference alias/repo[:tag] expands the alias to its configured URL — for example acme/code-review:1 becomes ghcr.io/acme/code-review:1 when acme is aliased to ghcr.io/acme. This only works for an oci-type alias. An index-type alias fails with exit 65. Full details and the multi-registry browse behavior in references/registries.md.

Routing Table

Further Reading

• Command reference — every command with current flags.
• Concepts — kinds, references, the lock, bundles, scopes, clients.
• Configuration — grimoire.toml, grimoire.lock, environment variables.
• Publishing — the author-to-release workflow.
• Authentication — credential store, login/logout, CI recipes.

Verified against the grim release this package ships beside.