# atmos plugin create

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

> ⚠️ Experimental

## Usage

```shell
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.

```shell
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:

```shell
# 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:

```shell
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.