AzureCR · mabelegba · Jan 5, 2026 · Jan 4, 2026
diff --git a/src/acrcache/HISTORY.rst b/src/acrcache/HISTORY.rst
@@ -4,9 +4,10 @@ Release History
 ===============
 1.0.0c8
 ++++++
-* **BUGFIX**: Resolved issue with sync-referrers enabled without sync activesync
+* **BUGFIX**: Resolved issue with sync-referrers enabled without `--sync activesync`
   * Added validation to ensure `--sync-referrers` can only be used with `--sync activesync`
   * Ensured proper validation and assignment of managed identities in `az acr cache create` and `az acr cache update` commands
+  * Improved README documentation for clarity on parameter dependencies and usage examples
 
 
 1.0.0c7

diff --git a/src/acrcache/README.rst b/src/acrcache/README.rst
@@ -40,35 +40,36 @@ Installation
 
 3. After forking `azure-cli`, follow the below commands to setup
 
-      # Clone your forked repository
+    Clone your forked repository
 
-    - git clone `https://github.com/<your-github-name>/azure-cli.git`
+      - git clone `https://github.com/<your-github-name>/azure-cli.git`
 
-    - cd azure-cli
+      - cd azure-cli
 
-      # Add the Azure/azure-cli repository as upstream
+    Add the Azure/azure-cli repository as upstream
 
-    -  git remote add upstream https://github.com/Azure/azure-cli.git
+      -  git remote add upstream https://github.com/Azure/azure-cli.git
 
-    -  git fetch upstream
+      -  git fetch upstream
 
-      # Reset the default dev branch to track dev branch of Azure/azure-cli so you can use it to track the latest azure-cli code.
+    Reset the default dev branch to track dev branch of Azure/azure-cli so you can use it to track the latest azure-cli code.
 
-    -  git branch dev --set-upstream-to upstream/dev
+      -  git branch dev --set-upstream-to upstream/dev
 
-      # Develop with a new branch
+    Develop with a new branch
 
-    -  git checkout -b <feature_branch>
+      -  git checkout -b <feature_branch>
 
 
-    Do the same for `azure-cli-extensions` except that the default branch for it is main, run git branch main --set-upstream-to upstream/main instead.
-    Note: The ACR cache extension is in the `feature/artifactcache` branch of the `azure-cli-extensions` repository, do NOT merge changes into main.
+  Do the same for `azure-cli-extensions` except that the default branch for it is main, run git branch main --set-upstream-to upstream/main instead.
+  Note: The ACR cache extension is in the `feature/artifactcache` branch of the `azure-cli-extensions` repository, do NOT merge changes into main.
 
 4. Create a virtual environment in the directory that contains both your CLI and CLI extension clones
 
     ```sh
     python -m venv .venv
     ```
+
 5. Activate the virtual environment
 
     Windows CMD.exe:
@@ -83,30 +84,29 @@ Installation
 
       `source .venv/bin/activate`
 
-5. Install the required packages
-      - Install python dependencies
+6. Install the required packages
+    Install python dependencies
+        - python -m pip install -U pip
+
+        Due to a known issue, the Azure CLI currently requires an older version of setuptools (70.0.0) and wheel (0.30.0) because newer versions are incompatible and may cause installation or build                    failures.         
+        For more details, see the related issue: https://github.com/Azure/azure-cli/issues/29467
 
-           - python -m pip install -U pip
-
-          Due to a known issue, the Azure CLI currently requires an older version of setuptools (70.0.0) and wheel (0.30.0) because newer versions are incompatible and may cause installation or build                    failures.         
-          For more details, see the related issue: https://github.com/Azure/azure-cli/issues/29467
-
-           - pip install setuptools==70.0.0 	
+      - pip install setuptools==70.0.0 	
 
-           - pip install --force-reinstall wheel==0.30.0
+      - pip install --force-reinstall wheel==0.30.0
 
-       - Install azdev
+      - Install azdev
+
+      - pip install -U azdev
 
-           - pip install -U azdev
-
-       - Setup azdev
-           - azdev setup -c -r azure-cli-extensions/
+    Setup azdev
+      - azdev setup -c -r azure-cli-extensions/
 
-  6. Build extension
+7. Build extension
 
-      azdev extension build acrcache
+    azdev extension build acrcache
 
-Developing with the ACR Cache Extension
+**Developing with the ACR Cache Extension**
 ==========================================  
 
 Please write the description of changes which can be perceived by customers into HISTORY.rst.
@@ -115,139 +115,70 @@ If you want to release a new extension version, please update the version in set
 
 If you make changes to the extension, you can test it by running:
 
-azdev extension build "acrcache"
-
-this will build your new changes into the extension package which you will see immediately.
-
-## Usage
-
-### List cache rules
-
-```sh
-az acr cache list -r <registry-name>
-```
-
-### Create a cache rule
-
-#### Basic cache rule (pull-through cache)
-```sh
-az acr cache create -r <registry-name> -n <rule-name> -s <source-repo> -t <target-repo>
-```
-
-#### Cache rule with credential set
-```sh
-az acr cache create -r <registry-name> -n <rule-name> -s <source-repo> -t <target-repo> -c <credential-set>
-```
-
-#### Cache rule with user-assigned managed identity (ACR-to-ACR authentication)
-```sh
-az acr cache create -r <registry-name> -n <rule-name> -s <upstream-acr>.azurecr.io/<source-repo> -t <target-repo> \
-  --assign-identity /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>
-```
-
-#### Advanced cache rule with artifact sync and filtering
-```sh
-az acr cache create -r <registry-name> -n <rule-name> -s <source-repo> -t <target-repo> \
-  --sync activesync --platforms linux/amd64,linux/arm64 --sync-referrers enabled \
-  --include-artifact-types images,notary-project-signature
-```
+    - azdev extension build "acrcache"
 
-### Update a cache rule
+  **this will build your new changes into the extension package which you will see immediately.**
 
-#### Update credential set
-```sh
-az acr cache update -r <registry-name> -n <rule-name> -c <new-credential-set>
-```
+After building the extension, if you dont see your changes immediately outputed in the cli, you can run the following command to reinstall the newly built extension:
 
-#### Update with managed identity
-```sh
-az acr cache update -r <registry-name> -n <rule-name> \
-  --assign-identity /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>
-```
+    - az extension remove --name acrcache
+    - az extension add --source "path\dist\acrcache-1.0.<0rc8>-py3-none-any.whl" 
 
-#### Update sync settings and filters
-```sh
-az acr cache update -r <registry-name> -n <rule-name> --sync activesync --platforms linux/amd64 \
-  --sync-referrers enabled --include-artifact-types images
-```
 
-#### Remove credential set
-```sh
-az acr cache update -r <registry-name> -n <rule-name> --remove-cred-set
-```
-
-### Show a cache rule
-
-```sh
-az acr cache show -r <registry-name> -n <rule-name>
-```
-
-### Sync a specific tag immediately
-
-```sh
-az acr cache sync -r <registry-name> -n <rule-name> --image <tag>
-```
-
-### Delete a cache rule
-
-```sh
-az acr cache delete -r <registry-name> -n <rule-name>
-```
-
-## Authentication Methods
+**Usage**
+==============
 
-### User-Assigned Managed Identity
+**cache rules Create, update, list, show, and sync **
 
-The `--assign-identity` parameter enables secure authentication between Azure Container Registries using user-assigned managed identities. This is particularly useful for:
+    see `az acr cache -h` for more information and examples.
 
-- **Cross-subscription ACR caching**: Cache images from ACRs in different subscriptions within the same tenant
-- **Enhanced security**: Eliminates the need for credential sets in many scenarios
-- **Simplified authentication**: Uses Azure's managed identity infrastructure for secure access
+**Authentication Methods**
 
-#### Requirements
-- **Same tenant**: Both source and target registries must be in the same Azure AD tenant
-- **Permissions**: The managed identity must have `AcrPull` permissions on the source registry
-- **Identity location**: The managed identity must be in the same subscription as the target registry
-- **Cross-subscription support**: Registries can be in different subscriptions within the same tenant
+  ** User-Assigned Managed Identity**
 
-#### Resource ID Format
-```
-/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identity-name}
-```
+    The `--assign-identity` parameter enables secure authentication between Azure Container Registries using user-assigned managed identities. This is particularly useful for:
 
-#### Example Setup
-1. Create a user-assigned managed identity
-2. Assign `AcrPull` role to the identity on the source registry
-3. Create cache rule with the identity resource ID
+      - **Cross-subscription ACR caching**: Cache images from ACR to ACR within the same tenant
+      - **Enhanced security**: Eliminates the need for credential sets in many scenarios
+      - **Simplified authentication**: Uses Azure's managed identity infrastructure for secure access
 
-```sh
-# Create managed identity
-az identity create -g <resource-group> -n <identity-name>
+    Create cache rule with managed identity
+    ``` 
+      az acr cache create -r <target-registry> -n <rule-name> -s <source-registry>.azurecr.io/<repo> -t <target-repo> \
+      --assign-identity /subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>
+    ```  
 
-# Assign AcrPull permissions to source registry
-az role assignment create --assignee <identity-principal-id> --role AcrPull --scope <source-registry-id>
+  ** Credentials**
 
-# Create cache rule with managed identity
-az acr cache create -r <target-registry> -n <rule-name> -s <source-registry>.azurecr.io/<repo> -t <target-repo> \
-  --assign-identity /subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>
-```
+    If `--assign-identity` is not specified in a cache rule command, the extension will fall back to using existing credentials configured for the target registry. This may include:
 
-## Artifact Sync and Filtering
+      - Admin user credentials
+      - Service principal credentials
+
+    Create cache rule with credentials
+    ``` 
+        az acr cache create -r <target-registry> -n <rule-name> -s <source-registry>.azurecr.io/<repo> -t <target-repo> --credential-set
+    ```
 
-### Sync Modes
-- **PassiveSync** (default): Pull-through cache behavior - images are cached when pulled
-- **ActiveSync**: Proactive synchronization - images are automatically pulled and cached
+** Important Notes**
+==============
 
-### Important Notes
-- **--sync-referrers enabled** requires **--sync activesync**
-- Artifact filtering parameters (--platforms, --include-artifact-types, etc.) require **--sync activesync**
-- Tag filters (--starts-with, --ends-with, --contains) require **--sync activesync**
+  ** Sync Modes **
+    - **PassiveSync** (default): Pull-through cache behavior - images are cached when pulled
+    - **ActiveSync**: Proactive synchronization - images are automatically pulled and cached
+
+  ** Parameter Dependencies **
+    - --sync-referrers enabled requires **--sync activesync**
+    -  Artifact filtering parameters (--platforms, --include-artifact-types, etc.) require **--sync activesync**
+    -  Tag filters (--starts-with, --ends-with, --contains) require **--sync activesync**
 
-## Minimum Azure CLI Version
+** Minimum Azure CLI Version **
+==============
 
-This extension requires Azure CLI version **2.57.0** or higher.
+  This extension requires Azure CLI version **2.57.0** or higher.
+  You can check your Azure CLI version with:
 
-## Documentation
+    az version
 
 For more details, see the official [Azure CLI documentation](https://learn.microsoft.com/cli/azure/acr).
 

diff --git a/src/acrcache/azext_acrcache/_client_factory.py b/src/acrcache/azext_acrcache/_client_factory.py
@@ -14,4 +14,4 @@ def cf_acrreg(cli_ctx, *_):
     from azure.cli.core.commands.client_factory import get_mgmt_service_client, get_subscription_id
     from azext_acrcache.vendored_sdks.containerregistry.v2025_09_01_preview.generated.container_registry_management_client import ContainerRegistryManagementClient
     subscription_id = get_subscription_id(cli_ctx)
-    return get_mgmt_service_client(cli_ctx, ContainerRegistryManagementClient, subscription_id=subscription_id).registries
+    return get_mgmt_service_client(cli_ctx, ContainerRegistryManagementClient, subscription_id=subscription_id)
diff --git a/src/acrcache/azext_acrcache/cache.py b/src/acrcache/azext_acrcache/cache.py
@@ -464,12 +464,13 @@ def acr_cache_sync(cmd,
     rg = get_resource_group_name_by_registry_name(cmd.cli_ctx, registry_name, resource_group_name)
 
     rule = client.cache_rules.get(resource_group_name=rg,
-                                  registry_name=registry_name,
-                                  cache_rule_name=name)
+                      registry_name=registry_name,
+                      cache_rule_name=name)
+
     tag = image
     rule_id = rule.id
-    source_repo = rule.source_repository
-    target_repo = rule.target_repository
+    source_repo = rule.properties.source_repository
+    target_repo = rule.properties.target_repository
     source_image_str = source_repo[source_repo.find('/') + 1:] + ":" + tag
 
     import_source = ImportSource(source_image=source_image_str,
@@ -481,6 +482,6 @@ def acr_cache_sync(cmd,
                                    target_tags=[target_repo + ":" + tag])
 
     return client.registries.begin_import_image(resource_group_name=rg,
-                                                registry_name=registry_name,
-                                                parameters=params)
+                                    registry_name=registry_name,
+                                    parameters=params)