The gdcloud CLI is a set of tools to create and manage
Google Distributed Cloud (GDC) air-gapped resources. Use these tools to perform common
tasks from the command line or through scripts and automation. The
gdcloud CLI lets you bootstrap infrastructure, manage authentication,
and customize local configurations.

This document is for all audience groups that need to set up
GDC's dedicated CLI to manage their air-gapped hardware
and software workflows. For more information, see
[Audiences for GDC air-gapped documentation](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/audiences.md.txt).

## Before you begin

- Confirm that you have access to the GDC console and note your
  organization's URL. For more information, see
  [GDC console access](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/get-started/console.md.txt).

- Confirm that you have a Certificate Authority (CA) certificate that is installed in
  your system's trusted certificates store. For more information, see
  [Fetch GDC trust bundles](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform/pa-user/pki/fetch-trust-bundles.md.txt).

- Verify that you have an organization network policy that allows traffic from a
  specific CIDR outside your organization to the artifact registry. For example,
  configure service name `all` in the `OrganizationNetworkPolicy` resource. For
  more information, see
  [Create organization network policies](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag//platform/pa-user/org-network-policy).

- Confirm that you have a browser installed on your device.

## Set up the gdcloud CLI

To set up the gdcloud CLI, complete the following:

1. Open the GDC console by inputting your organization's global or
   zonal URL in your browser.

2. From the home page, select **Download CLI Bundle**.

3. Select the Linux platform and the gdcloud CLI bundle version that
   corresponds with your GDC environment.

   When choosing non-Linux platforms, the configuration steps might vary
   slightly. Also be aware that some non-Linux gdcloud CLI bundles
   only provide a subset of gdcloud commands. For more
   information, see
   [Available gdcloud CLI bundles](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/gdcloud-overview.md.txt#cli-support).
4. Click **Download**.

5. From your device, navigate to the `Downloads` folder:

   ```bash
   cd ~/Downloads
   ```
6. Extract the contents of the gdcloud CLI bundle:

   ```bash
   tar -xf ./gdcloud_cli.tar.gz
   ```
7. Add the gdcloud CLI bundle to your path:

   ```bash
   eval echo 'export GDCLOUD_PATH=$(pwd)/google-distributed-cloud-hosted-cli' >> ~/.bashrc
   echo 'export PATH="$GDCLOUD_PATH/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc
   ```
8. Confirm the gdcloud CLI is installed correctly:

   ```bash
   gdcloud version
   ```

   The output is similar to the following:

       gdcloud version: 1.15.0-gdch.380608

9. Initialize the gdcloud CLI:

   ```bash
   gdcloud init
   ```
10. Provide the two prompted properties to complete the initialization:

    - `organization_console_url`: the URL to your current
      GDC organization's console. This URL can be global
      or zonal. For example, `https://console.org-1.google.gdch.test/`.

    - `project`: the name of your GDC project. If you
      don't have an existing project, use `default`.

    To update your gdcloud CLI configurations after initialization, see
    [Manage gdcloud CLI configurations](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/gdcloud-manage-configurations.md.txt).
11. Install the `gdcloud-k8s-auth-plugin` component:

    ```bash
    gdcloud components install gdcloud-k8s-auth-plugin
    ```
12. Authenticate with the gdcloud CLI to sign in:

    ```bash
    gdcloud auth login
    ```

    You're redirected to the browser to choose your identity and sign in.
13. Confirm your gdcloud CLI setup is connected to your
    GDC environment:

    ```bash
    gdcloud compute images list
    ```

    The output is similar to the following:

        METADATA.NAME               METADATA.NAMESPACE SPEC.OPERATINGSYSTEM.NAME SPEC.MINIMUMDISKSIZE
        rocky-8-v20250809-gdch      vm-system          rocky-linux-8             12G
        ubuntu-20.04-v20250809-gdch vm-system          ubuntu-2004               12G
        ubuntu-22.04-v20250809-gdch vm-system          ubuntu-2204               12G
        ubuntu-24.04-v20250809-gdch vm-system          ubuntu-2404               12G

## What's next

- [gdcloud CLI overview](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/gdcloud-overview.md.txt)
- [gdcloud CLI authentication](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/gdcloud-auth.md.txt)
- [Manage gdcloud CLI properties](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/gdcloud-manage-properties.md.txt)