# How to Use the Argo CD CLI for Development: A Complete Guide > Master the Argo CD CLI for development. Automate GitOps workflows, interact with installations, and debug locally with our comprehensive guide. - Repository: [Argo Project/argo-cd](https://github.com/argoproj/argo-cd) - Tags: how-to-guide - Published: 2026-07-14 --- **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`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/login.go) implements authentication flows - [`app.go`](https://github.com/argoproj/argo-cd/blob/main/app.go) handles application lifecycle operations - [`repo.go`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/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: ```bash 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`](https://github.com/argoproj/argo-cd/blob/main/developer-guide/development-environment.md). ### Bootstrapping Development Tools Install the required toolchain using Make targets: ```bash 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: ```bash 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: ```bash make build ``` After building, execute the binary directly: ```bash ./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`](https://github.com/argoproj/argo-cd/blob/main/cmd/argocd/commands/login.go): ```bash # 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`](https://github.com/argoproj/argo-cd/blob/main/cmd/argocd/commands/app.go): ```bash # 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`](https://github.com/argoproj/argo-cd/blob/main/cmd/argocd/commands/repo.go): ```bash # 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: ```bash make test ``` Execute linting to ensure style consistency: ```bash make lint ``` Test files follow the `*_test.go` pattern (e.g., [`cmd/argocd/commands/login_test.go`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/cmd/argocd/commands/root.go) - Global flags and command registration - [`cmd/argocd/commands/login.go`](https://github.com/argoproj/argo-cd/blob/main/cmd/argocd/commands/login.go) - Authentication implementations - [`cmd/argocd/commands/app.go`](https://github.com/argoproj/argo-cd/blob/main/cmd/argocd/commands/app.go) - Application lifecycle logic - [`cmd/argocd/commands/repo.go`](https://github.com/argoproj/argo-cd/blob/main/cmd/argocd/commands/repo.go) - Repository management - [`cmd/util/common.go`](https://github.com/argoproj/argo-cd/blob/main/cmd/util/common.go) - Shared gRPC client and connection handling - [`cmd/util/app.go`](https://github.com/argoproj/argo-cd/blob/main/cmd/util/app.go) - Application resource helpers - `docs/user-guide/commands/` - Auto-generated CLI documentation After modifying commands, regenerate documentation: ```bash make docs ``` ## Summary - The Argo CD CLI uses **Cobra** for command hierarchy, with root configuration in [`cmd/argocd/commands/root.go`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/app.go) or [`repo.go`](https://github.com/argoproj/argo-cd/blob/main/repo.go). Register the new command in [`cmd/argocd/commands/root.go`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/cmd/argocd/commands/login.go) can be tested using the local build: `go run ./cmd/argocd/ login --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 --sso`.