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 ten AI clients: Claude Code, OpenCode, GitHub Copilot, Codex, Cursor, Kiro, JetBrains Junie, Gemini CLI, Zed, and Amp. 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 and an MCP server install everywhere, but a rule needs a per-file scoping surface and an agent needs a shipped file format that some clients lack. Where a client cannot faithfully host a kind, grim warns and skips it (e.g. Codex, Junie, Gemini, Zed, and Amp decline rules; Kiro, Junie, Zed, and Amp decline agents). The authoritative per-client support matrix is the Client Compatibility docs page — trust it over this summary.

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

Command	Purpose	Details
grim init	Create a fresh grimoire.toml	consume
grim config	Read/write grimoire.toml settings and registries	registries
grim add	Declare an artifact and pin it in the lock	consume
grim lock	Resolve floating tags to digests	consume
grim install	Materialize the lock into AI clients	consume
grim update	Re-resolve, re-materialize, prune	consume
grim status	Report each declared artifact's state	consume
grim context	Report the resolved scope, paths, clients, registries	consume
grim fetch	Print an artifact's content without installing	consume
grim describe	Report an artifact's metadata (kind, annotations, tags) without downloading content	consume
grim remove / uninstall	Undeclare vs full inverse of install	consume
grim search / tui	Browse your declared registries' catalogs	registries
grim mcp	Run a local STDIO MCP server for AI agent integration	registries
grim build	Validate and pack locally, no push	publish
grim release	Validate, pack, push with cascade tags	publish
grim publish	Batch-release packages from a publish.toml manifest	publish
grim login / logout	Manage registry credentials	publish
grim schema	Emit the JSON Schema for grimoire.toml / publish.toml / grimoire.lock / the MCP descriptor	publish
grim completions <shell>	Print a shell completion script (bash, elvish, fish, powershell, zsh) to stdout; redirect it into your shell's completion dir	grim completions --help

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.

Git provenance: build, release, and publish can embed the publishing commit, date, and origin as OCI annotations via opt-in --git; 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]/[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. Full details and the multi-registry browse behavior in references/registries.md.

Routing Table

Read...	...when
references/consume.md	Installing, updating, or removing artifacts in a project
references/publish.md	Building, releasing, tagging, or logging in to publish
references/registries.md	Resolving registries, scopes, client targets, offline mode, or searching
references/troubleshooting.md	A grim command failed — exit codes, integrity gates, common causes
references/updating.md	Maintaining this skill itself against newer grim releases

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.