grim-usage
Drive the grim CLI — the OCI package manager for AI skills, rules, agents, MCP servers, hooks, and bundles. Use when installing, updating, searching, rating, or publishing AI-config artifacts with grim; when composing grim init, config, add, lock, install, update, status, context
#agents #mcp
Install
npx skills add https://github.com/grimoire-rs/grimoire/tree/main/catalog/skills/grim-usage
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install grimoire-rs-grimoire@llmmart
git clone https://github.com/grimoire-rs/grimoire.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole grimoire-rs/grimoire collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Grim Usage
Grimoire (binary: grim) is a package manager for AI-agent configuration.
It distributes six artifact kinds — skills, rules, agents,
MCP servers, hooks, 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, but agents are hosted by a majority of clients (12 of the 18 supported clients), and the skills-only clients mostly write no MCP config either — except Cline (global scope only), Droid, and Warp. The authoritative per-client support matrix is the Client Compatibility docs page — trust it over this summary, and check it rather than assuming.
Hooks are experimental and off by default. The kind publishes, resolves, locks, installs, and reports today; arming is gated twice:
options.experimental.hooksmust be true (falseunless you set it, config-only — no environment variable overrides it) and the workspace must have consented (grim hook allow,grim add, or an accepted prompt; global scope is always consented).grim installandgrim updatenever grant consent. So adding a hook gives you a declaration, a lock pin, and a materialized payload tree, and nothing fires until both gates clear.grim hook listis the surface for inspecting what you have. Full picture: references/consume.md; a hook that stays silent: references/troubleshooting.md.
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:
- Run
grim --version. This guide tracks the release it ships beside; on a different minor, treat every flag mentioned here as a hypothesis. - Run
grim <command> --helpbefore using flags you have not verified this session — it is the authoritative, always-current flag list. - On any conflict between this skill and live
--helpoutput, 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.
To verify a pre-built grim release archive's build provenance:
gh attestation verify <archive> --repo grimoire-rs/grimoire
(Installation).
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; --marketplace <path> instead rolls a declared plugin's own lock forward and installs nothing |
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; both also drop dependencies only the target needed | consume |
grim why |
Explain why an artifact is installed: direct, or required by which others (offline, lock only) | consume |
grim export plugin |
Render already-locked artifacts as a Claude-family (Claude Code, Qoder) or Agent Plugins plugin (directory or --zip), for a client with no grim install |
publish |
grim export marketplace |
Regenerate a git marketplace repository from a marketplace.toml's [marketplace] table: one marketplace file and one plugin tree per client, plus a root README with the add commands, for consumers with no grim install |
marketplaces |
grim search / tui |
Browse your declared registries' catalogs | registries |
grim rate |
Vote on an artifact through the index's rating forge | registries |
grim mcp |
Run a local STDIO MCP server for AI agent integration | registries |
grim hook list |
Report every declared hook with its tier, events, and per-client arming state | consume |
grim hook allow / grim hook revoke (alias deny) |
Record or remove this workspace's consent to arm its hooks | consume |
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 / hook.toml |
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;
addandstatusflag it as deprecated (anaddof a deprecated reference still succeeds).searchandtuihide deprecated artifacts by default unless they are installed — reveal them withgrim search --show-deprecated, the TUIhkey, or by settingoptions.show_deprecated = true(grim config set options.show_deprecated true). Areplaced-bysuccessor reference, when the publisher named one, surfaces ingrim search/grim describe. See Publishing.Build provenance:
build,release, andpublishembed the publishing commit and its date as OCI annotations by default (never a wall-clock time, so re-release stays idempotent).--gitadditionally requires them and discloses theoriginremote and commit author;--no-gitsuppresses every derived annotation. Confirm withgrim release --help.
grim hookhas three subcommands:list,allowandrevoke(aliasdeny). Hooks fire through a separate nativegrim-hooklauncher thatgrim installwrites to$GRIM_HOME/hooks/; clients run it, a person does not. After upgrading grim, re-rungrim installin each workspace that uses hooks, or that workspace's hooks stay quiet.Global flags apply to every subcommand —
--format,--global(-g),--config,--registry,--offline,--log-level, and--color <auto|always|never>(defaultautocolorizes clap's help/error output and--format jsononly when stdout is a terminal;--color alwayscolorizes 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 withgrim --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. [hooks] accepts registry references only — a
path value there is refused, so a hook always comes from a registry.
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
| 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, searching, or rating |
| references/marketplaces.md | Running grim export marketplace, or adding, pinning, rolling out or troubleshooting a grim-generated plugin marketplace in Claude Code, Copilot, Codex, Qoder or Cursor (consumers need no grim) |
| references/telemetry.md | Turning opt-in telemetry on, proving it is off, or auditing what it sends |
| 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.
- Use a marketplace and Host a marketplace
— consumer and curator guides. To create one (layout, deploy repository,
scheduled regenerate), use the
grim-authoringskill's marketplace reference.
Verified against the grim release this package ships beside.
Files (grimoire)
-
references
-
consume.md 35.3 KB
Loading… -
marketplaces.md 13.2 KB
Loading… -
publish.md 37.4 KB
Loading… -
registries.md 61.5 KB
Loading… -
telemetry.md 2.8 KB
Loading… -
troubleshooting.md 26.2 KB
Loading… -
updating.md 7.2 KB
Loading…
-
-
SKILL.md 13.6 KB
--- name: grim-usage description: Drive the grim CLI — the OCI package manager for AI skills, rules, agents, MCP servers, hooks, and bundles. Use when installing, updating, searching, rating, or publishing AI-config artifacts with grim; when composing grim init, config, add, lock, install, update, status, context, fetch, describe, export, search, rate, tui, mcp, hook, build, release, publish, login, logout, or completions commands; when adding, pinning, or exporting a plugin marketplace (marketplace.toml); when enabling opt-in telemetry; when configuring settings, multiple registries, or qualified alias/repo references; or when resolving registries, project vs global scope, client targets, or offline mode. license: Apache-2.0 compatibility: grim>=0.16 metadata: summary: How to use the grim CLI end to end keywords: grim,grimoire,cli,oci,registry,install,update,publish,skills,rules,agents,bundles,mcp,hooks,multi-registry repository: https://github.com/grimoire-rs/grimoire --- # Grim Usage Grimoire (binary: `grim`) is a package manager for AI-agent configuration. It distributes six artifact kinds — **skills**, **rules**, **agents**, **MCP servers**, **hooks**, 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](references/registries.md#client-targets); 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, but agents are hosted by a majority of clients (12 of the 18 supported clients), and the skills-only clients mostly write no MCP config either — except Cline (global scope only), Droid, and Warp. The authoritative per-client support matrix is the [Client Compatibility][clients] docs page — trust it over this summary, and check it rather than assuming. > **Hooks are experimental and off by default.** The kind publishes, > resolves, locks, installs, and reports today; **arming is gated twice**: > `options.experimental.hooks` must be true (`false` unless you set it, > config-only — no environment variable overrides it) **and** the workspace > must have consented (`grim hook allow`, `grim add`, or an accepted prompt; > global scope is always consented). `grim install` and `grim update` never > grant consent. So adding a hook gives you a declaration, a lock pin, and a > materialized payload tree, and nothing fires until both gates clear. > `grim hook list` is the surface for inspecting what you have. Full picture: > [references/consume.md](references/consume.md#hooks); a hook that stays > silent: > [references/troubleshooting.md](references/troubleshooting.md#a-hook-that-never-fires). 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](references/registries.md#client-targets). ## 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. To verify a pre-built grim release archive's build provenance: `gh attestation verify <archive> --repo grimoire-rs/grimoire` ([Installation][install]). ## Command Map | Command | Purpose | Details | |---|---|---| | `grim init` | Create a fresh `grimoire.toml` | [consume](references/consume.md) | | `grim config` | Read/write `grimoire.toml` settings and registries | [registries](references/registries.md) | | `grim add` | Declare an artifact and pin it in the lock | [consume](references/consume.md) | | `grim lock` | Resolve floating tags to digests | [consume](references/consume.md) | | `grim install` | Materialize the lock into AI clients | [consume](references/consume.md) | | `grim update` | Re-resolve, re-materialize, prune; `--marketplace <path>` instead rolls a declared plugin's own lock forward and installs nothing | [consume](references/consume.md) | | `grim status` | Report each declared artifact's state | [consume](references/consume.md) | | `grim context` | Report the resolved scope, paths, clients, registries | [consume](references/consume.md) | | `grim fetch` | Print an artifact's content without installing | [consume](references/consume.md) | | `grim describe` | Report an artifact's metadata (kind, annotations, tags) without downloading content | [consume](references/consume.md) | | `grim remove` / `uninstall` | Undeclare vs full inverse of install; both also drop dependencies only the target needed | [consume](references/consume.md) | | `grim why` | Explain why an artifact is installed: direct, or required by which others (offline, lock only) | [consume](references/consume.md#dependencies) | | `grim export plugin` | Render already-locked artifacts as a Claude-family (Claude Code, Qoder) or Agent Plugins plugin (directory or `--zip`), for a client with no grim install | [publish](references/publish.md#export) | | `grim export marketplace` | Regenerate a git marketplace repository from a `marketplace.toml`'s `[marketplace]` table: one marketplace file and one plugin tree per client, plus a root README with the add commands, for consumers with no grim install | [marketplaces](references/marketplaces.md) | | `grim search` / `tui` | Browse your declared registries' catalogs | [registries](references/registries.md) | | `grim rate` | Vote on an artifact through the index's rating forge | [registries](references/registries.md) | | `grim mcp` | Run a local STDIO MCP server for AI agent integration | [registries](references/registries.md) | | `grim hook list` | Report every declared hook with its tier, events, and per-client arming state | [consume](references/consume.md#hooks) | | `grim hook allow` / `grim hook revoke` (alias `deny`) | Record or remove this workspace's consent to arm its hooks | [consume](references/consume.md#hooks) | | `grim build` | Validate and pack locally, no push | [publish](references/publish.md) | | `grim release` | Validate, pack, push with cascade tags | [publish](references/publish.md) | | `grim publish` | Batch-release packages from a `publish.toml` manifest | [publish](references/publish.md) | | `grim login` / `logout` | Manage registry credentials | [publish](references/publish.md) | | `grim schema` | Emit the JSON Schema for `grimoire.toml` / `publish.toml` / `grimoire.lock` / the MCP descriptor / `hook.toml` | [publish](references/publish.md) | | `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][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`. > > **`grim hook` has three subcommands:** `list`, `allow` and `revoke` (alias > `deny`). Hooks fire through a separate native `grim-hook` launcher that > `grim install` writes to `$GRIM_HOME/hooks/`; clients run it, a person does > not. After upgrading grim, re-run `grim install` in each workspace that uses > hooks, or that workspace's hooks stay quiet. > > **Global flags** apply to every subcommand — `--format`, `--global` (`-g`), > `--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](references/consume.md#declaring) for how it is declared and installed. **`[hooks]` accepts registry references only** — a path value there is refused, so a hook always comes from a registry. 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](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](references/registries.md#multiple-registries). 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](references/registries.md#qualified-references). ## Routing Table | Read... | ...when | |---|---| | [references/consume.md](references/consume.md) | Installing, updating, or removing artifacts in a project | | [references/publish.md](references/publish.md) | Building, releasing, tagging, or logging in to publish | | [references/registries.md](references/registries.md) | Resolving registries, scopes, client targets, offline mode, searching, or rating | | [references/marketplaces.md](references/marketplaces.md) | Running `grim export marketplace`, or adding, pinning, rolling out or troubleshooting a grim-generated plugin marketplace in Claude Code, Copilot, Codex, Qoder or Cursor (consumers need no grim) | | [references/telemetry.md](references/telemetry.md) | Turning opt-in telemetry on, proving it is off, or auditing what it sends | | [references/troubleshooting.md](references/troubleshooting.md) | A grim command failed — exit codes, integrity gates, common causes | | [references/updating.md](references/updating.md) | Maintaining this skill itself against newer grim releases | ## Further Reading - [Command reference][commands] — every command with current flags. - [Concepts][concepts] — kinds, references, the lock, bundles, scopes, clients. - [Configuration][config] — `grimoire.toml`, `grimoire.lock`, environment variables. - [Publishing][publishing] — the author-to-release workflow. - [Authentication][auth] — credential store, login/logout, CI recipes. - [Use a marketplace][use-a-marketplace] and [Host a marketplace][hosting-a-marketplace] — consumer and curator guides. To *create* one (layout, deploy repository, scheduled regenerate), use the `grim-authoring` skill's marketplace reference. [commands]: https://grimoire.rs/commands.html [concepts]: https://grimoire.rs/concepts.html [config]: https://grimoire.rs/configuration.html [publishing]: https://grimoire.rs/publishing.html [auth]: https://grimoire.rs/authentication.html [clients]: https://grimoire.rs/clients.html [install]: https://grimoire.rs/installation.html#pre-built-binaries [use-a-marketplace]: https://grimoire.rs/guides/use-a-marketplace.html [hosting-a-marketplace]: https://grimoire.rs/guides/hosting-a-marketplace.html --- Verified against the grim release this package ships beside.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.