Grim Usage

---
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 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.14
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** behind
> `options.experimental.hooks` (`false` unless you set it, config-only —
> no environment variable overrides it). So adding a hook gives you a
> declaration, a lock pin, and a materialized payload tree, and nothing
> fires. `grim hook list` is the surface for inspecting what you have. Full
> picture: [references/consume.md](references/consume.md#hooks).

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.

## 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 | [consume](references/consume.md) |
| `grim export plugin` | Render already-locked artifacts as a Claude Code or Agent Plugins plugin (directory or `--zip`), for a client with no grim install | [publish](references/publish.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 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 run` is not a command you type.** `grim hook` has two
> subcommands, and only `list` is user-facing; `run` dispatches one client
> event and its caller is the launcher grim generates, which passes it
> `--client`, `--event`, `--table`, and `--root`. `grim hook --help` says
> as much. Same shape as `grim mcp`, which speaks JSON-RPC on stdout rather
> than to a person — invoke neither by hand expecting readable output.
>
> **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/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.

[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

---

Verified against the grim release this package ships beside.