How to Use the Argo CD CLI: A Complete Developer and User Guide

The Argo CD CLI provides a comprehensive command-line interface built on the Cobra framework that enables developers to manage GitOps workflows, authenticate with the API server, and debug the controller locally using both standard gRPC and direct Kubernetes communication modes.

The argocd command-line tool is the primary interface for interacting with Argo CD installations in the argoproj/argo-cd repository. Whether you are deploying applications in production or extending the CLI for custom workflows, understanding its architecture and command structure is essential for effective GitOps management.

Understanding the Argo CD CLI Architecture

The CLI follows a modular design pattern with clear separation between command definitions, client logic, and authentication handling.

Root Command and Global Flags

The entry point for all CLI operations resides in cmd/argocd/commands/root.go. This file initializes the Cobra command tree and defines global flags inherited by all sub-commands, including --server, --core, --grpc-web, and TLS configuration options.

When you invoke any argocd command, the root command parses these shared flags first, establishing the connection context before delegating to specific sub-command handlers.

Sub-commands and Command Hierarchy

Each major operation lives in its own dedicated file within cmd/argocd/commands/:

• login.go – Implements argocd login with support for username/password, token-based, and SSO authentication flows
• app.go – Contains the core logic for argocd app create, sync, delete, and diff operations
• repo.go – Handles repository management commands including argocd repo add and list

These files register their commands with the root command using Cobra's AddCommand pattern, creating the hierarchical structure that supports invocations like argocd app sync or argocd repo list.

Client Library and Connection Modes

The client implementation in cmd/util/common.go encapsulates two distinct communication modes:

1. API Server Mode (default) – Connects to the Argo CD API server via gRPC, handling TLS termination, authentication tokens, and optional Redis compression
2. Core Mode – Activated with the --core flag, this mode bypasses the API server entirely and communicates directly with the Kubernetes API and the argocd-application-controller deployment

The core mode is particularly valuable for development and unit testing when the API server is unavailable or when you need to debug controller behavior directly.

Testing Infrastructure

Every command file includes a corresponding *_test.go file (e.g., login_test.go, app_test.go) that utilizes a fake server or procfile-based test harness. This ensures backward compatibility and allows you to validate changes without requiring a full cluster deployment.

Setting Up Your Development Environment

To build and run the CLI from source in the argoproj/argo-cd repository, follow this workflow:

1. Clone the repository and navigate to the source directory:

git clone https://github.com/YOUR-USERNAME/argo-cd.git
cd argo-cd

2. Install the required toolchain using the provided Makefile targets:

make install-go-tools-local
make install-codegen-tools-local

These commands install golangci-lint, mockgen, controller-gen, and other dependencies necessary for code generation and linting.

3. Deploy Argo CD to a local cluster (Kind, Minikube, or K3d) for end-to-end testing:

kubectl create namespace argocd
kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/argoproj/argo-cd/master/manifests/install.yaml
kubectl config set-context --current --namespace=argocd

4. Run the CLI locally against the development environment:

go run ./cmd/argocd/ --core app list

The --core flag enables direct communication with the controller, bypassing authentication requirements and API server latency.

5. Iterate with live reload using Tilt for rapid development:

tilt up

Tilt monitors Go source files, rebuilds binaries automatically, and streams logs to a web interface, providing immediate feedback on code changes.

6. Validate changes before submitting:

make build
make test
make lint

Essential Argo CD CLI Commands with Examples

The following examples demonstrate practical usage patterns for common GitOps operations.

Authentication and Login

Connect to an Argo CD server using various authentication methods:

# Username and password authentication

argocd login cd.argoproj.io --username alice --password secret

# SSO-based login (opens browser window)

argocd login cd.argoproj.io --sso

# Direct Kubernetes access without API server

argocd login cd.argoproj.io --core

Reference the complete option set in cmd/argocd/commands/login.go or the generated documentation at docs/user-guide/commands/argocd_login.md.

Application Management

Create and synchronize applications declaratively:

# Create a new application

argocd app create guestbook \
  --repo https://github.com/argoproj/guestbook \
  --path ./deploy \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace default

# Sync with pruning enabled

argocd app sync guestbook --prune

# Compare local state against live cluster

argocd app diff guestbook --revision master

# List all applications in YAML format

argocd app list --output yaml

Repository Operations

Manage Helm and Git repositories:

# Add a Helm chart repository

argocd repo add https://charts.helm.sh/stable --type helm

# List configured repositories

argocd repo list

Core Mode for Local Development

When developing locally without an exposed API server, use core mode to interact directly with the controller:

argocd --core app list
argocd --core app sync guestbook

This mode leverages the client implementation in cmd/util/common.go to communicate through the Kubernetes API rather than gRPC.

Key Source Files for CLI Extension

When modifying or extending the CLI, focus on these critical files:

• cmd/argocd/commands/root.go – Global flag definitions and command registration
• cmd/argocd/commands/login.go – Authentication flow implementation
• cmd/argocd/commands/app.go – Application lifecycle commands
• cmd/argocd/commands/repo.go – Repository CRUD operations
• cmd/util/common.go – Shared gRPC client construction and TLS handling
• cmd/util/app.go – Application resource fetching helpers
• docs/user-guide/commands/ – Auto-generated markdown documentation (regenerate with make docs)

After modifying any command file, add corresponding tests in *_test.go files, regenerate documentation, and run the full validation suite (make lint && make test).

Summary

• The Argo CD CLI is built on Cobra with a hierarchical command structure defined in cmd/argocd/commands/root.go
• Two connection modes exist: API server mode (gRPC) and core mode (direct Kubernetes API), controlled by the --core flag
• All commands share common client logic in cmd/util/common.go that handles TLS, authentication, and request construction
• Development requires running make install-go-tools-local and make install-codegen-tools-local to set up the toolchain
• Use go run ./cmd/argocd/ --core <command> for rapid local testing without deploying the API server
• Every command has corresponding test files (*_test.go) and documentation generated in docs/user-guide/commands/

Frequently Asked Questions

What is the difference between --core mode and standard API server mode?

The --core flag instructs the CLI to bypass the Argo CD API server and communicate directly with the Kubernetes API and the argocd-application-controller deployment. This mode is essential for local development and debugging when the API server is not exposed or when testing controller logic directly. Standard mode connects via gRPC to the Argo CD API server, requiring authentication tokens or credentials.

How do I add a new sub-command to the Argo CD CLI?

Create a new file in cmd/argocd/commands/ (e.g., mycommand.go) that defines a Cobra command struct, implements the Run/RunE function with your logic, and registers it with the root command in root.go using AddCommand(). Include a corresponding mycommand_test.go file for unit tests, and run make docs to regenerate the CLI documentation. Refer to existing commands like login.go or app.go for implementation patterns.

Where is the client connection logic centralized in the source code?

Shared client connection logic, including gRPC channel construction, TLS configuration, and authentication token handling, resides in cmd/util/common.go. This file provides the NewConnection function and related helpers that most commands use to establish communication with the API server, ensuring consistent behavior for flags like --server, --insecure, and --plaintext across all operations.

How do I run the CLI locally without installing it system-wide?

Use go run ./cmd/argocd/ <command> from the repository root to execute the CLI directly from source. For development workflows that require interaction with the controller but not the full API server stack, append the --core flag (e.g., go run ./cmd/argocd/ --core app list) to communicate directly with Kubernetes resources.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}