Repository navigation
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
docs: explain plugin installs from pre-release-only repositories #156
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: explain plugin installs from pre-release-only repositories #156
Changes from all commits
1e32a39File filter
Filter by extension
Conversations
Uh oh!
There was an error while loading. Please reload this page.
Jump to
Uh oh!
There was an error while loading. Please reload this page.
There are no files selected for viewing
Plugins extend `datumctl` with additional commands without changing the core CLI. A plugin is an independent binary that datumctl runs on your behalf — once installed, you invoke it exactly like a built-in command. For the thinking behind plugins, see [Extending our CLI with plugins](https://www.datum.net/blog/extending-our-cli-with-plugins/) on the Datum blog. <Info> Plugins are optional. You never need one to use `datumctl`, and the core CLI works the same whether or not you have any installed. </Info> ## What a plugin is When you install the `compute` plugin from the official **datum** catalog, its commands become available under `datumctl compute`: ```bash datumctl compute --help ``` (See [Compute](/datumctl/compute/overview) for what that plugin does.) datumctl injects your current organization, project, and a fresh short-lived access token into the plugin automatically, so plugins work with your [active context](/datumctl/contexts-and-scoping) and [credentials](/datumctl/auth/managing-accounts) without a separate login. Plugins come from **catalogs** (also called indexes). The official **datum** catalog is curated by Datum and always available with no setup — its plugins carry an `official` trust badge. You can also add third-party catalogs, whose plugins carry a `third-party` badge. See [Adding catalogs](/datumctl/plugins/adding-catalogs) to register more. ## Finding plugins Search every registered catalog for available plugins: ```bash # List everything available across all catalogs datumctl plugin search # Filter by name or description datumctl plugin search compute # Scope the search to a single catalog datumctl plugin search deploy --index acme ``` 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: ```bash datumctl plugin search --index datum -o json datumctl plugin search -o name ``` Prefer to explore interactively? `plugin browse` opens a filterable picker where you can inspect a plugin's details and install it in place: ```bash datumctl plugin browse ``` <Note> `plugin browse` requires an interactive terminal. In scripts or CI, use `plugin search` instead. </Note> ## Installing a plugin Datum's own plugins are documented with the products they manage. For example, see [DNS operations](/domain-dns/operations) for the `dns` plugin and [Compute commands](/datumctl/compute/overview) for the `compute` plugin. Install by name from a catalog: ```bash # Install from the official datum catalog (searched first) datumctl plugin install compute # Install from a specific catalog datumctl plugin install acme/deploy ``` You can also install directly from a GitHub release, without a catalog: ```bash # Latest release, or the newest pre-release if there's no stable one datumctl plugin install your-org/datumctl-example # A specific release datumctl plugin install your-org/datumctl-example@v1.2.0 ``` <Info> If a bare name exists in more than one catalog, datumctl lists the matches instead of guessing. Qualify the name with its catalog (for example `acme/deploy`) to choose. </Info> ### Pinning a version Pin a specific version at install time by appending `@version`: ```bash # Pin a catalog plugin datumctl plugin install compute@v0.8.0-dev.7 datumctl plugin install acme/deploy@v2.0.0 # Pin a GitHub release datumctl plugin install your-org/datumctl-example@v1.2.0 ``` Without `@version`, datumctl installs the version the catalog recommends. ### Restoring your plugin set Run `install` with no arguments to restore every plugin you previously installed, at its recorded version. This reproduces your plugin set on a new machine: ```bash datumctl plugin install ``` ## Listing what you have ```bash datumctl plugin list ``` 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. | ## Running an installed plugin An installed plugin behaves like a native command: ```bash datumctl compute --help ``` Tab completion works transparently — datumctl forwards completion requests to the plugin, so completing subcommands and flags just works: ```bash datumctl compute <TAB> ``` ## Upgrading and removing ```bash # Upgrade a plugin to the latest version datumctl plugin upgrade compute # Remove a plugin datumctl plugin remove compute ``` To upgrade every plugin you have installed at once, run `datumctl plugin upgrade --all`. `datumctl plugin list` shows `update` in the `STATUS` column for any plugin with a newer version. `plugin upgrade` runs the same verified install flow as a fresh install. ## How plugins stay trustworthy datumctl treats a plugin as untrusted code and protects you in a few ways: - **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. - **Trust badges.** Every plugin and catalog shows whether it is `official` (Datum's curated **datum** catalog) or `third-party`, so you always know the source. <Warning> Third-party plugins are programs that run on your machine with your Datum credentials, and Datum does not review them. Only install plugins from catalogs and sources you trust. See [Adding catalogs](/datumctl/plugins/adding-catalogs) for the trust decision involved in registering a catalog. </Warning> ### Trusting a plugin already on your PATH If you have a plugin binary on your `PATH` that datumctl did not install (named `datumctl-<name>` or `milo-<name>`), datumctl blocks it from running until you explicitly trust it: ```bash # Allow an unmanaged PATH plugin to run datumctl plugin trust dns # Revoke that trust later datumctl plugin untrust dns ``` Trusting records the binary's path and fingerprint. If the binary changes afterward, datumctl blocks it again until you re-run `plugin trust`. ## Next steps - [Adding catalogs](/datumctl/plugins/adding-catalogs) — register additional or internal marketplaces - [Building plugins](/datumctl/plugins/building-plugins) — write your own plugin with the Go SDK - [Install](/datumctl/install) — new to `datumctl`? Install and log in first - [Contexts & scoping](/datumctl/contexts-and-scoping) — the organization and project a plugin inherits when it runs tumctl`? Install and log in first - [Contexts & scoping](/datumctl/contexts-and-scoping) — the organization and project a plugin inherits when it runsPlugins extend
Plugins are optional. You never need one to use `datumctl`, and the core CLI works the same whether or not you have any installed.datumctlwith additional commands without changing the core CLI. A plugin is an independent binary that datumctl runs on your behalf — once installed, you invoke it exactly like a built-in command. For the thinking behind plugins, see Extending our CLI with plugins on the Datum blog.What a plugin is
When you install the
computeplugin from the official datum catalog, its commands become available underdatumctl compute:(See Compute for what that plugin does.)
datumctl injects your current organization, project, and a fresh short-lived access token into the plugin automatically, so plugins work with your active context and credentials without a separate login.
Plugins come from catalogs (also called indexes). The official datum catalog is curated by Datum and always available with no setup — its plugins carry an
officialtrust badge. You can also add third-party catalogs, whose plugins carry athird-partybadge. See Adding catalogs to register more.Finding plugins
Search every registered catalog for available plugins:
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 jsonor-o name.-o jsonprints an array of objects withname,index,version,trust, anddescriptionfields, or[]when nothing matches.-o nameprints one plugin name per line:Prefer to explore interactively?
`plugin browse` requires an interactive terminal. In scripts or CI, use `plugin search` instead.plugin browseopens a filterable picker where you can inspect a plugin's details and install it in place:Installing a plugin
Datum's own plugins are documented with the products they manage. For example, see DNS operations for the
dnsplugin and Compute commands for thecomputeplugin.Install by name from a catalog:
You can also install directly from a GitHub release, without a catalog:
Without a version, datumctl installs the release GitHub marks as latest. If the repository has published only pre-releases, datumctl installs the highest pre-release instead, and
If a bare name exists in more than one catalog, datumctl lists the matches instead of guessing. Qualify the name with its catalog (for example `acme/deploy`) to choose.datumctl plugin upgradefollows newer pre-releases the same way.Pinning a version
Pin a specific version at install time by appending
@version:Without
@version, datumctl installs the version the catalog recommends.Restoring your plugin set
Run
installwith no arguments to restore every plugin you previously installed, at its recorded version. This reproduces your plugin set on a new machine:Listing what you have
This shows each installed plugin with its catalog, version, trust badge, description, and a status indicator:
okupdate!?Running an installed plugin
An installed plugin behaves like a native command:
Tab completion works transparently — datumctl forwards completion requests to the plugin, so completing subcommands and flags just works:
Upgrading and removing
To upgrade every plugin you have installed at once, run
datumctl plugin upgrade --all.datumctl plugin listshowsupdatein theSTATUScolumn for any plugin with a newer version.plugin upgraderuns the same verified install flow as a fresh install.How plugins stay trustworthy
datumctl treats a plugin as untrusted code and protects you in a few ways:
-
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.
-
Trust badges. Every plugin and catalog shows whether it is
Third-party plugins are programs that run on your machine with your Datum credentials, and Datum does not review them. Only install plugins from catalogs and sources you trust. See [Adding catalogs](/datumctl/plugins/adding-catalogs) for the trust decision involved in registering a catalog.official(Datum's curated datum catalog) orthird-party, so you always know the source.Trusting a plugin already on your PATH
If you have a plugin binary on your
PATHthat datumctl did not install (nameddatumctl-<name>ormilo-<name>), datumctl blocks it from running until you explicitly trust it:Trusting records the binary's path and fingerprint. If the binary changes afterward, datumctl blocks it again until you re-run
plugin trust.Next steps
datumctl? Install and log in firstUh oh!
There was an error while loading. Please reload this page.