ArgoCD Command Line Interface (CLI) Setup & Enterprise Administration Guide

Table of Contents

• 1. Introduction to the ArgoCD CLI
• 2. What You Will Learn
• 3. Prerequisites
• 4. Architecture and Internal Workflows
• 5. Multi-Platform Installation & Verification
• 6. Shell Autocompletion Setup
• 7. Enterprise Authentication Mechanisms
• 8. Security Hardening and TLS Management
• 9. Command Reference & High-Performance Workflows
• 10. Advanced CLI Scripting & CI/CD Automation
• 11. Troubleshooting & Debugging Common Errors
• 12. Monitoring & Auditing CLI Operations
• 13. Enterprise Interview Questions & Detailed Answers
• 14. Frequently Asked Questions (FAQs)
• 15. Summary & Next Steps

1. Introduction to the ArgoCD CLI

The ArgoCD Command Line Interface (CLI) is a powerful tool for managing, configuring, and automating ArgoCD instances. While the ArgoCD Web UI provides an excellent visual dashboard for developers and operations teams, the CLI serves as the backbone for administrative tasks, automated CI/CD pipelines, scriptable disaster recovery procedures, and multi-cluster GitOps orchestration.

In enterprise-grade GitOps architectures, relying solely on a graphical interface is an anti-pattern. Automated pipelines require a programmatic, low-latency, and highly secure interface to interact with the ArgoCD API server. The ArgoCD CLI acts as a wrapper around the ArgoCD gRPC and HTTP/S APIs, providing a declarative and imperative hybrid interface to manage applications, clusters, repositories, and access control policies.

Featured Snippet: What is the ArgoCD CLI?
The ArgoCD CLI is a native, compiled binary written in Go that communicates directly with the ArgoCD API Server (argocd-server) using high-performance gRPC or gRPC-web protocols. It allows administrators and CI/CD runners to programmatically manage ArgoCD configurations, sync applications, register target Kubernetes clusters, manage OIDC credentials, and execute dry-run diffs directly from terminal environments and automated delivery pipelines.

Understanding how to properly install, secure, and automate this tool is critical for any Platform Engineer or DevOps Architect. This guide covers everything from basic binary installation to advanced enterprise OIDC authentication flows and automated shell scripting patterns.

2. What You Will Learn

By the end of this comprehensive guide, you will be able to:

• Understand the underlying architecture and network protocols (gRPC, gRPC-web, HTTP/2) used by the ArgoCD CLI.
• Install and verify the ArgoCD CLI across Linux, macOS, and Windows operating systems using secure, cryptographically verified methods.
• Configure advanced shell autocompletions for Bash, Zsh, and Fish to accelerate your daily operational workflows.
• Authenticate securely against local, OIDC/SSO (Okta, Azure AD, Keycloak), and headless CI/CD service accounts.
• Implement enterprise-grade security practices, including custom Private PKI CA certificate injection and secure local credential storage.
• Write production-ready, idempotent Bash and GitHub Actions automation scripts using the CLI to orchestrate syncs, handle rollbacks, and capture structural diffs.
• Troubleshoot complex networking, authentication, and protocol negotiation issues occurring between the CLI and the API Gateway.

3. Prerequisites

Before proceeding with the installation and configuration of the ArgoCD CLI, ensure your environment meets the following requirements:

• A Running ArgoCD Instance: You must have access to an active ArgoCD installation. If you have not set one up yet, follow the Installing ArgoCD on Kubernetes guide.
• Kubernetes Cluster Access: Administrative or read-write access to a Kubernetes cluster via kubectl is highly recommended, especially when performing initial administrative login setup or cluster registration.
• Network Connectivity: Unrestricted network path (or appropriate proxy/VPN configuration) to the ArgoCD API server endpoint on ports 443 or 80.
• Local Shell Environment: A modern terminal shell (Bash v4+, Zsh, or PowerShell) with utility tools such as curl, openssl, and jq installed.

4. Architecture and Internal Workflows

To operate and troubleshoot the ArgoCD CLI at scale, it is essential to understand its communication paths and architecture. The CLI does not interact directly with the Kubernetes API server of the management cluster or target clusters (except during initial target cluster registration). Instead, it communicates exclusively with the argocd-server component.

CLI to API Server Communication Flow

The ArgoCD CLI uses two primary application-layer protocols to communicate with the argocd-server:

• gRPC over HTTP/2: This is the default, high-performance protocol. It enables multiplexed, bi-directional streaming of resources, allowing operations like log streaming (argocd app logs) and real-time resource tracking to run with minimal latency and network overhead.
• gRPC-web over HTTP/1.1 or HTTP/2: Used when the CLI is forced to route traffic through reverse proxies, Ingress controllers, or Web Application Firewalls (WAFs) that do not support raw HTTP/2 gRPC framing. You can force this mode using the --grpc-web CLI flag.

+---------------------------------------------------------------------------------+
|                                LOCAL WORKSTATION                                |
|                                                                                 |
|  +------------------+      gRPC / HTTP/2 (Default)      +--------------------+  |
|  |   ArgoCD CLI     |==================================>|  Local Config      |  |
|  |  (Go Binary)     |                                   |  ~/.config/argocd  |  |
|  +------------------+                                   +--------------------+  |
+-----------||--------------------------------------------------------------------+
            ||
            || (Encrypted TLS Tunnel)
            \/
+---------------------------------------------------------------------------------+
|                           KUBERNETES MANAGEMENT CLUSTER                         |
|                                                                                 |
|  +---------------------------------------------------------------------------+  |
|  |                          Ingress / LoadBalancer                           |  |
|  +---------------------------------------------------------------------------+  |
|                                       ||                                        |
|                                       \/                                        |
|  +---------------------------------------------------------------------------+  |
|  |                         argocd-server (Pod)                               |  |
|  |  - Authenticates request (JWT / Session Token validation)                 |  |
|  |  - Authorizes action via RBAC (argocd-rbac-cm)                            |  |
|  |  - Translates CLI commands to Kubernetes API actions                      |  |
|  +---------------------------------------------------------------------------+  |
|                     ||                                     ||                   |
|                     \/                                     \/                   |
|  +-------------------------------------+     +-------------------------------+  |
|  |     Application Controllers         |     |      Redis Cache Database     |  |
|  |  (Reconciliation & State Sync)     |     |  (Session & Cluster Metadata) |  |
|  +-------------------------------------+     +-------------------------------+  |
+---------------------------------------------------------------------------------+
    

Authentication Workflow (OIDC/SSO vs. Local)

The CLI handles authentication by exchanging credentials for a JSON Web Token (JWT). The step-by-step authentication sequence differs between local admin credentials and Single Sign-On (SSO):

[User/Operator]              [ArgoCD CLI]             [ArgoCD Server]        [OIDC Provider]
      |                           |                          |                      |
      |--- 1. argocd login ------>|                          |                      |
      |    (with --sso flag)      |                          |                      |
      |                           |--- 2. Request SSO URI -->|                      |
      |                           |<-- 3. Return Auth URL ---|                      |
      |                                                      |                      |
      |<-- 4. Open browser & start local loopback listener --|                      |
      |                                                      |                      |
      |=== 5. Authenticate via Web Browser ========================================>|
      |<============================================================================|
      |                                                      |                      |
      |--- 6. Redirect auth code to local port ------------->|                      |
      |                           |                          |                      |
      |                           |--- 7. Exchange code ---->|                      |
      |                           |       for JWT Token      |                      |
      |                           |<-- 8. Return JWT Token --|                      |
      |                           |                          |                      |
      |<-- 9. Login Successful ---|                          |                      |
      |                           |                          |                      |
    

Once authenticated, the CLI writes the JWT token, the server address, and CA certificate configurations to the local configuration file located at ~/.config/argocd/config (on Unix-like systems) or %USERPROFILE%\.config\argocd\config (on Windows). Subsequent CLI executions read this file to populate the Authorization: Bearer <TOKEN> header on all outgoing gRPC/HTTP requests.

5. Multi-Platform Installation & Verification

To maintain consistency and security across your engineering organization, you must install the exact version of the ArgoCD CLI that matches your running ArgoCD server instance. Using mismatched major or minor versions can lead to API serialization errors or unsupported command-line flags.

Determining the Correct Version

Before downloading, query your running ArgoCD server to determine its version. You can check this via the Web UI (click the help icon) or by querying the deployment metadata directly using kubectl:

kubectl get deployment argocd-server -n argocd -o jsonpath='{.spec.template.spec.containers[0].image}' | cut -d':' -f2

Linux Installation (AMD64 & ARM64)

For Linux production environments, download the compiled binary directly from the official GitHub releases page. We will use environment variables to make the script reusable and dynamic.

# Define the desired ArgoCD version matching your server
export ARGOCD_VERSION="v2.10.4"

# Detect system architecture (amd64, arm64, etc.)
export ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')

# Download the compiled binary
curl -sSL -o argocd-linux-${ARCH} https://github.com/argoproj/argo-cd/releases/download/${ARGOCD_VERSION}/argocd-linux-${ARCH}

# Download the cryptographic checksum file for verification
curl -sSL -o argocd-linux-${ARCH}.sha256 https://github.com/argoproj/argo-cd/releases/download/${ARGOCD_VERSION}/argocd-linux-${ARCH}.sha256

# Verify the integrity of the downloaded binary
echo "$(cat argocd-linux-${ARCH}.sha256)  argocd-linux-${ARCH}" | sha256sum --check --status

if [ $? -eq 0 ]; then
    echo "Cryptographic verification passed. Installing..."
    sudo install -m 555 argocd-linux-${ARCH} /usr/local/bin/argocd
    rm argocd-linux-${ARCH} argocd-linux-${ARCH}.sha256
    echo "ArgoCD CLI installed successfully."
else
    echo "ERROR: Cryptographic signature mismatch! Do not install this binary."
    exit 1
fi

macOS Installation (Intel & Apple Silicon)

On macOS, you can install the CLI manually or use the Homebrew package manager. While Homebrew is convenient, be careful as it may default to the absolute latest version, which could mismatch your server version.

Option A: Manual Installation (Recommended for Version Matching)

# Set version and detect architecture (darwin-amd64 or darwin-arm64)
export ARGOCD_VERSION="v2.10.4"
export ARCH=$(uname -m | sed 's/x86_64/amd64/;s/arm64/arm64/')

# Download binary and SHA256 checksum
curl -sSL -o argocd-darwin-${ARCH} https://github.com/argoproj/argo-cd/releases/download/${ARGOCD_VERSION}/argocd-darwin-${ARCH}
curl -sSL -o argocd-darwin-${ARCH}.sha256 https://github.com/argoproj/argo-cd/releases/download/${ARGOCD_VERSION}/argocd-darwin-${ARCH}.sha256

# Verify checksum (macOS uses 'shasum' instead of 'sha256sum')
echo "$(cat argocd-darwin-${ARCH}.sha256)  argocd-darwin-${ARCH}" | shasum -a 256 --check --status

if [ $? -eq 0 ]; then
    chmod +x argocd-darwin-${ARCH}
    sudo mv argocd-darwin-${ARCH} /usr/local/bin/argocd
    rm argocd-darwin-${ARCH}.sha256
    echo "ArgoCD CLI successfully installed on macOS."
else
    echo "Verification failed!"
    exit 1
fi

Option B: Homebrew Installation

brew install argocd

Windows Installation (PowerShell)

For Windows systems, you can use package managers like Chocolatey or Scoop, or perform a manual installation using PowerShell.

Option A: PowerShell Manual Installation

$version = "v2.10.4"
$url = "https://github.com/argoproj/argo-cd/releases/download/$version/argocd-windows-amd64.exe"
$output = "$env:USERPROFILE\AppData\Local\Microsoft\WindowsApps\argocd.exe"

Invoke-WebRequest -Uri $url -OutFile $output
Write-Host "ArgoCD CLI installed to WindowsApps directory: $output"

Option B: Chocolatey Installation

choco install argocd-cli --version 2.10.4

Installation Verification

To verify that your installation was successful and to check the client-side version, execute the following command in a new terminal window:

argocd version --client

This command should return output similar to the following:

argocd: v2.10.4+4d2e37c
  BuildDate: 2024-02-21T15:47:01Z
  GitCommit: 4d2e37c17d23f8cb15d6f1c4e727937d5813f631
  GitTreeState: clean
  GoVersion: go1.21.7
  Compiler: gc
  Platform: linux/amd64

6. Shell Autocompletion Setup

The ArgoCD CLI features deep, context-aware command autocompletions. Setting this up significantly improves productivity by allowing tab-completion of command flags, application names, projects, and target clusters.

Bash Setup

Ensure you have the bash-completion package installed via your system package manager (e.g., apt-get install bash-completion or yum install bash-completion) before applying the configuration.

# Generate completion script and save it to the user's home directory
mkdir -p ~/.local/share/bash-completion/completions
argocd completion bash > ~/.local/share/bash-completion/completions/argocd

# Alternatively, load it system-wide (requires root permissions)
# argocd completion bash | sudo tee /etc/bash_completion.d/argocd > /dev/null

# Source your bash profile to apply immediately
source ~/.bashrc

Zsh Setup

For Zsh, the completion script must be placed in a directory included in your $fpath variable.

# Create a custom completion directory if it doesn't exist
mkdir -p ~/.zsh/completion

# Generate the Zsh completion script
argocd completion zsh > ~/.zsh/completion/_argocd

# Append the directory to your $fpath in ~/.zshrc
echo 'fpath=(~/.zsh/completion $fpath)' >> ~/.zshrc
echo 'autoload -Uz compinit && compinit' >> ~/.zshrc

# Reload your shell configuration
source ~/.zshrc

Fish Setup

Fish shell completions are straightforward and load automatically when placed in the standard configuration directory.

argocd completion fish > ~/.config/fish/completions/argocd.fish

7. Enterprise Authentication Mechanisms

ArgoCD supports multiple authentication backends. In an enterprise environment, local accounts should be strictly restricted, and all human operators should authenticate via Single Sign-On (SSO). Automated systems (CI/CD pipelines) must use non-interactive service accounts or programmatic API tokens.

Local Admin Authentication

When setting up a fresh ArgoCD instance, the initial password for the default admin user is auto-generated and stored in a Kubernetes secret named argocd-initial-admin-secret inside the installation namespace.

Step 1: Retrieve the Auto-Generated Password

kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d; echo

Step 2: Log In via the CLI

Use the retrieved password to log in. Replace argocd.example.com with your actual ArgoCD LoadBalancer or Ingress DNS endpoint.

argocd login argocd.example.com --username admin

You will be prompted to enter the password retrieved in Step 1. If your API server is using a self-signed certificate, see Section 8: Security Hardening to handle TLS validation correctly.

Step 3: Update the Admin Password

For security, change the default password immediately after your first login:

argocd account update-password

Once changed, delete the initial secret from your Kubernetes cluster to prevent exposure:

kubectl -n argocd delete secret argocd-initial-admin-secret

Single Sign-On (SSO) / OIDC Authentication

In production, ArgoCD is usually integrated with an identity provider (IdP) like Okta, Azure Active Directory, Ping Identity, or Keycloak via Dex or native OIDC. To log in using your enterprise SSO credentials:

argocd login argocd.example.com --sso

How the SSO CLI Flow Works:

1. The CLI starts a temporary, local lightweight loopback web server on your workstation (typically binding to localhost:8085 or another random open port).
2. The CLI automatically opens your default system web browser and navigates to the ArgoCD server's OIDC login endpoint.
3. You authenticate against your enterprise identity provider (including multi-factor authentication if required).
4. Upon successful authentication, the ArgoCD server redirects your browser back to the local loopback address (e.g., http://localhost:8085/auth/callback), passing the cryptographically signed JWT token.
5. The CLI extracts the token, writes it to your local ~/.config/argocd/config file, shuts down the local loopback server, and prints a success message to your terminal.

If you are working on a headless remote server (such as an SSH jump box) where a local browser cannot be opened, use the --sso-headless flag:

argocd login argocd.example.com --sso-headless

This command outputs a unique URL. Copy this URL, paste it into a web browser on your local workstation, complete the login, copy the generated authorization code from the browser window, and paste it back into your remote terminal prompt to complete the authentication.

Headless CI/CD & Programmatic Authentication

CI/CD agents (such as GitHub Runners, GitLab Runners, or Jenkins Nodes) cannot perform interactive browser logins. To authorize automated systems, use one of the following two production-grade patterns:

Pattern A: ArgoCD Local Project/Account Tokens (Recommended)

You can create a dedicated local service account within ArgoCD, assign it specific RBAC permissions, and generate a long-lived API token.

1. First, define the account in the ArgoCD ConfigMap (argocd-cm) inside Kubernetes:

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: argocd-cm
     namespace: argocd
   data:
     accounts.github-runner: apiKey

2. Define the permissions for this account in the RBAC ConfigMap (argocd-rbac-cm):

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: argocd-rbac-cm
     namespace: argocd
   data:
     policy.csv: |
       p, role:github-runner-role, applications, sync, */*, allow
       p, role:github-runner-role, applications, get, */*, allow
       g, github-runner, role:github-runner-role

3. Generate a token using the administrative CLI:

   argocd account generate-token --account github-runner --expires-in 30d

   This command returns an API token (e.g., eyJhbGciOiJSUzI1NiIs...). Store this token securely in your CI/CD secrets manager (e.g., GitHub Secrets, HashiCorp Vault).

4. In your CI/CD runner script, authenticate non-interactively using the token:

   export ARGOCD_AUTH_TOKEN="eyJhbGciOiJSUzI1NiIs..."
   argocd app sync my-app --server argocd.example.com --auth-token $ARGOCD_AUTH_TOKEN

Pattern B: Short-Lived Kubernetes JWT Token Projection

If your CI/CD runner is running inside the same Kubernetes cluster as ArgoCD, you can configure the runner's ServiceAccount to authenticate directly using its native Kubernetes token. This eliminates the need to manage long-lived secrets.

8. Security Hardening and TLS Management

Securing the transport layer between your local machine, CI/CD runners, and the ArgoCD API Server is critical. In enterprise environments, using self-signed certificates without verification or bypassing TLS checks using insecure flags is a major compliance violation.

The Dangers of the `--insecure` and `--insecure-skip-tls-verify` Flags

During initial setup, you might see tutorials recommending the --insecure flag:

# WARNING: Do not use this in production environments!
argocd login argocd.example.com --insecure

This flag disables TLS verification, exposing your session token and administrative commands to Man-in-the-Middle (MITM) attacks. Anyone on the local network path could intercept your gRPC traffic and steal your administrator JWT.

Configuring Custom CA Certificates

If your enterprise uses a private PKI (such as Active Directory Certificate Services, HashiCorp Vault PKI, or Let's Encrypt with a private root), you must configure the CLI to trust your custom Certificate Authority (CA).

Option A: System Trust Store Integration

The ArgoCD CLI automatically attempts to load the standard root certificates from your operating system's trust store. Ensure your enterprise root CA is installed locally:

• Ubuntu/Debian: Copy your CA cert to /usr/local/share/ca-certificates/enterprise-root.crt and run sudo update-ca-certificates.
• macOS: Import the certificate into the System Keychain using Keychain Access and set its trust settings to "Always Trust".
• Windows: Import the certificate into the "Trusted Root Certification Authorities" store using certlm.msc.

Option B: Direct CLI CA Injection

If you cannot modify the system trust store (e.g., inside a locked-down CI/CD container), pass the CA certificate directly to the CLI during login. The CLI will store this certificate in its local configuration directory and use it to verify all subsequent requests.

# Log in while specifying the path to your enterprise Root CA
argocd login argocd.example.com --server-crt ~/certs/enterprise-root-ca.crt

Securing Local Credentials

By default, the ArgoCD CLI stores session tokens in plain text inside ~/.config/argocd/config. To protect these credentials on shared development workstations or multi-user jump boxes, implement the following security controls:

1. Restrict directory permissions to the current user only:

   chmod 700 ~/.config/argocd
   chmod 600 ~/.config/argocd/config

2. Use environment variables instead of persistent configuration files in shared environments:

   # Set these variables in your shell environment to bypass writing to disk
   export ARGOCD_SERVER="argocd.example.com"
   export ARGOCD_AUTH_TOKEN="eyJhbGciOiJSUzI1NiIs..."

9. Command Reference & High-Performance Workflows

Now that your CLI is installed and secure, let's explore the core commands used for day-to-day GitOps operations, cluster administration, and resource synchronization.

Application Management

Applications are the primary custom resource managed by ArgoCD. The CLI provides commands to create, inspect, sync, and debug these applications.

Cluster Administration

ArgoCD can manage multiple target Kubernetes clusters from a single central management instance. To register an external cluster, use the CLI:

# 1. Ensure your local kubectl context is pointed to the target cluster
kubectl config use-context target-production-cluster

# 2. Add the cluster to ArgoCD
# This creates a ServiceAccount, ClusterRole, and ClusterRoleBinding on the target cluster,
# and stores the connection credentials as a secret in the ArgoCD namespace.
argocd cluster add target-production-cluster --name prod-us-east-1

To list all registered target clusters and verify their connection status:

argocd cluster list

Declarative Project Creation

ArgoCD Projects (AppProject) provide logical boundaries for applications, allowing you to restrict target namespaces, source repositories, and resource types.

# Create a project for the payment engineering team
argocd proj create payments-team \
    --description "Payment processing microservices" \
    -src "https://github.com/enterprise/payments-*.git" \
    -dest "https://kubernetes.default.svc,payments-prod"

# Allow only specific resource types within the project
argocd proj allow-namespace-resource payments-team apps Deployment
argocd proj allow-namespace-resource payments-team "" Service

10. Advanced CLI Scripting & CI/CD Automation

In production environments, the CLI is frequently executed inside automated CI/CD pipelines (such as GitHub Actions, GitLab CI, or Jenkins). Writing robust, non-interactive scripts requires careful handling of exit codes, structured output formats, and error handling.

Structured Output Processing with `jq`

By default, most ArgoCD CLI commands output human-readable text. For scripting, use the -o json or -o yaml flags to output structured data, which can then be parsed using utilities like jq.

Example: Get the Sync Status of an Application

# Query the application and parse its sync status
SYNC_STATUS=$(argocd app get payment-gateway -o json | jq -r '.status.sync.status')
echo "Current Application Sync Status: $SYNC_STATUS"

if [ "$SYNC_STATUS" != "Synced" ]; then
    echo "WARNING: Application is out of sync!"
fi

Example: Identify Failing Resources

This script parses the application's resource tree and prints only the resources that are in a Degraded state:

argocd app get payment-gateway -o json | jq -r '
  .status.resources[] 
  | select(.health.status == "Degraded") 
  | "Degraded Resource: \(.kind) \(.name) - Reason: \(.health.message)"
'

Production-Grade CI/CD Sync Script

Below is a production-grade Bash script designed for deployment pipelines. It triggers a synchronization, waits for the application to reach a healthy state, handles timeouts, and returns appropriate exit codes to fail the pipeline if the deployment fails.

#!/usr/bin/env bash

# Stop execution on any error
set -eo pipefail

# Required variables
APP_NAME="${1:?Error: Application name must be provided as the first argument}"
ARGOCD_SERVER="${ARGOCD_SERVER:-argocd.example.com}"
TIMEOUT_SECONDS=600

echo "=== Starting deployment pipeline for application: ${APP_NAME} ==="

# Step 1: Check server connectivity
echo "Verifying connectivity to ArgoCD API Server at ${ARGOCD_SERVER}..."
argocd version --server "${ARGOCD_SERVER}" --grpc-web > /dev/null

# Step 2: Show structural diff before syncing
echo "Calculating structural diff between Git and Live Cluster..."
argocd app diff "${APP_NAME}" --server "${ARGOCD_SERVER}" --grpc-web || true

# Step 3: Trigger synchronization
echo "Triggering application sync..."
argocd app sync "${APP_NAME}" \
    --server "${ARGOCD_SERVER}" \
    --grpc-web \
    --async

# Step 4: Wait for application to reach 'Synced' and 'Healthy' states
echo "Waiting for application to reach Healthy state (Timeout: ${TIMEOUT_SECONDS}s)..."
if argocd app wait "${APP_NAME}" \
    --server "${ARGOCD_SERVER}" \
    --grpc-web \
    --sync \
    --health \
    --timeout "${TIMEOUT_SECONDS}"; then
    
    echo "=== SUCCESS: Application ${APP_NAME} is Synced and Healthy! ==="
    exit 0
else
    echo "=== ERROR: Application ${APP_NAME} failed to reach Healthy state within timeout. ==="
    
    # Print diagnostic information
    echo "Retrieving degraded resources..."
    argocd app get "${APP_NAME}" --server "${ARGOCD_SERVER}" --grpc-web -o json | jq -r '
      .status.resources[] | select(.health.status != "Healthy" and .health.status != null) | "Resource: \(.kind)/\(.name) Status: \(.health.status) Message: \(.health.message)"
    '
    exit 1
fi

GitHub Actions Integration

To run the ArgoCD CLI within a GitHub Actions workflow, use the official runner environment and inject your credentials as secrets:

name: GitOps Sync Pipeline

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Install ArgoCD CLI
        run: |
          export ARGOCD_VERSION="v2.10.4"
          curl -sSL -o /usr/local/bin/argocd https://github.com/argoproj/argo-cd/releases/download/${ARGOCD_VERSION}/argocd-linux-amd64
          chmod +x /usr/local/bin/argocd

      - name: Sync Application
        env:
          ARGOCD_SERVER: ${{ secrets.ARGOCD_SERVER }}
          ARGOCD_AUTH_TOKEN: ${{ secrets.ARGOCD_AUTH_TOKEN }}
        run: |
          argocd app sync payment-gateway-prod \
            --server "$ARGOCD_SERVER" \
            --auth-token "$ARGOCD_AUTH_TOKEN" \
            --grpc-web \
            --retry-limit 3

11. Troubleshooting & Debugging Common Errors

When operating the ArgoCD CLI in enterprise networks, you may encounter connectivity, authentication, or protocol negotiation errors. Below are common issues and steps to resolve them.

Error 1: "transport: Error while dialing dial tcp: i/o timeout"

• Symptom: The CLI hangs for several seconds and then fails with a connection timeout.
• Root Cause: A network firewall, security group, or routing table is blocking traffic on port 443 (or port 80) between your local machine and the ArgoCD API Server.
• Resolution:
  1. Verify DNS resolution: nslookup argocd.example.com.
  2. Test low-level TCP connectivity: nc -zv argocd.example.com 443.
  3. Check if your corporate VPN is active and has a route to the target cluster's Ingress controller.

Error 2: "rpc error: code = Unauthenticated desc = Invalid session token"

• Symptom: Any execution of an ArgoCD command returns an unauthenticated error.
• Root Cause: Your local JWT token has expired or has been revoked by the ArgoCD server (the default token lifespan is 24 hours unless configured otherwise).
• Resolution:
  1. Force a fresh interactive login: argocd login argocd.example.com --sso.
  2. If using a headless token in CI/CD, verify that the token has not expired and that the account is still active in the argocd-cm ConfigMap.

Error 3: "rpc error: code = Internal desc = transport is closing" (HTTP/2 Proxy Issues)

• Symptom: The CLI successfully authenticates but immediately crashes or closes the connection when running commands like argocd app list.
• Root Cause: An intermediate proxy, load balancer (e.g., AWS ALB without HTTP/2 enabled), or Cloudflare-like CDN is stripping HTTP/2 gRPC headers.
• Resolution: Force the CLI to fallback to the gRPC-web protocol, which encapsulates gRPC frames inside standard HTTP/1.1 requests: