#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: permission to access the namespace specified with -n; use -A only when you need to scan every namespace the current user can access

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.
• 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.

#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

For better performance, query a specific namespace whenever possible:

ac get images -n my-ns --registry-url=<REGISTRY_API_URL>

If the current context already specifies the target namespace, you can omit -n. If the current context does not specify a namespace, default is used.

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

Use -A only when you need to list images from every namespace that the current user is authorized to access. This can be slower on clusters with many namespaces or repositories.

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

By default, the output contains only REPOSITORY and TAG columns. Keep the default output for routine queries. Add -o wide only when you need created time and digest metadata because it requires additional metadata lookup and can increase command latency.

Use structured output when automation needs machine-readable data:

ac get images -n my-ns -o yaml --registry-url=<REGISTRY_API_URL>

For JSON and YAML output, the default output also contains only repository and tag fields. Use -o wide only when digest and created-time metadata are required.

For large registries, you can tune the Registry catalog page size. The default is 200. Do not increase it unless you need larger catalog pages.

ac get images -n my-ns --catalog-page-size=1000 --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.

#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