# Get started with chainctl URL: https://chainguard-docs-preview-git-1016-404s.chainguard.app/get-started/getting-started-with-chainctl.md Last Modified: October 8, 2026 Tags: chainctl, Getting Started Get started with chainctl basics including authentication, organization management, and essential commands for Chainguard's container security platform Chainguard's `chainctl` provides command-line access to manage container images, identity resources, and security configurations across your organization. This guide covers essential commands to begin using `chainctl` effectively in your security and DevOps workflows. For comprehensive command documentation, refer to the [chainctl reference](/platform/chainctl/). ## Authenticate and check auth status To use `chainctl`, the first thing you must do is [authenticate with the Chainguard platform](/chainguard/containers/registry/authenticating/). Do so with: ```shell chainctl auth login ``` This will present a list of identity providers for you to select from. Use the one that is tied to your Chainguard Account. Once you select the one you wish to use, such as Google, `chainctl` will open a browser window for you to log in with your credentials. Upon successful login, you will have the option to save this identity provider as your default for future logins. Then a token will be exchanged and you will be able to use `chainctl`.

Note: chainctl auth login supports several login flows, including device-code login for machines without a browser and assumable identities for CI. If the default browser flow doesn't work in your environment, see Authentication options.

To check your authentication status at any time, enter: ```shell chainctl auth status ``` This will list your identity and other attributes tied to your account, including your account's assigned roles and capabilities. To create a pull token, use: ```shell chainctl auth pull-token ``` One important flag you can pass to this command is the `--repository` flag, which allows you to specify the repository type to create the pull token for. For example, specifying `--repository=apk` binds the pull-token identity to the `apk.pull` role, allowing the identity to download packages from the private APK repository of the parent organization. To configure a Docker credential helper, which will use a token to pull images when using Docker, use: ```shell chainctl auth configure-docker ``` > **Note**:

Zscaler, a popular decrypting proxy, may not support encrypted HTTP/2 traffic by default. If you are having connection issues using chainctl behind Zscaler, follow these steps to enable support for HTTP/2.

  1. Open a Support Ticket with Zscaler

    Before any UI configuration option appears you may need to contact Zscaler Support (TAC) and request that HTTP/2 support be provisioned/activated for your tenant. This is currently a backend setting only Support can toggle.

    You typically need to provide:

    This will allow HTTP/2 negotiation to be available in policies.

  2. Enable HTTP/2 in SSL Inspection Policies

    Once Support has enabled HTTP/2 on your tenant:

    1. Log in to the Zscaler Admin Portal.
    2. Navigate to Policy → SSL Inspection (or Administration → Advanced Settings depending on UI version).
    3. Edit your relevant SSL Inspection Policy.
    4. Look for the option "Enable HTTP/2" and turn it ON for the required rules/policies.

    This setting ensures Zscaler will maintain HTTP/2 where possible rather than downgrading to HTTP/1.1. You may need to enable it on multiple rules if you use granular SSL policies (for example, by URL category).

  3. Check Advanced settings for API/CLI traffic

    Zscaler has an advanced setting under Admin → Advanced that controls how non-browser (API or CLI) HTTP/2 traffic is handled. This setting is disabled by default, which means Zscaler will downgrade non-browser HTTP/2 traffic to HTTP/1.1. For chainctl usage, this must be set to Enabled.

See this Zscaler blog post for more details.

If the above approach is not available to you, you may need to reconfigure Zscaler to disable its "Block Undecryptable Traffic" setting. Another option is to configure direct (proxyless) access to HTTP/2 endpoints and use the no_proxy environment variable, depending on your IT policies. Please consult your proxy software's documentation for guidance on adjusting these settings in order to authenticate.

## Update chainctl to the latest release To see which `chainctl` version you have installed, use: ```shell chainctl version ``` To update your `chainctl` installation, use: ```shell chainctl update ``` Because this replaces the installed binary, you need write access to the directory where `chainctl` lives. On Linux and macOS, updating a system-wide install such as `/usr/local/bin` requires administrative privileges (for example, with `sudo`). The command also verifies the downloaded binary's signature in-process before installing it; refer to [Updating chainctl](/platform/chainctl-usage/how-to-install-chainctl/#updating-chainctl) for details. ## Configure chainctl `chainctl` comes with a default configuration, but there are aspects of it that can be adjusted. Examples include setting the registry location that will be used when one is not mentioned in an issued command. To edit the current configuration, use: ```shell chainctl config edit ``` If you make a mistake and can't recall the original settings, reset the configuration to default settings with: ```shell chainctl config reset ``` Learn more at [How to manage chainctl configuration](/platform/chainctl-usage/manage-chainctl-config/). ## List available images To see which container images are available to your account, use: ```shell chainctl images list ``` Be warned, that list may take a while to generate and is likely to scroll past quickly in your command line terminal. ## Compare two image versions Let's say you want to compare two versions of an image for the same package. You need to know the URL for your repo, the image name, and the two versions you want to compare. For versions, you can use release numbers like `8.12.0` or you can use `latest` or `latest-dev`. Use this, where we show the repo used by our Chainguard Developer Education team and where both instances of `` are the same: ```shell chainctl images diff cgr.dev/chainguard.edu/$IMAGENAME:latest cgr.dev/chainguard.edu/$IMAGENAME:latest-dev ``` If a requested image or release being requested is not available in the repo you are using, this will return a `Forbidden` error, just like if you tried to pull an image you did not have access to or from a repository your account is not authorized to use. Learn more at [How to compare Chainguard Containers with chainctl](/platform/chainctl-usage/comparing-images/). ## List available package versions If you want to get details about the various package versions available that can be used in images, use: ```shell chainctl packages versions list $PACKAGENAME ``` This will list all the versions that Chainguard has built and the end-of-life date for each version that has one assigned. It will also list older package versions that are no longer available. ## Output formats Commands may have a default format for output, but that doesn't mean you have to stick with it. There is an option available to tell `chainctl` the output format to use, like this: ```shell chainctl $COMMAND -o $FORMAT ``` The `-o` is followed by one of the following strings: `csv`, `id`, `json`, `none`, `table`, `terse`, `tree`, or `wide`. Not all output formats make sense for all commands, so test thoroughly before you use any specific format in automation.