> ## Documentation Index
> Fetch the complete documentation index at: https://docs.entire.io/llms.txt
> Use this file to discover all available pages before exploring further.

# plugin

> Discover, install, inspect, update, and troubleshoot commands that extend the Entire CLI.

CLI plugins are executables named `entire-<name>` that add commands to Entire. For example, an executable named `entire-graph` runs when you enter `entire graph`. This system is separate from the [Agent Integration Protocol](/agents/agent-integration-protocol/overview), which uses `entire-agent-<name>` executables to integrate coding agents.

```bash theme={null}
entire plugin COMMAND
```

<Warning>
  A CLI plugin is a native executable that runs with your user account's filesystem, network, and process permissions. Entire filters the environment passed to plugins, but it does not sandbox them. Install plugins only from sources you trust.
</Warning>

## Command Tree

| Command                                 | Purpose                                                                                 |
| --------------------------------------- | --------------------------------------------------------------------------------------- |
| `entire plugin browse`                  | Interactively browse the plugin index and install a selection.                          |
| `entire plugin doctor`                  | Check managed plugins for broken entries, integrity problems, and missing dependencies. |
| `entire plugin index update`            | Force a refresh of the synced plugin index.                                             |
| `entire plugin info NAME`               | Show index and install details for a plugin.                                            |
| `entire plugin install NAME\|URL\|PATH` | Install from the index, a repository, or a local executable.                            |
| `entire plugin list`                    | List plugins installed in the managed directory.                                        |
| `entire plugin remove NAME`             | Remove a managed plugin.                                                                |
| `entire plugin search [TERM]`           | Search the plugin index.                                                                |
| `entire plugin upgrade [NAME]`          | Upgrade one or all plugins installed from remote repositories.                          |

## Discovery and Precedence

When you run a command such as `entire graph build`, Entire:

1. Checks whether `graph` is a command included with Entire.
2. Looks for an executable named `entire-graph` on `$PATH`.
3. Runs that executable with `build` as its argument and passes stdin, stdout, stderr, and its exit code through unchanged.

Commands included with Entire take precedence. If you install `entire-version`, for example, `entire version` still runs the command included with Entire.

Entire temporarily prepends the managed plugin directory to `$PATH` during plugin discovery. Therefore, a managed plugin takes precedence over an `entire-<name>` executable with the same name elsewhere on your shell's `$PATH`. Entire keeps the managed directory on `$PATH` while a plugin runs so it can invoke other managed plugins.

Entire reserves names beginning with `entire-agent-` for agent integrations and does not dispatch them as CLI commands. Follow the [Agent Integration Protocol](/agents/agent-integration-protocol/overview) to build or install one.

### Run an Unmanaged Plugin

You do not need `entire plugin install` to run a plugin. Make the binary executable and place it anywhere on your `$PATH`:

```bash theme={null}
chmod +x /path/to/entire-example
entire example --help
```

Unmanaged plugins do not appear in `entire plugin list`. `entire plugin upgrade` does not update them, and you must remove them from `$PATH` manually.

## Managed Directory

`entire plugin install` uses the first managed root that applies:

| Environment     | Managed Root                                                         |
| --------------- | -------------------------------------------------------------------- |
| Override        | `$ENTIRE_PLUGIN_DIR`                                                 |
| Linux and macOS | `$XDG_DATA_HOME/entire/plugins`, or `~/.local/share/entire/plugins`  |
| Windows         | `%LOCALAPPDATA%\entire\plugins`, or `~\AppData\Local\entire\plugins` |

`ENTIRE_PLUGIN_DIR` must be an absolute path. Under the root, Entire uses this layout:

```text theme={null}
<managed-root>/
├── bin/                    # Executables discovered as entire-<name>
├── data/<name>/            # Durable storage available to the plugin
└── pkg/<name>/
    ├── entire-<name>       # Binary from a remote install
    └── manifest.yml        # Version, source, checksum, and dependencies
```

Remote installs store the downloaded binary and its provenance under `pkg/`, then link the binary into `bin/`. Local path installs link the source executable directly into `bin/`, so rebuilding the source normally updates the command immediately. When symbolic links are unavailable, Entire falls back to a hard link and then a copy.

Each plugin receives:

| Variable                 | Value                                                                            |
| ------------------------ | -------------------------------------------------------------------------------- |
| `ENTIRE_CLI_VERSION`     | The version of the Entire CLI that launched it.                                  |
| `ENTIRE_REPO_ROOT`       | The repository root, when the command runs inside a repository.                  |
| `ENTIRE_PLUGIN_DATA_DIR` | The plugin's durable `data/<name>` directory. The plugin creates it when needed. |

Entire passes common operating system, terminal, locale, CI, proxy, SSH agent, `ENTIRE_*`, `LC_*`, and `XDG_*` variables. Entire excludes other variables by default to reduce accidental credential exposure. You can explicitly pass additional names or prefixes with `ENTIRE_PLUGIN_ENV`, for example:

```bash theme={null}
ENTIRE_PLUGIN_ENV='AWS_*,GH_TOKEN' entire example
```

This filtering is defense in depth, not a security boundary: a malicious plugin can still read files and credentials available to your user account.

## Install a Plugin

Install a plugin from the synced index, a git repository URL, or a local executable.

```bash theme={null}
entire plugin install NAME|URL|PATH [flags]
```

| Source         | Example                                                        | Behavior                                                                                     |
| -------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Index name     | `entire plugin install run`                                    | Resolves the name through the synced plugin index.                                           |
| Repository URL | `entire plugin install https://github.com/entireio/entire-run` | Resolves a release from the repository. A URL not listed in the index requires confirmation. |
| Local path     | `entire plugin install ./dist/entire-run`                      | Links an existing executable into the managed directory.                                     |

Local paths must be explicit: include a directory separator or begin with `./`. The executable's basename must be `entire-<name>` so Entire can derive the command name.

For a remote install, Entire:

1. Uses the tag supplied with `--pin`, or tries the newest stable semantic version tag. Without `--pin`, Entire tries up to two older stable tags when newer tags lack a compatible release asset.
2. Reads `entire-plugin.yml` from that tag when the repository provides it.
3. Downloads the matching release asset over HTTPS.
4. Verifies the asset against the release's checksum manifest.
5. Stores the binary and install manifest in the managed directory.
6. Resolves and offers to install declared dependencies.

Installing from a URL that is not in the plugin index asks for confirmation. Pass `--yes` to skip the prompt; a run without a terminal requires this flag for an unlisted URL.

### Checksum Verification

Remote installation looks for `checksums.txt` or a supported plugin checksum filename in the release. When the manifest covers the release asset, Entire computes its SHA-256 digest and refuses the install if it does not match. Entire also records a digest of the installed binary so `entire plugin doctor` can detect later changes.

If the release asset has no published checksum covering your platform, installation stops. `--allow-unverified` bypasses that requirement and records the install as unverified; `plugin doctor` continues to report it. Future upgrades preserve the original choice: a verified install cannot silently become unverified, while an unverified install remains allowed to upgrade without a new flag.

<Warning>
  A matching checksum proves that the downloaded bytes match the checksum published with that release. It does not prove that the repository owner, release process, or plugin code is trustworthy. Use `--allow-unverified` only after you have independently decided to trust the source and accept that the download is not authenticated by a published checksum.
</Warning>

### Dependencies

A plugin repository can declare runtime dependencies in `entire-plugin.yml`:

```yaml theme={null}
name: example
description: Example Entire CLI plugin
requires:
  - name: graph
    min_version: v0.4.0
```

`min_version` accepts an optional minimum semantic version. Entire does not support version ranges. Entire resolves dependencies by name through the plugin index, including transitive dependencies. A plugin author cannot supply a dependency repository URL in `entire-plugin.yml`.

Entire shows the dependencies it plans to install or upgrade and asks once for confirmation. Use `--yes` in a run without a terminal or `--no-deps` to install only the requested plugin. If a dependency already comes from a local path or your shell's `$PATH`, Entire treats it as present but cannot verify its minimum version. Run `entire plugin doctor` to inspect the resulting state.

| Flag                 | Description                                                      |
| -------------------- | ---------------------------------------------------------------- |
| `--allow-unverified` | Install when no published checksum covers the release asset.     |
| `--force`            | Replace an existing managed entry with the same name.            |
| `--index URL`        | Use a different plugin index for this command.                   |
| `--no-deps`          | Do not install declared dependencies.                            |
| `--pin TAG`          | Install exactly this tag and skip the plugin during upgrades.    |
| `--yes`              | Skip confirmation prompts for unlisted sources and dependencies. |

## List Managed Plugins

List plugins installed in the managed directory.

```bash theme={null}
entire plugin list
```

```text theme={null}
Managed plugin directory: /Users/you/.local/share/entire/plugins/bin

  run                  v0.1.0             → /Users/you/.local/share/entire/plugins/pkg/run/entire-run
```

This command does not list unmanaged `entire-<name>` executables elsewhere on `$PATH`.

## Search the Plugin Index

Search the synced plugin index. Run the command without a term to list everything available. A `*` marks a managed plugin that is already installed.

```bash theme={null}
entire plugin search [TERM] [flags]
```

```text theme={null}
* run                  Launch one of the agents enabled for Entire in the current repository [official]
  upgrade              Upgrade the system-installed Entire binary [official]
```

Entire caches the Git repository that contains the index. On the next index operation after the cached copy is 24 hours old, Entire attempts a refresh. If a refresh fails while you are offline, Entire uses the existing cached copy. The index URL resolves in this order: `--index`, `ENTIRE_PLUGIN_INDEX_URL`, then Entire's default index.

| Flag          | Description                                    |
| ------------- | ---------------------------------------------- |
| `--index URL` | Use a different plugin index for this command. |

## Inspect a Plugin

Show index metadata and managed install details for a plugin, including its repository, version, pin, and dependencies.

```bash theme={null}
entire plugin info NAME [flags]
```

```text theme={null}
Name:        run
Description: Launch one of the agents enabled for Entire in the current repository
Repository:  https://github.com/entireio/entire-run
Official:    true
Installed:   v0.1.0 (from https://github.com/entireio/entire-run)
```

| Flag          | Description                                    |
| ------------- | ---------------------------------------------- |
| `--index URL` | Use a different plugin index for this command. |

## Browse the Plugin Index

Browse the plugin index in an interactive picker and install a selection.

```bash theme={null}
entire plugin browse [flags]
```

The picker shows each plugin's name and description. Before downloading anything, Entire shows the repository that provides the binary and asks you to confirm.

<Note>
  This command needs a terminal. Use `entire plugin search` and `entire plugin install NAME` in scripts and runs without a terminal.
</Note>

| Flag          | Description                                    |
| ------------- | ---------------------------------------------- |
| `--index URL` | Use a different plugin index for this command. |

## Upgrade Plugins

Upgrade one plugin installed from a remote repository, or use `--all` to upgrade every eligible plugin. Entire tries the newest stable semantic version first and uses the same release asset fallback as installation.

```bash theme={null}
entire plugin upgrade NAME
entire plugin upgrade --all
```

Entire cannot upgrade local path installs because they have no remote install manifest. Pinned plugins stay at their selected version until you reinstall them without `--pin`.

| Flag    | Description                                                       |
| ------- | ----------------------------------------------------------------- |
| `--all` | Upgrade every eligible plugin installed from a remote repository. |

## Remove a Plugin

Remove a plugin from the managed directory.

```bash theme={null}
entire plugin remove NAME [flags]
```

If another managed plugin declares the target as a dependency, Entire refuses removal unless you pass `--force`. This command does not remove unmanaged executables elsewhere on `$PATH`.

| Flag      | Description                                                   |
| --------- | ------------------------------------------------------------- |
| `--force` | Remove a plugin even when other managed plugins depend on it. |

## Diagnose Plugin Problems

Check managed plugins for:

* broken managed entries
* dangling links to local paths
* missing or outdated dependencies
* unverified installs
* changes to a binary installed from a remote repository
* the macOS quarantine attribute

```bash theme={null}
entire plugin doctor
```

```text theme={null}
All plugins healthy.
```

The command prints a suggested fix for each actionable problem and exits unsuccessfully when it finds issues.

## Update the Plugin Index

Force a refresh of the plugin index from its Git repository.

```bash theme={null}
entire plugin index update [flags]
```

Use this command when `plugin search` does not show a newly published plugin or when you need to refresh the index before the cached copy becomes stale.

| Flag          | Description                       |
| ------------- | --------------------------------- |
| `--index URL` | Refresh a different plugin index. |

## Troubleshooting

### `entire NAME` Reports an Unknown Command

1. Confirm the executable is named `entire-NAME`, including the `entire-` prefix.
2. Run `entire plugin list` for a managed install.
3. For an unmanaged install, run `command -v entire-NAME` on Linux or macOS, or `where entire-NAME` on Windows.
4. On Linux or macOS, make the file executable with `chmod +x /path/to/entire-NAME`.
5. Run `entire plugin doctor` to check managed entries.

### The Wrong Copy Runs

Entire prepends the managed `bin/` directory during discovery, so it wins over matching executables elsewhere on `$PATH`. Run `entire plugin list` to see the managed entry. Remove it with `entire plugin remove NAME` if you intend to use the copy from your shell's `$PATH`.

If the name matches a command included with Entire, Entire runs that command. Rename the plugin executable and invoke it under the new name.

### A Plugin Is Missing from Search

Refresh and search the index:

```bash theme={null}
entire plugin index update
entire plugin search NAME
```

If the plugin is not indexed, install its repository URL directly. Review the repository before accepting the unlisted source prompt.

### Installation Needs a Terminal

An unlisted repository URL and dependency installation require confirmation. In CI or another environment without a terminal, review the source and its `entire-plugin.yml` dependencies first, then add `--yes`.

### Checksum Verification Fails

Do not bypass a checksum mismatch. A mismatch means the downloaded asset differs from the published digest. If no checksum covers your platform, ask the plugin author to publish one. `--allow-unverified` is an explicit choice for a missing checksum, not a remedy for a mismatch.

### A Local Plugin Does Not Update

Local installs use a symbolic link when the platform allows it, so rebuilding the source updates the command. On systems that require the hard link or copy fallback, reinstall with `--force` after rebuilding:

```bash theme={null}
entire plugin install ./dist/entire-example --force
```

### Dependencies Are Missing or Outdated

Run `entire plugin doctor` and follow its suggested install or upgrade commands. Reinstall the parent plugin without `--no-deps` if you want Entire to plan the transitive dependency set again.