Skip to content
Documentation Background

Web UI and CLI

Argo CD offers two interactive clients, and both call the same server API. The web UI is built for visualizing and managing applications. The argocd CLI covers more of the server’s configuration and fits scripts and pipelines.


The landing page after login lists the registered applications. An application is a source of GitOps content bound to a target Kubernetes destination, and it is the main thing end users work with. From this view you can create, inspect, and sync applications without writing manifests by hand.

The second purpose of the UI is administering the server itself. The Settings menu has seven panels:

PanelManages
RepositoriesRemote content sources, such as Git repositories, that Argo CD turns into Kubernetes manifests
CertificatesCustom TLS certificates for secure connections to remote repositories
GnuPG keysPublic keys used to verify GPG signatures on source control commits
ClustersTarget Kubernetes environments that applications are deployed to
ProjectsAppProjects, which group applications with shared configuration and permissions
AccountsLocal user accounts stored in the Argo CD server
AppearanceLook and feel of the UI, such as themes

The User Info page in the navigation sidebar shows the identity of the current session. It is the quickest way to check which identity claims Argo CD received and how they map to RBAC permissions.

Many server parameters are read-only in the browser or missing from it. Registering a new remote cluster and changing a local account password both require the CLI or declarative manifests. Treat the UI as the place to observe and operate applications, and use the CLI or manifests for administration.


The CLI calls the same API as the UI and exposes a superset of its capabilities. Scripts, CI/CD pipelines, and other automation commonly drive Argo CD through it.

  • Package managers - for example brew install argocd on macOS and Linux, and an Arch Linux package
  • Prebuilt binaries - downloadable from the Argo CD GitHub releases for Linux, macOS, and Windows
  • Container images - images that include the argocd binary, for pipeline steps

Most commands need a server connection, so the first step is argocd login. The command prompts for a username and password. For a fresh install, use admin and the initial password described under first access.

Terminal window
argocd login argocd.example.com --grpc-web
FlagEffect
--grpc-webWraps gRPC in ordinary HTTP requests, so the CLI works behind a proxy or ingress that does not support HTTP/2
--insecureSkips server certificate and domain verification, needed for self-signed certificates
--ssoLogs in through the configured single sign-on provider instead of a password
--coreTalks directly to the Kubernetes API instead of an Argo CD API server, for core installs
--nameNames the saved context
--username, --passwordPass credentials non-interactively

Without any exposure, the CLI can also reach the API server through a temporary port-forward when given --port-forward-namespace argocd on each command. Setting ARGOCD_OPTS='--port-forward-namespace argocd' applies it to every command.

After a successful login, the CLI stores tokens, server endpoints, and contexts in a file named config. The CLI chooses its directory in this order:

  1. ARGOCD_CONFIG_DIR, if set
  2. ~/.argocd, if it already exists (legacy location)
  3. $XDG_CONFIG_HOME/argocd, if XDG_CONFIG_HOME is set
  4. ~/.config/argocd

The --config flag points a single command at a different file. Each login creates a context, and the CLI manages them with these commands:

Terminal window
argocd context # list saved contexts
argocd context <context> # switch to a context
argocd context <context> --delete
argocd logout <context> # end the session for a context

Password changes go through the CLI. The command asks for the current password and then the new one:

Terminal window
argocd account update-password
# change another local account (needs RBAC permission to do so)
argocd account update-password --account <name>

The server validates the new password against a regular expression. The default is ^.{8,32}$, which accepts 8 to 32 characters, and the passwordPattern key in argocd-cm changes it. To confirm a rotation, log out of the context and log in again with the new password.


SymptomLikely causeFix
argocd login hangs with no outputThe TLS probe against the server stallsAdd --skip-test-tls, or check that the server address and port are reachable
x509: certificate signed by unknown authoritySelf-signed certificate on the server or ingressAdd --insecure, or install a trusted certificate
Commands work over a port-forward but fail through the ingressThe proxy does not pass gRPC (HTTP/2)Log in with --grpc-web
new password does not match the following expressionThe new password violates passwordPatternChoose a password that matches the pattern, or change the pattern in argocd-cm
Commands act on the wrong Argo CD serverAnother context is activeRun argocd context and switch to the right one