Argo CD is a GitOps continuous delivery tool for Kubernetes. It monitors your Git repositories and then automatically applies changes to the resources in your Kubernetes cluster. This ensures your cluster’s state is continually synced with the manifests in your repository, eliminating manual deployment tasks.
Argo CD is popular because of its powerful features and ease of use. You can manage Argo apps using Kubernetes custom resources, an API, a web interface, and a CLI, providing multiple options for interacting with your workloads.
In this cheat sheet, we examine Argo’s CLI. It enables you to control your Argo instance from your terminal, ensuring streamlined integration with development workflows. We’ll share the most useful Argo CLI commands and discuss some best practices to help you avoid errors and work more effectively.
Argo CD CLI is the command-line interface for interacting with Argo CD, a declarative GitOps continuous delivery tool for Kubernetes. It allows users to manage applications, synchronize Git repositories with live cluster state, and perform operations like login, app creation, sync, and status checks directly from the terminal. You can also administer Argo and initiate data exports and imports.
You can download the CLI from Argo’s GitHub releases page.
To install the Argo CD CLI, follow the method appropriate for your OS:
- macOS (using Homebrew):
brew install argocd- Linux (manual install):
VERSION=$(curl -s https://api.github.com/repos/argoproj/argo-cd/releases/latest | grep tag_name | cut -d '"' -f 4)
curl -sSL -o argocd "https://github.com/argoproj/argo-cd/releases/download/${VERSION}/argocd-linux-amd64"
chmod +x argocd
sudo mv argocd /usr/local/bin/- Windows (PowerShell):
Invoke-WebRequest -Uri https://github.com/argoproj/argo-cd/releases/latest/download/argocd-windows-amd64.exe -OutFile argocd.exeAdd argocd.exe to your system’s PATH manually or via System Settings.
Confirm the CLI is installed and shows client/server versions:
argocd versionOnce you’re set up, the argocd command should be available in your shell:
$ argocd
argocd controls a Argo CD serverInitially, the CLI uses your active Kubeconfig context to connect to your Kubernetes cluster. After you’ve logged into the CLI, it’ll then connect directly to the Argo CD API server in your cluster.
Now let’s explore some of the CLI’s top features:
argocd admin initial-passwordargocd loginargocd account can-iargocd account update-passwordargocd clusterargocd contextargocd app createargocd app getargocd app syncargocd app historyargocd app diffargocd app rollbackargocd app logsargocd projargocd repoargocd completionargocd configureargocd admin dashboard
argocd admin initial-password command fetches the random password assigned to Argo’s admin user during installation. You must use the -n flag to specify the Kubernetes namespace that you’ve installed Argo within:
$ argocd admin initial-password -n argocd
RZUcbWd6ebUjjIYV
This password must be only used for first time login. We strongly recommend you update the password using `argocd account update-password`.Use argocd login command to connect the CLI to your Argo CD instance, specifying the server hostname to use. If you’re using Argo for the first time, you should connect as admin and use the initial password displayed by the command above.
Once you’ve added custom user accounts, you can use the argo login command to authenticate as them instead.
$ argocd login localhost:8080You’ll be prompted to supply your username and password interactively.
Set the username and password with flags
The --username and --password flags allow you to supply your credentials directly on the command line. This makes it easier to use the CLI with CI/CD scripts and other automated processes.
$ argocd login localhost:8080 --username=<username> --password=<password>Use SSO authentication
The --sso flag enables you to sign in using SSO when an identity provider has been configured for your Argo CD instance:
$ argocd login localhost:8080 --ssoIf you are unsure whether you have permission to perform an Argo action you can check before you try with the argocd account can-i command. It lets you specify a verb and noun, such as create repositories or sync applications, then see if you’ve got the permission.
# Can I create repositories?
$ argocd account can-i create repositories '*'
yes
# Can I sync the applications in the 'demo' project?
$ argocd account can-i sync applications demo
noYou can change your account’s password using argocd account update-password. It’s a great way to quickly secure the default admin user, after you’ve logged in with the randomly generated initial password. You’ll be prompted to enter your current and new passwords interactively.
$ argocd account update-password
*** Enter password of currently logged in user (admin):
*** Enter new password for user admin:
*** Confirm new password for user admin:
Password updated
Context 'localhost:8080' updatedSet the current and new password with flags
You can opt out of interactive inputs by setting the --current-password and --new-password flags.
$ argocd account update-password --current-password <old> --new-password <new>Change another user’s password
The --account flag allows you to change another user’s password.
$ argocd account update-password --account <other-username>argocd admin dashboard command starts an instance of Argo CD’s web UI locally, without exposing it in your cluster. Port 8080 is used by default.
$ argocd admin dashboard
Argo CD UI is available at http://localhost:8080Visit http://localhost:8080 in your browser to login to the UI.
Listen on a different port
The --port flag lets you serve the UI on a different port instead of the default 8080:
$ argocd admin dashboard --port 8180
Argo CD UI is available at http://localhost:8180Commands in the argocd cluster group manage the Kubernetes clusters connected to your Argo CD instance. These are the clusters to which you can deploy apps, not necessarily the cluster that Argo is running within.
List all clusters
argocd cluster list lists all the clusters known to Argo CD:
$ argocd cluster list
SERVER NAME VERSION STATUS MESSAGE PROJECT
https://kubernetes.default.svc in-cluster Unknown Cluster has no applications and is not being monitored. Get a cluster’s details
argocd cluster get <name> retrieves the detailed YAML configuration for a single cluster:
$ argocd cluster get in-cluster
config:
tlsClientConfig:
insecure: false
connectionState:
attemptedAt: "2025-01-10T16:35:57Z"
message: Cluster has no applications and is not being monitored.
status: UnknownAdd a new cluster
Clusters are added using argocd cluster add <kube-context-name>. You must specify the name of an existing context in your Kubeconfig file. The CLI will import the cluster credentials that the context uses.
# demo-context exists as a context in the active Kubeconfig file
$ argocd cluster add demo-contextRemove a cluster
argocd cluster rm <cluster-name> removes a previously added cluster. You’ll be prompted to confirm the removal first, unless you also add the -y (--yes) flag.
$ argocd cluster rm demo-clusterThe Argo CD CLI lets you authenticate to multiple Argo instances using a single config file. A new configuration context is created each time you run argocd login. Switching between contexts allows you to work efficiently with all your Argo environments.
View available contexts
To view all available context, run the argocd context command without any arguments:
$ argocd context
CURRENT NAME SERVER
* localhost:8080 localhost:8080Switch between contexts
Specify the name of the context to switch to:
$ argocd context localhost:8080Delete a context
To specify the context’s name and set the --delete flag:
$ argocd context localhost:8080 --deleteThe argocd app create command registers new Argo applications. You must specify your app’s Git repository, the path that contains your Kubernetes manifests, and which Kubernetes cluster and namespace the app should be deployed to.
You can also deploy Helm charts and set Kustomizations.
Create an app from a Git repository
The following example creates an app called guestbook that deploys the manifests from the guestbook directory of the specified Git repository. They’ll be added to the demo-guestbook namespace in the same Kubernetes cluster that’s hosting Argo.
$ argocd app create guestbook \
--repo https://github.com/argoproj/argocd-example-apps.git \
--path guestbook \
--dest-namespace demo-guestbook \
--dest-server https://kubernetes.default.svc \
--directory-recurse
application 'guestbook' createdCreate an app from a Helm repository
This example provides an app that uses a Helm chart stored in a Helm repository. You must specify the Helm repository, chart, and version. The --helm-set flag allows you to customize chart values.
$ argocd app create ingress-nginx-helm \
--repo https://kubernetes.github.io/ingress-nginx \
--helm-chart ingress-nginx \
--revision 4.12.0 \
--dest-namespace ingress-nginx \
--dest-server https://kubernetes.default.svc \
--helm-set controller.metrics.enabled=true
application 'ingress-nginx-helm' createdYou can run argocd app list to list all the apps you’ve deployed to check their health and sync statuses quickly:
$ argocd app list
NAME CLUSTER NAMESPACE PROJECT STATUS HEALTH SYNCPOLICY CONDITIONS REPO PATH TARGET
argocd/guestbook https://kubernetes.default.svc demo-guestbook default OutOfSync Missing <none> <none> https://github.com/argoproj/argocd-example-apps.git guestbook
argocd/ingress-nginx-helm https://kubernetes.default.svc ingress-nginx default OutOfSync Missing <none> <none> https://kubernetes.github.io/ingress-nginx 4.12.0You can also use the argocd app get command to fetch detailed information about a specific app and its resources:
$ argocd app get guestbook
Name: argocd/guestbook
Project: default
Server: https://kubernetes.default.svc
Namespace: demo-guestbook
URL: https://localhost:8080/applications/guestbook
Repo: https://github.com/argoproj/argocd-example-apps.git
Target:
Path: guestbook
SyncWindow: Sync Allowed
Sync Policy: <none>
Sync Status: OutOfSync from (d7927a2)
Health Status: Missing
GROUP KIND NAMESPACE NAME STATUS HEALTH HOOK MESSAGE
Service demo-guestbook guestbook-ui OutOfSync Missing
apps Deployment demo-guestbook guestbook-ui OutOfSync Missing Syncing is one of Argo’s key operations. Syncing an app compares the resources in your cluster to the files in the app’s Git or Helm repository. Argo then reconciles the changes to apply the correct state to your cluster.
Sync an app
You can sync an app by passing its name to the argocd app sync command.
$ argocd app sync guestbookThe sync result will be displayed in your terminal.
Sync multiple apps
It’s possible to sync multiple apps in one operation:
$ argocd app sync app1 app2Perform a dry run
The --dry-run flag shows what the sync would do without actually applying any changes to your cluster.
$ argocd app sync guestbook --dry-runPreview changes before syncing
The --preview-changes flag displays the differences between your cluster’s state and your repository’s state, then prompts you to continue before the sync proceeds:
$ argocd app sync guestbook --preview-changesPrune old objects
Argo CD doesn’t automatically delete resources that already exist in your cluster but have been removed from your repository. This helps avoid accidental data loss. The --prune flag lets you opt-in to clean up removed resources during a sync.
$ argocd app sync guestbook --pruneThe argocd app diff command allows you to compare the target and live states for a particular app. The diff is displayed visually so you can identify new, changed, and removed resources. This lets you easily check whether the app needs to be resynced.
$ argocd app diff guestbookargocd app history command provides a basic app deployment history. It accepts a single argument, such as the name of the app to query. The output is a table that displays the timestamp, and Git commit from each of the app’s sync events.
$ argocd app history guestbook
ID DATE REVISION
0 2025-01-10 18:00:32 +0000 GMT (d7927a2)
1 2025-01-10 18:02:03 +0000 GMT (d7927a2)Because Argo CD tracks your app’s deployment history, you can easily roll back to a previous release using argocd app rollback command. When run without an argument, the app will be reverted to the previous version before the current sync.
$ argocd app rollback guestbookThe rollback result will be displayed in your terminal.
Rollback to an older version
You can roll back to a different version by passing an ID from argocd app history as the rollback command’s second argument:
# Rollback to the revision with history ID #1
$ argocd app rollback guestbook 1Prune objects during rollback
Like a regular sync, Argo CD doesn’t automatically delete cluster objects that become redundant after a rollback. Use the --prune flag to clean these objects so your cluster’s state exactly matches your repository’s configuration.
$ argocd app rollback guestbook --pruneYou can use argocd app logs command to access the logs written by your app’s Pods easily. By default, it combines the output from all the Pods in the specified app:
$ argocd app logs guestbook
[Fri Jan 10 18:00:49.663125 2025] [mpm_prefork:notice] [pid 1] AH00163: Apache/2.4.10 (Debian) PHP/5.6.31 configured -- resuming normal operationsLivestream new logs
The --follow flag of argocd app logs command continually streams new logs into your terminal, enabling real-time monitoring:
$ argocd app logs guestbook --followGet logs from a specific container
You can retrieve the logs from a specific container among your app’s Pods with --container:
$ argocd app logs guestbook --container guestbook-uiGet logs from a specific resource
You can also use the --kind and --name flags to access the logs from a specific resource in your app, such as Pods in a certain Deployment:
$ argocd app logs guestbook --kind Deployment --name guestbook-uiGet logs created in a specific timeframe
The --since-seconds and --until-time flags enable you to constrain the log output to messages written in a given timeframe. Note that --since-seconds takes a relative number of seconds before the current time, such as 60, whereas --until-time requires a precise timestamp in 0000-00-00T00:00:00Z format.
# Get messages <15 minutes old, but older than 14:00 on Jan 10th
$ argocd app logs guestbook --since-seconds 900 --until-time "2025-01-10T14:00:00Z"Filter log messages
If you know what you’re looking for in the log, use the --filter flag to match messages that contain a search string:
$ argocd app logs guestbook --filter errorArgo CD projects group multiple applications together, enabling safe cross-team access management. Each project can contain its own policies to control what can be deployed and which clusters and namespaces can be used.
Projects are managed via the argocd proj CLI command group. Here are some of its key features.
Create a project
Add a new project using argocd proj create <project-name>. You can configure many project settings using flags—run argocd proj create --help to see what’s available. Settings can also be configured later using other commands, as we’ll show below.
$ argocd proj create demo-projectList projects
argocd proj list lists all projects and displays their key settings, including allowed app deployment destinations, sources, and resource types.
$ argocd proj list
NAME DESCRIPTION DESTINATIONS SOURCES CLUSTER-RESOURCE-WHITELIST NAMESPACE-RESOURCE-BLACKLIST SIGNATURE-KEYS ORPHANED-RESOURCES
default *,* * */* <none> <none> disabled
demo-project <none> <none> <none> <none> <none> disabledGet a specific project
argocd proj get <project-name> displays the details of a specific project identified by name. The output is displayed in a list, so it’s easier to scan complex configurations.
$ argocd proj get demo-project
Name: demo-project
Description:
Destinations: <none>
Repositories: <none>
Scoped Repositories: <none>
Allowed Cluster Resources: <none>
Scoped Clusters: <none>
Denied Namespaced Resources: <none>
Signature keys: <none>
Orphaned Resources: disabledDelete a project
Delete a project by passing its name to argocd proj delete <project-name>:
$ argocd proj delete demo-projectManage project roles
The argocd proj role command family configures the RBAC roles that are available in the project. Sub-commands let you create, edit, and remove roles, tokens, and policies:
argocd proj role create— Add a role to the project.argocd proj role list— List roles in the project.argocd proj role get— Get the details of a specific role.argocd proj role delete— Delete a role from the project.argocd proj role add-policy— Attach an RBAC policy to a role.argocd proj role remove-policy— Remove a policy from a role.argocd proj role create-token— Add a token to the project.argocd proj role list-tokens— List tokens in the project.argocd proj role delete-token— Delete a token from the project.
Argo’s documentation contains examples of how to use these commands and others in the group.
Add a project destination
Project destinations define Kubernetes clusters to which apps in the project can deploy. You can add a destination by passing a server URL and target namespace name to argocd proj add-destination <project-name>:
# Allow demo-project to deploy to demo-namespace in the kubernetes.example.com cluster
$ argocd proj add-destination demo-project https://kubernetes.example.com demo-namespaceRemove a project destination
Destinations can be removed using argocd proj remove-destination. Repeat the arguments that were passed to add-destination:
$ argocd proj remove-destination demo-project https://kubernetes.example.com demo-namespaceAdd a project source
Project sources define the Git repositories that can be used to deploy apps in the project. They’re added by passing the target project name and repository URL to argocd proj add-source:
$ argocd proj add-source demo-project https://github.com/jhwalker/spacelift-argocd-helm-demo.gitRemove a project source
Use argocd proj remove-source to remove a specific repository URL from a project:
$ argocd proj remove-source demo-project https://github.com/jhwalker/spacelift-argocd-helm-demo.git16. argocd repo
The argocd repo command group manages the Git and Helm repositories connected to your Argo CD instance. It allows you to configure private repositories so they can be used as app sources.
Add a new Git repository
Use the argocd repo add command and specify the Git URL to the repository, either using HTTP or SSH. The --username and --password flags should be set with your credentials when you’re connecting to a private repository over HTTP. Advanced options are also available to specify TLS settings and connect to GitHub Enterprise repositories using a GitHub app.
# HTTP
$ argocd repo add https://git.example.com/user/repo --username <user> --password <password>
# SSH
$ argocd repo add git@git.example.com:user/repoList all repositories
List your connected repositories with argocd repo list:
$ argocd repo list
TYPE NAME REPO INSECURE OCI LFS CREDS STATUS MESSAGE PROJECT
git https://github.com/jamesheronwalker/spacelift-argocd-helm-demo.git false false false false SuccessfulGet a repository’s details
You can fetch a previously added repository’s details by passing its URL to argocd repo get:
$ argocd repo get https://github.com/jhwalker/spacelift-argocd-helm-demo.git
TYPE NAME REPO INSECURE OCI LFS CREDS STATUS MESSAGE PROJECT
git https://github.com/jhwalker/spacelift-argocd-helm-demo.git false false false false SuccessfulRemove a repository
Passing a repository’s URL to the argocd repo rm command will remove it from your Argo instance:
$ argocd repo rm https://git.example.com/user/repo
Repository 'https://github.com/jhwalker/spacelift-argocd-helm-demo.git' removedargocd completion command generates Bash and zsh shell completions. It will write the code for the specified shell to its output.
# Load completions into your current shell instance
$ source <(argocd completion bash)Argo CD authentication sessions can expire and require you to log in again. The relogin command allows you to reauthenticate with your current identity, producing a new session token.
To complete authentication, you’ll be prompted to enter your password. You can also supply the password on the command line using the --password flag.
Use the --sso option instead of setting a password if you authenticate using an external identity service.
You can browse the CLI’s help documentation directly in your terminal. The output is the same as that provided by the docs website.
When run argocd help without any arguments, you’ll see the docs homepage with a list of top-level commands and global flags. You can learn about a specific command using either argocd help <command> or argocd command --help syntax.
argocd version command displays your Argo CLI and server versions. It defaults to showing verbose output that also includes the release build dates, Git commit SHAs, and toolchain versions of each component. The --short flag allows you to print just the version numbers instead.
$ argocd version --short
argocd: v2.8.0+804d4b8
argocd-server: v2.13.2+dc43124Now we’ve covered the main Argo CD commands, here are a few best practices to ensure your Argo CLI operations run smoothly:
1. Ensure you select the correct kube context
Some argocd commands run directly against the Kubernetes API server, instead of your Argo API server. These include all the commands within the argocd admin group and other commands when run with the --core option.
Setting the --kube-context flag lets you specify the Kubernetes context to connect to. Without the flag, Argo will use the default context in your active Kubeconfig file, potentially causing the wrong environment to be targeted.
2. Avoid setting plain-text passwords and tokens in commands
Passing credentials using plaintext --auth-token, --username, and --password flags is risky. They’ll be persisted in your shell history, potentially exposing them to attackers. It’s safer to either use the interactive versions of commands, where possible, or load values directly from files.
$ argocd login —-username <username> --password $(cat argo_password.txt)3. Use multiple config files and contexts to distinguish different environments
Separate Kubernetes clusters are common for development, staging, and production environments. This practice isolates each environment and can help optimize overall resource usage.
Argo’s CLI allows you to switch between Argo CD instances using contexts. A new context is added to your config file each time you run argocd login to connect to a cluster. You can use the argocd context <new-context> command to easily switch between your contexts at any time. Alternatively, you can store each environment in a different file, and then specify the --config flag to select the correct file for your command.
4. Avoid manually using the CLI to manage live deployments
Argo’s CLI is a helpful tool, but running it manually is rarely the best way to deploy production apps to your cluster. Each team member needs to be given Argo credentials, and mistakes could cause misconfigurations that are tricky to diagnose. It’s better to use Argo’s declarative configuration features instead of defining repositories and apps as Kubernetes custom resources you can apply in a CI/CD pipeline.
5. Check your CLI and Argo versions are compatible
Argo CD and its CLI are regularly updated with new features and improvements. It’s important to use fully compatible versions. Using an old CLI release with a newer server could mean features are missing or behave unexpectedly. Remember to update the CLI each time you install a major Argo update in your cluster.
Spacelift is an IaC management platform that uses GitOps to automate CI/CD for your infrastructure components. It supports OpenTofu, Terraform, Terragrunt, CloudFormation, Pulumi, Kubernetes, and Ansible.
The power of Spacelift lies in its fully automated hands-on approach. Once you’ve created a Spacelift stack for your project, changes to the IaC files in your repository will automatically be applied to your infrastructure.
Spacelift’s pull request integrations keep everyone informed of what will change by displaying which resources are going to be affected by new merges. Spacelift also allows you to enforce policies and automated compliance checks that prevent dangerous oversights from occurring.
Spacelift includes drift detection capabilities that periodically check your infrastructure for discrepancies compared to your repository’s state. It can then launch reconciliation jobs to restore the correct state, ensuring your infrastructure operates predictably and reliably.
With Spacelift, you get:
- Policies to control what kind of resources engineers can create, what parameters they can have, how many approvals you need for a run, what kind of task you execute, what happens when a pull request is open, and where to send your notifications
- Stack dependencies to build multi-infrastructure automation workflows with dependencies, having the ability to build a workflow that, for example, generates your EC2 instances using Terraform and combines it with Ansible to configure them
- Self-service infrastructure via Blueprints, or Spacelift’s Kubernetes operator, enabling your developers to do what matters – developing application code while not sacrificing control
- Creature comforts such as contexts (reusable containers for your environment variables, files, and hooks), and the ability to run arbitrary code
- Drift detection and optional remediation
If you want to learn more about Spacelift, create a free account today or book a demo with one of our engineers.
Argo CD’s CLI provides a complete terminal interface for managing Argo apps and installations. It serves the needs of cluster operators and developers who need to deploy to Kubernetes.
The CLI is just one way to interact with Argo. The web UI makes some tasks more efficient, such as quickly monitoring resources using its visual dashboards, while Argo’s API lets you build your own tooling for programmatic management. Nonetheless, a good knowledge of the CLI allows you to control Argo alongside development work without leaving your terminal.
Ready to learn more advanced Argo CD topics? Check out our guide to how Argo can deploy Helm charts or try combining Argo CD and Terraform to manage your entire Kubernetes cluster as code.
Solve your infrastructure challenges
Spacelift is a flexible orchestration solution for IaC development. It delivers enhanced collaboration, automation, and controls to simplify and accelerate the provisioning of cloud-based infrastructures.
