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

# ubx plugin

> Install, list, update, and remove ubx engine plugins.

ubx uses engine plugins for execution. Plugins communicate via gRPC and are installed to `~/.ubx/plugins/<name>/ubx-plugin-<name>`.

## Subcommands

| Subcommand                    | Description                           |
| ----------------------------- | ------------------------------------- |
| `ubx plugin install <source>` | Install a plugin                      |
| `ubx plugin list`             | List installed plugins                |
| `ubx plugin update <name>`    | Update a plugin to its latest version |
| `ubx plugin remove <name>`    | Remove an installed plugin            |

## `ubx plugin install`

```bash theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
ubx plugin install pulumi                        # install by bare name (from GitHub)
ubx plugin install terraform                     # install Terraform plugin
ubx plugin install opentofu                      # install OpenTofu plugin

ubx plugin install github://org/repo@v1.2.3     # specific GitHub release
ubx plugin install github://org/repo@latest      # latest GitHub release
ubx plugin install file:///path/to/binary        # local binary
```

Bare names (e.g. `pulumi`) expand to `github://ubiquex/ubx-plugin-pulumi@latest`.

Plugins are installed to:

```
~/.ubx/plugins/<name>/ubx-plugin-<name>
```

## `ubx plugin list`

```bash theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
ubx plugin list
```

Output:

```
Installed plugins:
  pulumi                github://ubiquex/ubx-plugin-pulumi@v1.2.0
  terraform             github://ubiquex/ubx-plugin-terraform@v0.8.0
```

## `ubx plugin update`

```bash theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
ubx plugin update pulumi     # update to latest version
```

Re-installs from the source recorded in the plugin lock file.

## `ubx plugin remove`

```bash theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
ubx plugin remove pulumi
```

Removes the binary and the plugin directory. Updates the lock file.

## Plugin lock file

ubx maintains a lock file at `.ubx/plugin.lock` (JSON):

```json theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
{
  "plugins": {
    "pulumi": {
      "source": "github://ubiquex/ubx-plugin-pulumi@v1.2.0",
      "sha256": "abc123...",
      "path": "/Users/you/.ubx/plugins/pulumi/ubx-plugin-pulumi"
    }
  }
}
```

## Plugin discovery order

ubx finds plugins by searching:

1. `~/.ubx/plugins/<name>/ubx-plugin-<name>` (installed via `ubx plugin install`)
2. `ubx-plugin-<name>` on `$PATH`

The binary must be a regular executable file.

## Source schemes

| Scheme          | Example                                                |
| --------------- | ------------------------------------------------------ |
| Bare name       | `pulumi` → `github://ubiquex/ubx-plugin-pulumi@latest` |
| GitHub          | `github://owner/repo@version`                          |
| Local file      | `file:///absolute/path/to/binary`                      |
| Strata (future) | `strata://` *(not yet supported)*                      |