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

> Master the Argo CD CLI to manage GitOps workflows authenticate with the API server and debug locally. This comprehensive guide empowers developers to leverage the command-line interface efficiently.

- Repository: [Argo Project/argo-cd](https://github.com/argoproj/argo-cd)
- Tags: how-to-guide
- Published: 2026-07-15

---

**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`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/login.go)** – Implements `argocd login` with support for username/password, token-based, and SSO authentication flows
- **[`app.go`](https://github.com/argoproj/argo-cd/blob/main/app.go)** – Contains the core logic for `argocd app create`, `sync`, `delete`, and `diff` operations
- **[`repo.go`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/login_test.go), [`app_test.go`](https://github.com/argoproj/argo-cd/blob/main/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:

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

```

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

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash

# 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`](https://github.com/argoproj/argo-cd/blob/main/cmd/argocd/commands/login.go) or the generated documentation at [`docs/user-guide/commands/argocd_login.md`](https://github.com/argoproj/argo-cd/blob/main/docs/user-guide/commands/argocd_login.md).

### Application Management

Create and synchronize applications declaratively:

```bash

# 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:

```bash

# 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:

```bash
argocd --core app list
argocd --core app sync guestbook

```

This mode leverages the client implementation in [`cmd/util/common.go`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/cmd/argocd/commands/root.go)** – Global flag definitions and command registration
- **[`cmd/argocd/commands/login.go`](https://github.com/argoproj/argo-cd/blob/main/cmd/argocd/commands/login.go)** – Authentication flow implementation
- **[`cmd/argocd/commands/app.go`](https://github.com/argoproj/argo-cd/blob/main/cmd/argocd/commands/app.go)** – Application lifecycle commands
- **[`cmd/argocd/commands/repo.go`](https://github.com/argoproj/argo-cd/blob/main/cmd/argocd/commands/repo.go)** – Repository CRUD operations
- **[`cmd/util/common.go`](https://github.com/argoproj/argo-cd/blob/main/cmd/util/common.go)** – Shared gRPC client construction and TLS handling
- **[`cmd/util/app.go`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/root.go) using `AddCommand()`. Include a corresponding [`mycommand_test.go`](https://github.com/argoproj/argo-cd/blob/main/mycommand_test.go) file for unit tests, and run `make docs` to regenerate the CLI documentation. Refer to existing commands like [`login.go`](https://github.com/argoproj/argo-cd/blob/main/login.go) or [`app.go`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/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.