Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 14 additions & 7 deletions datumctl/plugins/using-plugins.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@

Results show the plugin name, the catalog it came from, its version, its trust badge, and a short description.

For scripts and coding agents, pass `-o json` or `-o name`. `-o json` prints an array of objects with `name`, `index`, `version`, `trust`, and `description` fields, or `[]` when nothing matches. `-o name` prints one plugin name per line:
For scripts and coding agents, pass `-o json` or `-o name`. `-o json` prints an array of objects with `name`, `index`, `version`, `trust`, and `description` fields, or `[]` when nothing matches. A plugin its catalog marks deprecated also has a `deprecated` object with the catalog's `message` and `replacement`. `-o name` prints one plugin name per line:

```bash
datumctl plugin search --index datum -o json
Expand Down Expand Up @@ -119,12 +119,13 @@

This shows each installed plugin with its catalog, version, trust badge, description, and a status indicator:

| Status | Meaning |
|----------|-----------------------------------------------------|
| `ok` | Installed and compatible with this datumctl. |
| `update` | A newer version is available in its catalog. |
| `!` | Built for a different datumctl version. |
| `?` | Version information is unavailable. |
| Status | Meaning |
|--------------|-----------------------------------------------------|
| `ok` | Installed and compatible with this datumctl. |
| `update` | A newer version is available in its catalog. |
| `deprecated` | Its catalog marks the plugin deprecated. See [Deprecated plugins](#deprecated-plugins). |
| `!` | Built for a different datumctl version. |
| `?` | Version information is unavailable. |

## Running an installed plugin

Expand Down Expand Up @@ -179,9 +180,15 @@

`datumctl plugin install --all-available` skips a deprecated plugin you haven't installed and prints `Skipped <name>: deprecated`. A deprecated plugin you already have is still upgraded, or reported as up to date, and datumctl prints its deprecation warning.

Listings flag deprecated plugins too:

- `datumctl plugin list` shows `deprecated` in the `STATUS` column in place of `update`. When a newer version also exists, datumctl still suggests `datumctl plugin upgrade`. A plugin built for a different datumctl version still shows `!`, and one without version information still shows `?`. After the table, datumctl prints the deprecation warning for each deprecated plugin to stderr, whatever its status. `plugin list` reads only the catalog indexes datumctl has cached, so run `datumctl plugin search` to refresh them.
- `datumctl plugin search` adds `[deprecated]` before the description and prints the warning for each deprecated result to stderr after the table. With `-o json`, each deprecated result carries a `deprecated` object instead. `-o json` and `-o name` print no warnings.
- `datumctl plugin browse` adds `(deprecated)` after the plugin name and shows the warning in the plugin's details.

## How plugins stay trustworthy

datumctl treats a plugin as untrusted code and protects you in a few ways:

Check warning on line 191 in datumctl/plugins/using-plugins.mdx

View check run for this annotation

Mintlify / Mintlify Validation (datum-4926dda5) - vale-spellcheck

datumctl/plugins/using-plugins.mdx#L191

Did you really mean 'untrusted'?

- **HTTPS-only downloads.** Plugin archives and catalog manifests are fetched over HTTPS only. Downloads to private, loopback, or link-local addresses are refused, and redirects are re-checked on every hop.
- **Checksum verification on every run.** datumctl records a SHA256 fingerprint of each plugin binary at install time and verifies it *every time the plugin runs*. If a managed plugin binary is modified after installation, datumctl refuses to run it.
Expand Down
Loading