# Install plugins with HOL Guard

> Plan, apply, and undo a HOL-listed plugin install in Claude Code and Codex, with Guard checks before anything runs.

Canonical: https://hol.org/guard/docs/plugin-scanner/install-with-hol-guard · Updated: 2026-10-26 · Applies to: Guard 3.x

`hol-guard plugin install` installs a plugin listed on [HOL](https://hol.org/registry/plugins) with each runtime's own CLI. Guard reads the listing's install details from HOL, checks every identifier in them, prints the exact commands, and runs nothing until you pass `--apply` and confirm each runtime.

```bash
pipx install hol-guard
hol-guard plugin install owner/plugin
```

`plugin install` is new; if `hol-guard plugin install --help` reports an unknown command, upgrade with `pipx upgrade hol-guard`.

## What it does

1. Downloads the listing's install spec from `https://hol.org/api/guard/plugins/install-spec`. The spec carries identifiers only (repository, marketplace and plugin names), never command text.
2. Checks every identifier. A name that could be read as a flag, a path, a URL or shell text fails the check and nothing runs.
3. Builds the commands from fixed programs: `claude`, `codex` and `npx`. No shell is involved.
4. Prints the plan. With `--apply`, asks before each runtime and then runs that runtime's commands.

## Print the plan

The plan is the default; `--dry-run` says so explicitly.

```bash
hol-guard plugin install acme/toolgate
```

```text
acme/toolgate 1.2.0
  HOL trust score: 82/100
  Listing: https://hol.org/registry/plugins/acme%2Ftoolgate

claude-code:
  claude plugin marketplace add acme/toolgate
  claude plugin install toolgate@acme

codex:
  codex plugin marketplace add acme/toolgate
  codex plugin add toolgate@acme

agent-skills:
  npx skills add acme/toolgate
  Run this yourself: the Skills CLI downloads a package from npm and installs for every agent it detects.

Install by hand (see the listing): mcp

Nothing was changed. Run with --apply to install, confirming each runtime.
```

A runtime whose CLI is not on your `PATH` is marked `(claude not found)` and skipped.

## Install

```bash
hol-guard plugin install acme/toolgate --apply
```

Guard asks `Install for claude-code? [y/N]` and `Install for codex? [y/N]`. Answer `y` for the runtimes you want. Start a new Claude Code or Codex session to load the plugin, then check it with `claude plugin list` or `codex plugin list`.

| Option | Effect |
| :--- | :--- |
| `--apply` | Run the commands after a confirmation per runtime. |
| `--dry-run` | Only print the plan (the default). Cannot be combined with `--apply`. |
| `--yes` | Skip the confirmations, for CI and scripted setups. Use it with `--apply`. |
| `--json` | Print the plan as JSON. |
| `--runtime claude-code,codex` | Limit the plan to some runtimes: `claude-code`, `codex`, `agent-skills`. |
| `owner/plugin@1.2.0` | Refuse to continue unless HOL lists that version. |

Agent skills for Cursor, Gemini CLI, OpenCode and other agents are always printed, never run: the Skills CLI downloads a package from npm and installs for every agent it detects, so run `npx skills add` yourself when you want that. MCP servers and other runtimes the listing supports are listed under "Install by hand".

## Uninstall

```bash
hol-guard plugin uninstall acme/toolgate --apply
```

Guard removes the plugin entry with `claude plugin uninstall` and `codex plugin remove`. The marketplace stays registered, since other plugins may use it.

## What Guard records

Guard keeps a local list of the listings it installed, under the Guard home directory, so `uninstall` knows what to remove. The only request to HOL is the download of the listing's install spec. If you turn on the weekly plugin counts with `hol-guard telemetry plugins on`, listings Guard installed are counted as installed with HOL Guard. The counts stay off until you turn them on, and `hol-guard telemetry plugins send --dry-run` prints exactly what would be sent.

## For plugin authors

The plugin workspace on HOL offers a README install block: your verified badge, the `hol-guard plugin install` line and a collapsed table of each runtime's own commands. `hol-guard plugin links --block` prints the same block from your terminal. HOL checks claimed READMEs every few hours for the block.