# atmos version track add

Add a dependency entry to a version track in `atmos.yaml`, preserving comments and formatting.

When `--ecosystem` is omitted, Atmos infers it from the package coordinate:

- `actions/*` and other `owner/repo` action paths resolve to `github/actions`
- registry-hosted images such as `ghcr.io/...` resolve to `oci`
- bare tool names such as `opentofu` or `kubectl` resolve to `toolchain`
- other `owner/repo` coordinates resolve to `github`

## Usage

```shell
atmos version track add NAME [flags]
```

## Arguments

- **`NAME` required**
  Entry name used by 
  `!version`
  , 
  `{{ .version.name }}`
  , and marker annotations.

## Flags

- **`--package`**
  Package coordinate. Defaults to 
  `NAME`
  .
- **`--ecosystem`**
  Ecosystem such as 
  `github/actions`
  , 
  `github`
  , 
  `oci`
  , 
  `docker`
  , or 
  `toolchain`
  .
- **`--datasource`**
  Datasource override, such as 
  `github-tags`
  , 
  `github-releases`
  , 
  `oci-tags`
  , 
  `docker-tags`
  , or 
  `toolchain`
  .
- **`--provider`**
  Provider name from 
  `version.providers`
  .
- **`--desired`**
  Desired version: concrete, SemVer constraint, or 
  `latest`
  . Default is 
  `latest`
  .
- **`--group`**
  Version group name.
- **`--pin`**
  Pin policy. Use 
  `digest`
   or 
  `sha`
   to lock and render the immutable identifier.
- **`--include`**
  Candidate version patterns to include. Repeat the flag for multiple patterns.
- **`--exclude`**
  Candidate version patterns to exclude. Repeat the flag for multiple patterns.
- **`--prerelease`**
  Allow prerelease candidates for this entry.

## Examples

```shell
# Add a GitHub Action and pin it to the resolved commit SHA
atmos version track add checkout --package=actions/checkout --pin=sha

# Add a toolchain tool with a SemVer constraint
atmos version track add opentofu --desired="~1.10"

# Add a GitHub Action but exclude a known-bad tag
atmos version track add checkout --package=actions/checkout --desired=v6 --exclude=v6.0.0

# Add a container image on the prod track
atmos version track add nginx --package=library/nginx --track=prod
```