atmos plugin install
path. Usage
atmos plugin install [source]
With a source, the command installs one package, records it under plugins.packages in
atmos.yaml, and writes the selected release to .atmos.plugins.lock.yaml. Without a
source, it restores every enabled declaration from the lock.
Version constraints
A new declaration installed without --version is written as a caret pin of the release that
was actually installed, so the declaration is reviewable and later releases do not slip in
silently:
| Installed release | Recorded constraint | Meaning |
|---|---|---|
1.4.2 | ^1.4.2 | Any stable 1.x.y at or above 1.4.2. |
0.1.0 | ^0.1.0 | Only 0.1.x; caret treats a 0.x minor as breaking. |
1.5.0-rc.1 | 1.5.0-rc.1 | Pinned exactly, because caret ranges never advance across pre-release tags. |
Passing --version always stores your constraint verbatim. Re-running install for a source
that is already declared keeps the existing constraint and never advances a locked release.
Use plugin update to move to a newer release.
Automatic installation and trust
Declared project plugins also install automatically, but only when a command needs one of their
exports, such as an auth provider or identity kind that Atmos does not provide. First use
creates a missing lock entry and prints a notice naming the source, digest, and signature status.
An existing lock pins every later restoration. In CI, Atmos refuses to create a new lock entry
and asks you to run atmos plugin install locally and commit the lockfile; restoring an already
locked release is allowed. See automatic installation for the
full rules.
Missing releases download in parallel with toolchain-style progress on stderr.
The default limit is four; plugins.max_concurrency changes the limit (1
selects sequential installation). A failed or canceled batch leaves the project
declaration and lockfile unchanged. Verified downloads use shared XDG storage and can be reused
by other projects selecting the same digest and platform.
Signature policy applies equally to explicit installation and automatic restoration.
Configure plugins.policy.trusted_publishers to require an authenticated release
signer. Cached bundles are checked against the current policy; a lockfile label
alone does not establish trust. See trusted publishers
for policy and offline layout setup.
Local builds
install only fetches and restores releases. To run a plugin you built locally, set
plugins.packages.<alias>.path to its directory, normally in a profile
of your own so the local build applies only while that profile is active. A package with a path is
never fetched, locked, or checked for a signature, so install skips it with a notice, and
install --frozen refuses while the active configuration sets one. See
path and the
plugin development tutorial.
A path-like source (one that starts with ., /, ~, or a drive letter, or names a directory
that contains plugin.yaml) is never treated as a release; the error explains how to declare path.
To install a copied OCI layout offline, pass the release source together with --from-layout.
Arguments and flags
source- An
oci://repository, or a<registry>/<package>selector for a configured discovery source (repository discovery or a catalog). Omit to restore declarations. --as- Package alias. Defaults to the existing alias bound to the same source, or to the package name.
Needs a
source. --version- Semantic version constraint, stored verbatim. Without it, a new declaration is pinned with a caret
from the installed release (see above) and an existing declaration keeps its constraint. Needs a
source. --from-layout- Read release bytes from a copied OCI image layout instead of a registry.
--frozen- Restore exactly what the lock records. Fails when the declarations and the lock disagree, when the
active configuration sets
plugins.packages.<alias>.path(the error names the active profiles), or when the cached release is corrupt. It never writes the lock, the declaration, or the cache, and cannot be combined with asource.
Packages with enabled: false or a path are skipped, with a notice, when restoring declarations.
Examples
atmos plugin install oci://registry.example.com/team/oidc --as=corporate
atmos plugin install oci://registry.example.com/team/oidc --as=corporate --version='^0.1'
atmos plugin install team/acme/oidc --as=corporate --version='^0.1'
atmos plugin install
atmos plugin install --frozen
atmos plugin install oci://registry.example.com/team/oidc --from-layout=./oidc-release
