# atmos version track add

Bring a dependency under version management by adding it to a track in `atmos.yaml`. Define its
desired version and update policy alongside the rest of your project's dependencies, 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
```

## Try it out

### version-tracker

Copy the example into a new directory and make it your own:

```shell
atmos init examples/version-tracker
cd version-tracker
```

Add a pinned tool dependency to your local catalog. No cloud credentials are needed.

```shell
atmos version track add demo-tool --ecosystem toolchain --package jq --desired 1.7.1
```

- [Installation guide](/install)
- [Explore the example](/examples/version-tracker)
- [Initialization and repository settings](/cli/commands/init#examples-and-source-directories)