How to Use the Argo CD CLI for Development: A Complete Guide

The Argo CD CLI enables developers to interact with Argo CD installations, automate GitOps workflows, and debug the controller locally using commands defined in the argoproj/argo-cd repository.

The Argo CD command-line interface (CLI) serves as the primary tool for developers working with the argoproj/argo-cd project, whether managing applications in production or extending the tool's functionality. Understanding how to use the Argo CD CLI for development requires familiarity with its Cobra-based architecture, local build processes, and dual-mode operation that supports both API server and direct Kubernetes connections.

Argo CD CLI Architecture

The CLI follows a modular architecture built on the Cobra framework, organizing commands hierarchically and sharing common client logic across all operations.

Root Command Structure

In cmd/argocd/commands/root.go, the root command configures global flags and registers all sub-commands. This file initializes the top-level argocd command and parses shared flags such as --core, --grpc-web, and authentication options that propagate to child commands.

Sub-command Organization

Each CLI verb lives in its own file within cmd/argocd/commands/:

• login.go implements authentication flows
• app.go handles application lifecycle operations
• repo.go manages repository configurations

These files register their specific logic to the root command tree using Cobra's command pattern.

Client Library and Connection Modes

The cmd/util/common.go file contains the shared client code that handles gRPC connections, TLS configuration, and token management. The CLI supports two connection modes:

• API Server Mode (default): Connects to the Argo CD API server via gRPC using --server flags
• Core Mode (--core): Bypasses the API server to communicate directly with the argocd-application-controller deployment via the Kubernetes API

Setting Up the Development Environment

Before modifying the CLI, configure your local environment with the necessary toolchains.

Prerequisites and Repository Setup

Fork and clone the repository:

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

Install Go, Docker or Podman, and a local Kubernetes cluster (Kind, Minikube, or K3d) as specified in developer-guide/development-environment.md.

Bootstrapping Development Tools

Install the required toolchain using Make targets:

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

These commands pull in golangci-lint, mockgen, controller-gen, and other utilities required for code generation and linting.

Running the CLI Locally

Developers can test changes immediately without deploying to a cluster using the local build workflow.

Core Mode Development

The --core flag enables direct communication with the controller, bypassing the API server. This mode is ideal for unit testing and debugging:

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

When running with --core, the CLI reads from the current Kubernetes context and interacts directly with the argocd-application-controller deployment.

Building the Binary

Compile the CLI binary for testing:

make build

After building, execute the binary directly:

./dist/argocd --core app list

Essential Development Commands

Test your changes against real-world scenarios using these common command patterns.

Authentication Commands

Test login functionality in cmd/argocd/commands/login.go:

# Username/password authentication

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

# SSO authentication (opens browser)

argocd login cd.argoproj.io --sso

# Core mode (no API server required)

argocd login cd.argoproj.io --core

Application Operations

Verify application management logic in cmd/argocd/commands/app.go:

# Create an 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

argocd app sync guestbook --prune

# Diff local changes

argocd app diff guestbook --revision master

# List with YAML output for debugging

argocd app list --output yaml

Repository Management

Test repository commands defined in cmd/argocd/commands/repo.go:

# Add Helm repository

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

# List configured repositories

argocd repo list

Testing and Code Quality

Maintain code standards using the project's built-in verification tools.

Run unit tests for specific commands:

make test

Execute linting to ensure style consistency:

make lint

Test files follow the *_test.go pattern (e.g., cmd/argocd/commands/login_test.go) and use fake servers or procfile-based harnesses to mock API responses.

Key Files for CLI Extension

When adding new functionality or debugging existing commands, focus on these critical paths:

• cmd/argocd/commands/root.go - Global flags and command registration
• cmd/argocd/commands/login.go - Authentication implementations
• cmd/argocd/commands/app.go - Application lifecycle logic
• cmd/argocd/commands/repo.go - Repository management
• cmd/util/common.go - Shared gRPC client and connection handling
• cmd/util/app.go - Application resource helpers
• docs/user-guide/commands/ - Auto-generated CLI documentation

After modifying commands, regenerate documentation:

make docs

Summary

• The Argo CD CLI uses Cobra for command hierarchy, with root configuration in cmd/argocd/commands/root.go
• Core mode (--core) enables direct Kubernetes API communication for local development without requiring a running API server
• Build and test locally using make build, make test, and make lint targets
• Command implementations reside in cmd/argocd/commands/ with shared utilities in cmd/util/
• Unit tests follow the *_test.go naming convention and mock server interactions
• Auto-generated documentation lives in docs/user-guide/commands/ and updates via make docs

Frequently Asked Questions

How do I run the Argo CD CLI without installing it in a cluster?

Use go run ./cmd/argocd/ with the --core flag to execute commands directly against your local Kubernetes context. This bypasses the API server and communicates straight with the controller, eliminating the need for a full Argo CD installation during development.

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

API server mode (default) connects via gRPC to the Argo CD API server using authentication tokens or SSO, as implemented in cmd/util/common.go. Core mode (--core) uses the Kubernetes API directly to interact with the argocd-application-controller deployment, useful for debugging and unit testing when the API server is unavailable.

Where should I add a new CLI sub-command?

Create a new file in cmd/argocd/commands/ following the pattern of existing commands like app.go or repo.go. Register the new command in cmd/argocd/commands/root.go using Cobra's command addition methods. Include corresponding tests in a *_test.go file to ensure backward compatibility.

How do I test CLI authentication changes locally?

Modifications to authentication logic in cmd/argocd/commands/login.go can be tested using the local build: go run ./cmd/argocd/ login <server> --core. For full authentication flow testing including SSO, deploy Argo CD to a local Kind or Minikube cluster and test against that endpoint using argocd login <server> --sso.

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