# atmos aws ecr login

Login to AWS Elastic Container Registry (ECR) using a named integration, an identity's linked integrations, or explicit registry URLs. Supports both private ECR (`aws/ecr`) and ECR Public (`aws/ecr-public`) registries. This command writes Docker credentials to the standard Docker config location.

## Usage

```shell
atmos aws ecr login [integration] [flags]
```

## Examples

```shell
# Login using a named integration (private ECR)
atmos aws ecr login dev/ecr/primary

# Login to ECR Public (public.ecr.aws) using ambient AWS credentials
atmos aws ecr login --public

# Login to ECR Public using a specific identity
atmos aws ecr login --public --identity dev-admin

# Login using an identity's linked integrations
atmos aws ecr login --identity dev-admin

# Pick an identity interactively (requires a TTY)
atmos aws ecr login --identity

# Login with explicit registry URL (uses current AWS credentials)
atmos aws ecr login --registry 123456789012.dkr.ecr.us-east-1.amazonaws.com

# Login to multiple explicit registries
atmos aws ecr login \
  --registry 123456789012.dkr.ecr.us-east-1.amazonaws.com \
  --registry 987654321098.dkr.ecr.us-west-2.amazonaws.com
```

## Arguments

- **`integration`**

  Name of the integration to use for ECR login. The integration must be configured in `auth.integrations` with `kind: aws/ecr` or `kind: aws/ecr-public`. When provided, Atmos authenticates the integration's linked identity and logs into the configured registry.

## Flags

- **`--public`**

  Log in to AWS ECR Public (`public.ecr.aws`) directly, without a named integration. By default this uses ambient AWS credentials (the AWS SDK default credential chain: environment variables, shared config/profile, SSO, IMDS/IRSA/ECS) — ideal for CI, where the runner already has credentials. Combine with `--identity` to use a specific Atmos identity's credentials instead. Authentication is always performed in `us-east-1`. Cannot be combined with an integration argument or `--registry`.
- **`--identity` (alias `-i`)**

  Identity name whose linked integrations should be executed. All `aws/ecr` and `aws/ecr-public` integrations that reference this identity will be triggered. This authenticates the identity first, then executes all its linked integrations. When combined with `--public`, the identity's credentials are used to log in to ECR Public.

  Passing `--identity` **without a value** opens an interactive picker to choose an identity (the same selector used by `atmos auth login`). This requires an interactive terminal (TTY); in CI or other non-interactive contexts it errors instead of prompting, so pass an explicit name there (`--identity <name>`).
- **`--registry` (alias `-r`)**

  Explicit ECR registry URL(s) for ad-hoc login. This mode uses the current AWS credentials from the environment (not Atmos identities). Can be specified multiple times for multiple registries.

  Format: `{account_id}.dkr.ecr.{region}.amazonaws.com`

## Configuration

ECR integrations are configured in `atmos.yaml` under `auth.integrations`:

```yaml
auth:
  providers:
    company-sso:
      kind: aws/iam-identity-center
      region: us-east-1
      start_url: https://company.awsapps.com/start/

  identities:
    dev-admin:
      kind: aws/permission-set
      via:
        provider: company-sso
      principal:
        name: AdministratorAccess
        account: dev

  # Integrations derive credentials from identities
  integrations:
    dev/ecr/primary:
      kind: aws/ecr
      via:
        identity: dev-admin           # Which identity provides AWS credentials
      spec:
        auto_provision: true          # Auto-trigger on identity login (default: true)
        registry:
          account_id: "123456789012"
          region: us-east-2

    dev/ecr/secondary:
      kind: aws/ecr
      via:
        identity: dev-admin
      spec:
        registry:
          account_id: "123456789012"
          region: us-west-2
```

### ECR Public Configuration

For a one-off ECR Public login, you don't need any configuration — just run `atmos aws ecr login --public`, which uses ambient AWS credentials (or pass `--identity <name>` to use a specific identity). This is the simplest option for CI.

To have ECR Public login happen automatically on `atmos auth login`, configure an `aws/ecr-public` integration kind. No registry block is needed since ECR Public is always `public.ecr.aws`:

```yaml
auth:
  integrations:
    ecr-public:
      kind: aws/ecr-public
      via:
        identity: dev-admin
      spec:
        auto_provision: true
```

### Integration Configuration Options

#### `aws/ecr` (Private ECR)

| Field | Required | Default | Description |
|-------|----------|---------|-------------|
| `kind` | Yes | - | Must be `aws/ecr` for private ECR integrations |
| `via.identity` | Yes | - | Name of identity providing AWS credentials |
| `spec.auto_provision` | No | `true` | Auto-trigger on identity login |
| `spec.registry.account_id` | Yes | - | AWS account ID for the ECR registry |
| `spec.registry.region` | Yes | - | AWS region for the ECR registry |

#### `aws/ecr-public` (ECR Public)

| Field | Required | Default | Description |
|-------|----------|---------|-------------|
| `kind` | Yes | - | Must be `aws/ecr-public` for ECR Public integrations |
| `via.identity` | Yes | - | Name of identity providing AWS credentials |
| `spec.auto_provision` | No | `true` | Auto-trigger on identity login |

ECR Public does not require a `spec.registry` block. The registry is always `public.ecr.aws` and authentication is always performed in `us-east-1`.

## How It Works

### Named Integration Mode

When you specify an integration name:

1. Atmos looks up the integration config from `auth.integrations`
2. Authenticates the linked identity (via `via.identity`)
3. For `aws/ecr`: calls `ecr:GetAuthorizationToken` using the identity's credentials
4. For `aws/ecr-public`: calls `ecr-public:GetAuthorizationToken` in `us-east-1`
5. Writes credentials to Docker config (`~/.docker/config.json`)

### Identity Mode

When you use `--identity`:

1. Atmos finds all integrations that reference the specified identity
2. Authenticates the identity
3. Executes each linked integration
4. Each integration writes its credentials to Docker config

### Explicit Registry Mode

When you use `--registry`:

1. Atmos uses the current AWS credentials from the environment
2. Parses the registry URL to extract account ID and region
3. Calls `ecr:GetAuthorizationToken`
4. Writes credentials to Docker config (`~/.docker/config.json`)

## Credential Storage

ECR credentials are written to `~/.docker/config.json` by default, the standard Docker config location. This means:

- Docker commands work immediately after login without additional configuration
- Credentials are merged with existing entries in your Docker config
- Respects `DOCKER_CONFIG` environment variable if set

If you need isolated credentials, set `DOCKER_CONFIG` before running the command:

```bash
export DOCKER_CONFIG=~/.config/atmos/docker
atmos aws ecr login dev/ecr/primary
```

## Auto-Provisioning

When `auto_provision` is `true` (the default), ECR integrations are automatically triggered when you authenticate with their linked identity:

```shell
$ atmos auth login dev-admin
Authenticating with identity: dev-admin
Opening browser for SSO authentication...
Successfully authenticated as dev-admin
✓ ECR login: 123456789012.dkr.ecr.us-east-2.amazonaws.com (expires in 11h59m)
✓ ECR login: 123456789012.dkr.ecr.us-west-2.amazonaws.com (expires in 11h59m)
```

To disable auto-provisioning for an integration, set `auto_provision: false`:

```yaml
integrations:
  dev/ecr/optional:
    kind: aws/ecr
    via:
      identity: dev-admin
    spec:
      auto_provision: false  # Only triggered via explicit `atmos aws ecr login` command
      registry:
        account_id: "123456789012"
        region: eu-west-1
```

## Error Handling

- **Named integration failures**: Return error to user (fatal)
- **Auto-provisioned integration failures**: Log warning and continue (non-fatal)
- **Invalid registry URL**: Return error with supported format

ECR integration failures during `atmos auth login` are logged but don't block authentication. Your identity credentials succeed even if ECR login fails.

## Notes

- ECR tokens expire after approximately 12 hours (AWS-enforced)
- The actual expiration time is displayed when login succeeds
- **Private ECR** (`aws/ecr`): requires `ecr:GetAuthorizationToken` IAM permission
- **ECR Public** (`aws/ecr-public`): requires `ecr-public:GetAuthorizationToken` and `sts:GetServiceBearerToken` IAM permissions. Authentication is always performed in `us-east-1`. ECR Public is only available in `us-east-1` and `us-west-2`.
- China and GovCloud regions are not supported for either integration kind

## See Also

- [Auth Login Command](/cli/commands/auth/login) - Authenticate with identities (triggers auto-provisioned integrations)
- [ECR Authentication Tutorial](/tutorials/ecr-authentication) - Step-by-step guide
- [Auth Configuration](/cli/configuration/auth) - Configure providers, identities, and integrations