#Common CLI Command Operations

Use the ac CLI for platform login, namespace permission management, and Registry metadata operations. Use a standard OCI client such as nerdctl for image transfer operations such as push and pull.

The examples below assume:

• Registry client address: <REGISTRY_CLIENT_HOSTPORT>
• Registry API URL: <REGISTRY_API_URL>
• Current namespace: my-ns

#Before You Begin

Before running the commands in this document, make sure:

• ac is installed.
• nerdctl is installed if you need to push or pull images.
• You can reach the ACP API endpoint and the Registry address from your current environment.
• You have logged in to ACP and selected the target cluster.
• Your current ACP account, or the ServiceAccount used in a Pod or Job, has the required namespace permissions.

Typical permission requirements:

• Pull images: system:image-puller
• Push images: system:image-pusher
• List images with ac get images: access to the target namespaces
• Delete images with ac delete images: permission to delete images in the target namespaces

If you run ac inside a Pod, Job, or CronJob:

• The Pod must use a valid serviceAccountName.
• The mounted ServiceAccount token must be available.
• The ServiceAccount must have permissions to access the target cluster and Registry-related APIs.

#How Authentication Works

ac and nerdctl use different authentication paths:

• ac uses the current ACP login session for Registry-related API access.
• If ac runs inside a Pod and no ACP session is available, it can fall back to the mounted ServiceAccount token.
• nerdctl authenticates directly to the Registry, typically by using the same ACP account credentials that already have access to the target namespace.

Address usage in this document:

• <REGISTRY_CLIENT_HOSTPORT> is the Registry address used by OCI clients such as nerdctl.
• <REGISTRY_API_URL> is the Registry API endpoint used by ac get images and ac delete images.
• In external access scenarios, ac should typically use an explicitly specified --registry-url instead of relying on the default in-cluster Registry address.

#Authenticate to ACP

Before using Registry-related commands in ac, log in and select the target cluster:

ac login <acp-url>
ac config get-clusters
ac config use-cluster <cluster-name>

After login, ac can use the current session to access Registry-related APIs such as ac get images and ac delete images.

#Grant namespace permissions to a user

Add namespace pull permission for a user.

ac create rolebinding <binding-name> --clusterrole=system:image-puller --user=<username> -n <namespace>

Add namespace push permissions to a user.

ac create rolebinding <binding-name> --clusterrole=system:image-pusher --user=<username> -n <namespace>

#Grant namespace permissions to a ServiceAccount

Add namespace pull permission for a service account.

ac create rolebinding <binding-name> --clusterrole=system:image-puller --serviceaccount=<namespace>:<serviceaccount-name> -n <namespace>

Add namespace push permission for a service account.

ac create rolebinding <binding-name> --clusterrole=system:image-pusher --serviceaccount=<namespace>:<serviceaccount-name> -n <namespace>

#Authenticate an OCI Client

For image push and pull, use the same ACP account credentials that have access to the target namespace:

nerdctl login <REGISTRY_CLIENT_HOSTPORT> -u <ACP-USERNAME> -p <ACP-PASSWORD>

If the Registry uses a self-signed certificate or plain HTTP, add the global flag --insecure-registry.

Example:

nerdctl --insecure-registry login <REGISTRY_CLIENT_HOSTPORT> -u <ACP-USERNAME> -p <ACP-PASSWORD>

#List Images

List images from namespaces that the current user is allowed to access:

ac get images --registry-url=<REGISTRY_API_URL>

# List images from a specific namespace
ac get images -n my-ns --registry-url=<REGISTRY_API_URL>

# Use structured output
ac get images -o yaml --registry-url=<REGISTRY_API_URL>

When ac runs outside the cluster, explicitly specifying --registry-url is recommended. Otherwise, the CLI may fall back to the default in-cluster Registry address, which is often unreachable from a local workstation.

Example:

ac get images --registry-url=<REGISTRY_API_URL>

#Pull Images

Pull an image from the Registry with nerdctl:

# Pull an image from the current namespace
nerdctl pull <REGISTRY_CLIENT_HOSTPORT>/my-ns/my-app:latest

# Pull an image from another namespace when you already have permission
nerdctl pull <REGISTRY_CLIENT_HOSTPORT>/shared-ns/base-image:latest

#Push Images

Push a local image to the current namespace:

# Tag the local image with the target repository
nerdctl tag my-app:latest <REGISTRY_CLIENT_HOSTPORT>/my-ns/my-app:v1

# Push it to the Registry
nerdctl push <REGISTRY_CLIENT_HOSTPORT>/my-ns/my-app:v1

Copy an image from another registry into ACP Registry:

# Pull the source image
nerdctl pull remote.registry.io/demo/my-app:latest

# Retag it for ACP Registry
nerdctl tag remote.registry.io/demo/my-app:latest <REGISTRY_CLIENT_HOSTPORT>/my-ns/my-app:latest

# Push it to ACP Registry
nerdctl push <REGISTRY_CLIENT_HOSTPORT>/my-ns/my-app:latest

#Delete Images

Use ac delete images to remove image tags from the Registry:

# Preview the deletion result without removing anything
ac delete images --repo=my-ns/my-app:v1 --registry-url=<REGISTRY_API_URL>

# Confirm the deletion
ac delete images --repo=my-ns/my-app:v1 --registry-url=<REGISTRY_API_URL> --confirm

Notes:

• This operation removes the image manifest reference from the Registry, but it does not guarantee that the underlying image data is reclaimed immediately.
• In the current implementation, if multiple tags point to the same manifest digest, deleting one tag may also remove the sibling tags that reference the same manifest.

Example:

ac delete images \
  --repo=my-ns/my-app:v1 \
  --registry-url=<REGISTRY_API_URL> \
  --confirm