atmos plugin create

Scaffold a Go OIDC provider, AWS broker identity, and command using Atmos scaffolding.

Experimental

atmos plugin create --help

Usage

atmos plugin create <directory>

Arguments and flags

directory

Destination for generated source and schemas.

--kind

Provider identifier in organization/name form, such as acme/oidc. Defaults to example/oidc.

--display-name

Human-readable plugin name. The stable package ID remains metadata.name, selected by --kind.

--description

Description stored in the plugin manifest.

--author

Optional author or maintainer.

--repository

Optional source repository URL. This is author-provided metadata; the consumer lockfile separately records the OCI download source.

--module

Go module path for the generated plugin. Defaults to example.com/atmos-oidc.

--runtime

Authoring runtime; the first implementation supports go (the default).

--capability

Primary extension capability. Takes a single value, not a list; the first starter supports only auth.provider (the default). Other capabilities and combining several are not available yet.

--sdk-version

Released Atmos Plugin SDK module version.

--sdk-path

Absolute path to a local SDK checkout for development.

--defaults

Use scaffold field defaults without prompting.

--force

Permit overwriting generated files.

Examples

Start in any directory where you want to keep the plugin source. The generator creates the source, manifest, schemas, README, local test fixtures, and an atmos.yaml with build, test, and push custom commands; you do not need to copy an Atmos demo project or set up an OCI registry to build and test it.

atmos plugin create ./corporate-oidc --kind=acme/oidc --module=example.com/acme/oidc --display-name="Corporate Identity" --repository=https://github.com/acme/atmos-oidc --defaults
cd corporate-oidc
atmos build
atmos test

When developing against an unreleased Atmos checkout, add --sdk-path to select its local SDK. This is the only extra authoring setup required by an unreleased SDK:

# For unreleased SDK development:
atmos plugin create ./corporate-oidc --defaults --sdk-path=/absolute/path/to/atmos/sdk

Try OCI publishing locally

The generated stacks/local.yaml configures an anonymous registry emulator on localhost:15557. With Docker running:

atmos dev registry up
atmos push
atmos plugin search oidc --registry=local
atmos plugin install local/acme/oidc --as=corporate --version=0.1.0
atmos plugin list
atmos dev registry down

No authentication is required for this local registry. atmos push builds, validates, tests, packs, and publishes. Search indexes the configured OCI repository and caches its release metadata locally; no catalog needs to be maintained. Push preserves numbered layouts under the gitignored .atmos/release/ directory. The emulator is ephemeral; stopping it discards registry contents. Change the port in stacks/local.yaml and its matching references in atmos.yaml if needed.

After publishing another version, use atmos plugin search oidc --registry local --refresh to refresh discovery immediately. Normal searches reuse the cached index.

For a remote registry, configure an auth identity and bind it with plugins.registries.<name>.identity. Then run atmos auth login --identity publisher and atmos push --to oci://registry.example.com/team/oidc. Use --sign --yes to sign the published release. Publishing does not update a shared catalog. The generated README includes a complete publishing identity example.