Azure Container Registry CLI
Use the Azure CLI az acr command group to create registries, authenticate clients, build or import images, manage repositories and tags, configure security and networking, and diagnose Azure Container Registry behavior.
When to invoke
- "Create an Azure Container Registry and push an image."
- "Use az acr build instead of local Docker."
- "Diagnose ACR login or pull permissions."
- "Import or purge images in Azure Container Registry."
- "Configure ACR geo-replication, Private Link, or repository tokens."
Prerequisites and context
az acr ships with the core Azure CLI; no extension is required for normal registry work. The acrtransfer extension is only needed for export/import pipeline commands.
# Install Azure CLI
brew install azure-cli
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash
winget install Microsoft.AzureCLI
# Sign in and select subscription
az login
az account set --subscription {subscription-id}
Confirm the resource group, registry name, subscription, SKU, and identity model before running mutating commands.
Command map
| Need |
Command pattern |
Notes |
| Registry lifecycle |
az acr create --resource-group {rg} --name {registry} --sku Standard |
SKU is Basic, Standard, or Premium. |
| Docker/Podman login |
az acr login --name {registry} |
Uses local credential helper. Use --expose-token for token-based flows. |
| Cloud build |
az acr build --registry {registry} --image app:v1 . |
No local Docker daemon required. |
| Server-side copy |
az acr import --name {registry} --source mcr.microsoft.com/hello-world:latest |
Avoids local pull and push. |
| Repositories |
az acr repository list --name {registry} --output table |
Inventory repositories. |
| Tags |
az acr repository show-tags --name {registry} --repository app --orderby time_desc |
Sort by recency for cleanup. |
| Health |
az acr check-health --name {registry} --yes |
Diagnoses Docker daemon, network, auth, and config. |
| Usage |
az acr show-usage --name {registry} |
Review quota and storage. |
Common task phrases include pushing/importing/purging images and replacing local pull/push loops with server-side operations.
ACR principles
| Principle |
Why it matters |
Prefer az acr build and ACR Tasks over docker build plus docker push. |
Builds run in Azure, work without a local daemon, and integrate with source, base-image, and timer triggers. |
Prefer az acr import for registry-to-registry movement. |
Import is server-side, faster, and does not require local storage. |
| Never enable the admin user for production. |
Use Microsoft Entra identities, managed identities, RBAC roles AcrPull and AcrPush, ABAC roles Container Registry Repository Reader and Container Registry Repository Writer, or repository-scoped tokens. |
| Treat Premium-only features as design choices. |
Geo-replication, private endpoints, retention policies, connected registries, and agent pools require Premium. Repository-scoped tokens work in all tiers; zone redundancy is automatic in supported regions. |
| Distinguish untag from delete. |
Removing a tag may leave manifests; deleting manifests removes content. Use retention, soft delete, and purge intentionally. |
The repository command family covers List/show/delete/untag actions, Push/delete webhooks, artifact cache pull-through rules, soft-delete configuration, content-trust, and git/base-image/timer task triggers. ABAC-enabled registries may use Container Registry Repository Reader/Writer for scoped reads and writes.
CLI structure
az acr
├── create / delete / list / show / update
├── login
├── check-health / check-name / show-usage
├── build
├── run
├── task
├── agentpool
├── import
├── repository
├── manifest
├── credential
├── token / scope-map
├── replication
├── network-rule
├── private-endpoint-connection
├── config
├── cache / credential-set
├── webhook
├── connected-registry
└── export-pipeline / import-pipeline / pipeline-run
Procedure
- Run
az account show and confirm the target subscription if the task mutates resources.
- Choose the smallest command group that matches the task: lifecycle, auth, build, repository, networking, or diagnostics.
- Prefer read-only
show, list, show-tags, show-usage, and check-health commands before destructive updates.
- For builds, imports, purges, retention, private endpoints, geo-replication, or repository-scoped tokens, read the relevant bundled reference first.
- Execute the command with explicit
--resource-group, --name, --repository, --image, --output, and confirmation flags rather than relying on defaults.
- Report the command, registry, affected repository or tag, and any quota, auth, or network diagnostic result.
Progressive disclosure and bundled resources
| Resource |
Read when |
Covers |
references/auth-and-security.md |
Login, permissions, CI/CD, AKS pull access, tokens, or admin-user questions. |
az acr login, --expose-token, Entra RBAC, service principals, managed identities, --attach-acr, repository-scoped tokens, scope maps, content trust. |
references/build-and-tasks.md |
Building images in Azure or automating builds. |
az acr build, az acr run, multi-step task YAML, az acr task, git triggers, base-image triggers, timer triggers, logs, runs, agent pools. |
references/images-and-artifacts.md |
Repositories, tags, cleanup, storage costs, artifact cache. |
az acr import, repository and manifest commands, untag vs delete, acr purge, image locking, retention policy, soft delete, show-usage. |
references/networking-and-geo.md |
Multi-region, private access, edge, or transfer scenarios. |
Geo-replication, zone redundancy, private endpoints, network rules, dedicated data endpoints, connected registries, registry transfer pipelines. |
Gotchas
- Admin user is not production auth: enabling it creates broad registry credentials; use identity-based pull and push instead.
- Private endpoints change DNS and network paths: a successful role assignment does not prove network reachability.
- ACR Tasks are not local builds: build context, secrets, and Dockerfile paths must be valid from the cloud task environment.
acrtransfer is separate: install it only for export/import pipeline workflows, not for normal az acr import.
Output template
## Azure Container Registry CLI result
**Status:** complete | needs input | blocked
**Registry:** `{registry}`
**Subscription:** `{subscription-id}`
**Operation:** <lifecycle | auth | build | import | repository | networking | diagnostics>
### Commands
```bash
<az acr command executed or recommended>
Result
- Affected resource: <registry/repository/tag/task>
- Output or diagnostic evidence:
- Follow-up:
## Quality gate
- [ ] The target subscription, resource group, registry, and SKU assumptions are explicit.
- [ ] Mutating operations use explicit flags and avoid relying on ambient defaults.
- [ ] Production auth avoids the admin user unless the user explicitly accepts the risk.
- [ ] Premium-only features are identified before commands are recommended.
- [ ] Image cleanup distinguishes tag removal, manifest deletion, retention, soft delete, and `acr purge`.
- [ ] The relevant bundled reference was read for auth, builds, artifacts, networking, or geo-replication work.
## References
- [Install Azure CLI on Linux](https://aka.ms/InstallAzureCLIDeb)
1---2name: azure-container-registry-cli-23description: Manage Azure Container Registry with az acr CLI commands for registries, images, cloud builds, ACR Tasks, authentication, tokens, geo-replication, networking, purge, import, and diagnostics. Use when working with ACR, az acr, pushing or importing container images in Azure, or Azure Container Registry operations.4---56# Azure Container Registry CLI78Use the Azure CLI `az acr` command group to create registries, authenticate clients, build or import images, manage repositories and tags, configure security and networking, and diagnose Azure Container Registry behavior.910## When to invoke1112- "Create an Azure Container Registry and push an image."13- "Use az acr build instead of local Docker."14- "Diagnose ACR login or pull permissions."15- "Import or purge images in Azure Container Registry."16- "Configure ACR geo-replication, Private Link, or repository tokens."1718## Prerequisites and context1920`az acr` ships with the core Azure CLI; no extension is required for normal registry work. The `acrtransfer` extension is only needed for export/import pipeline commands.2122```bash23# Install Azure CLI24brew install azure-cli25curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash26winget install Microsoft.AzureCLI2728# Sign in and select subscription29az login30az account set --subscription {subscription-id}31```3233Confirm the resource group, registry name, subscription, SKU, and identity model before running mutating commands.3435## Command map3637| Need | Command pattern | Notes |38| --- | --- | --- |39| Registry lifecycle | `az acr create --resource-group {rg} --name {registry} --sku Standard` | SKU is `Basic`, `Standard`, or `Premium`. |40| Docker/Podman login | `az acr login --name {registry}` | Uses local credential helper. Use `--expose-token` for token-based flows. |41| Cloud build | `az acr build --registry {registry} --image app:v1 .` | No local Docker daemon required. |42| Server-side copy | `az acr import --name {registry} --source mcr.microsoft.com/hello-world:latest` | Avoids local pull and push. |43| Repositories | `az acr repository list --name {registry} --output table` | Inventory repositories. |44| Tags | `az acr repository show-tags --name {registry} --repository app --orderby time_desc` | Sort by recency for cleanup. |45| Health | `az acr check-health --name {registry} --yes` | Diagnoses Docker daemon, network, auth, and config. |46| Usage | `az acr show-usage --name {registry}` | Review quota and storage. |4748Common task phrases include pushing/importing/purging images and replacing local pull/push loops with server-side operations.4950## ACR principles5152| Principle | Why it matters |53| --- | --- |54| Prefer `az acr build` and ACR Tasks over `docker build` plus `docker push`. | Builds run in Azure, work without a local daemon, and integrate with source, base-image, and timer triggers. |55| Prefer `az acr import` for registry-to-registry movement. | Import is server-side, faster, and does not require local storage. |56| Never enable the admin user for production. | Use Microsoft Entra identities, managed identities, RBAC roles `AcrPull` and `AcrPush`, ABAC roles `Container Registry Repository Reader` and `Container Registry Repository Writer`, or repository-scoped tokens. |57| Treat Premium-only features as design choices. | Geo-replication, private endpoints, retention policies, connected registries, and agent pools require Premium. Repository-scoped tokens work in all tiers; zone redundancy is automatic in supported regions. |58| Distinguish untag from delete. | Removing a tag may leave manifests; deleting manifests removes content. Use retention, soft delete, and purge intentionally. |5960The repository command family covers List/show/delete/untag actions, Push/delete webhooks, artifact cache pull-through rules, soft-delete configuration, `content-trust`, and git/base-image/timer task triggers. ABAC-enabled registries may use `Container Registry Repository Reader`/`Writer` for scoped reads and writes.6162## CLI structure6364```text65az acr66├── create / delete / list / show / update67├── login68├── check-health / check-name / show-usage69├── build70├── run71├── task72├── agentpool73├── import74├── repository75├── manifest76├── credential77├── token / scope-map78├── replication79├── network-rule80├── private-endpoint-connection81├── config82├── cache / credential-set83├── webhook84├── connected-registry85└── export-pipeline / import-pipeline / pipeline-run86```8788## Procedure89901. Run `az account show` and confirm the target subscription if the task mutates resources.912. Choose the smallest command group that matches the task: lifecycle, auth, build, repository, networking, or diagnostics.923. Prefer read-only `show`, `list`, `show-tags`, `show-usage`, and `check-health` commands before destructive updates.934. For builds, imports, purges, retention, private endpoints, geo-replication, or repository-scoped tokens, read the relevant bundled reference first.945. Execute the command with explicit `--resource-group`, `--name`, `--repository`, `--image`, `--output`, and confirmation flags rather than relying on defaults.956. Report the command, registry, affected repository or tag, and any quota, auth, or network diagnostic result.9697## Progressive disclosure and bundled resources9899| Resource | Read when | Covers |100| --- | --- | --- |101| `references/auth-and-security.md` | Login, permissions, CI/CD, AKS pull access, tokens, or admin-user questions. | `az acr login`, `--expose-token`, Entra RBAC, service principals, managed identities, `--attach-acr`, repository-scoped tokens, scope maps, content trust. |102| `references/build-and-tasks.md` | Building images in Azure or automating builds. | `az acr build`, `az acr run`, multi-step task YAML, `az acr task`, git triggers, base-image triggers, timer triggers, logs, runs, agent pools. |103| `references/images-and-artifacts.md` | Repositories, tags, cleanup, storage costs, artifact cache. | `az acr import`, repository and manifest commands, untag vs delete, `acr purge`, image locking, retention policy, soft delete, `show-usage`. |104| `references/networking-and-geo.md` | Multi-region, private access, edge, or transfer scenarios. | Geo-replication, zone redundancy, private endpoints, network rules, dedicated data endpoints, connected registries, registry transfer pipelines. |105106## Gotchas107108- **Admin user is not production auth**: enabling it creates broad registry credentials; use identity-based pull and push instead.109- **Private endpoints change DNS and network paths**: a successful role assignment does not prove network reachability.110- **ACR Tasks are not local builds**: build context, secrets, and Dockerfile paths must be valid from the cloud task environment.111- **`acrtransfer` is separate**: install it only for export/import pipeline workflows, not for normal `az acr import`.112113## Output template114115```markdown116## Azure Container Registry CLI result117118**Status:** complete | needs input | blocked119**Registry:** `{registry}`120**Subscription:** `{subscription-id}`121**Operation:** <lifecycle | auth | build | import | repository | networking | diagnostics>122123### Commands124```bash125<az acr command executed or recommended>126```127128### Result129- Affected resource: <registry/repository/tag/task>130- Output or diagnostic evidence: <summary>131- Follow-up: <next command or none>132```133134## Quality gate135136- [ ] The target subscription, resource group, registry, and SKU assumptions are explicit.137- [ ] Mutating operations use explicit flags and avoid relying on ambient defaults.138- [ ] Production auth avoids the admin user unless the user explicitly accepts the risk.139- [ ] Premium-only features are identified before commands are recommended.140- [ ] Image cleanup distinguishes tag removal, manifest deletion, retention, soft delete, and `acr purge`.141- [ ] The relevant bundled reference was read for auth, builds, artifacts, networking, or geo-replication work.142143## References144145- [Install Azure CLI on Linux](https://aka.ms/InstallAzureCLIDeb)
paulasilvatech