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

# tp plugin

> Publish, install, lock and govern a plugin package.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tp plugin publish ./my-plugin
tp plugin install alice/opsd-patch --exp my-grpo
```

A plugin is a directory with a `plugin.yaml` in it. The walkthrough is
[extension points](https://docs.tuneplane.ai/en/extend/overview.md); the manifest is
[plugin packages](https://docs.tuneplane.ai/en/extend/plugins.md).

## Worked examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
# browse
tp plugin ls
tp plugin info alice/opsd-patch

# install, and lock it to an experiment
tp plugin install alice/opsd-patch                    # into local tuneplane_plugins/, latest version
tp plugin install alice/opsd-patch --exp my-grpo      # into the experiment's plugins.lock.json
tp plugin remove alice/opsd-patch --exp my-grpo

# publish
tp plugin publish ./my-plugin                         # the directory must hold plugin.yaml
tp plugin publish ./my-plugin --owner team-x          # only an administrator can cross namespaces

# governance (admin)
tp plugin disable alice/opsd-patch                    # no new job may reference it; history is kept
tp plugin enable alice/opsd-patch
```

`--exp` is what makes a plugin travel with a job: the lock file is referenced in the JobSpec at
submission, and the platform injects the package into the job. Installing without `--exp` only
puts it on your machine.

## What publish checks

* The entrypoint module exists in the package.
* No top-level file shadows a real dependency. `torch.py` at the root would make every later
  `import torch` in the training process load your file.
* A declarative pack contains no executable file outside `template/`.
* The recomputed content digest matches what the client claimed.
* The version does not already exist. **Versions are immutable** — publish `1.2.1` to fix
  `1.2.0`.

## Check it worked

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tp plugin info alice/opsd-patch
```

Shows the version you published and its digest. After submitting a job that references it, the
job log carries one line per loaded plugin:

```text theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
plugin  : alice/opsd-patch@1.2.0 loaded
```

Disabling blocks new submissions only. A job already running or queued is unaffected.

## `tp plugin`

Manage plugins

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tp plugin <subcommand>
```

| Command | Description |
| - | - |
| `tp plugin activate` | Activate a playbook or prompt version |
| `tp plugin deactivate` | Restore the built-in defaults |
| `tp plugin disable` | Disable a plugin |
| `tp plugin enable` | Enable a plugin (admin) |
| `tp plugin info` | Show a plugin's details |
| `tp plugin install` | Install a plugin |
| `tp plugin ls` | List the plugins on the platform |
| `tp plugin publish` | Publish a plugin version |
| `tp plugin remove` | Remove a plugin from an experiment |
| `tp plugin validate` | Validate a plugin package |

### `tp plugin activate`

Activate a playbook or prompt version

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tp plugin activate <REF>
```

| Argument | Description |
| - | - |
| `REF` | Exact plugin reference: owner/name\@version (**required**) |

No options beyond `--help`.

### `tp plugin deactivate`

Restore the built-in defaults

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tp plugin deactivate <KIND>
```

| Argument | Description |
| - | - |
| `KIND` | playbook or prompt (**required**) |

No options beyond `--help`.

### `tp plugin disable`

Disable a plugin

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tp plugin disable <REF>
```

| Argument | Description |
| - | - |
| `REF` | Plugin id: \<owner>/\<name>\[@version] (**required**) |

No options beyond `--help`.

### `tp plugin enable`

Enable a plugin (admin)

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tp plugin enable <REF>
```

| Argument | Description |
| - | - |
| `REF` | Plugin id: \<owner>/\<name>\[@version] (**required**) |

No options beyond `--help`.

### `tp plugin info`

Show a plugin's details

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tp plugin info <REF>
```

| Argument | Description |
| - | - |
| `REF` | Plugin id: \<owner>/\<name>\[@version] (**required**) |

No options beyond `--help`.

### `tp plugin install`

Install a plugin

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tp plugin install <REF> [options]
```

| Argument | Description |
| - | - |
| `REF` | Plugin id: \<owner>/\<name>\[@version], defaults to the latest (**required**) |

| Option | Description |
| - | - |
| `--exp`, `-e` | Lock it to this experiment: referenced with the JobSpec on submission, injected into the job package by the platform |

### `tp plugin ls`

List the plugins on the platform

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tp plugin ls
```

No options beyond `--help`.

### `tp plugin publish`

Publish a plugin version

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tp plugin publish <PATH> [options]
```

| Argument | Description |
| - | - |
| `PATH` | Plugin directory (**required**) |

| Option | Description |
| - | - |
| `--owner` | Target namespace (only an admin can cross namespaces; defaults to your own) |

### `tp plugin remove`

Remove a plugin from an experiment

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tp plugin remove <REF> [options]
```

| Argument | Description |
| - | - |
| `REF` | Plugin id: \<owner>/\<name> (**required**) |

| Option | Description |
| - | - |
| `--exp`, `-e` | Experiment name or path (**required**) |

### `tp plugin validate`

Validate a plugin package

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tp plugin validate <DIRECTORY>
```

| Argument | Description |
| - | - |
| `DIRECTORY` | **required** |

No options beyond `--help`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.