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.
Web UI
Section titled “Web UI”Applications view
Section titled “Applications view”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.
Settings
Section titled “Settings”The second purpose of the UI is administering the server itself. The Settings menu has seven panels:
| Panel | Manages |
|---|---|
| Repositories | Remote content sources, such as Git repositories, that Argo CD turns into Kubernetes manifests |
| Certificates | Custom TLS certificates for secure connections to remote repositories |
| GnuPG keys | Public keys used to verify GPG signatures on source control commits |
| Clusters | Target Kubernetes environments that applications are deployed to |
| Projects | AppProjects, which group applications with shared configuration and permissions |
| Accounts | Local user accounts stored in the Argo CD server |
| Appearance | Look and feel of the UI, such as themes |
User info
Section titled “User info”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.
What the UI cannot do
Section titled “What the UI cannot do”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.
Installation
Section titled “Installation”- Package managers - for example
brew install argocdon 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
argocdbinary, for pipeline steps
Logging in
Section titled “Logging in”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.
argocd login argocd.example.com --grpc-web| Flag | Effect |
|---|---|
--grpc-web | Wraps gRPC in ordinary HTTP requests, so the CLI works behind a proxy or ingress that does not support HTTP/2 |
--insecure | Skips server certificate and domain verification, needed for self-signed certificates |
--sso | Logs in through the configured single sign-on provider instead of a password |
--core | Talks directly to the Kubernetes API instead of an Argo CD API server, for core installs |
--name | Names the saved context |
--username, --password | Pass 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.
Config file and contexts
Section titled “Config file and contexts”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:
ARGOCD_CONFIG_DIR, if set~/.argocd, if it already exists (legacy location)$XDG_CONFIG_HOME/argocd, ifXDG_CONFIG_HOMEis set~/.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:
argocd context # list saved contextsargocd context <context> # switch to a contextargocd context <context> --deleteargocd logout <context> # end the session for a contextChanging a password
Section titled “Changing a password”Password changes go through the CLI. The command asks for the current password and then the new one:
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.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Likely cause | Fix |
|---|---|---|
argocd login hangs with no output | The TLS probe against the server stalls | Add --skip-test-tls, or check that the server address and port are reachable |
x509: certificate signed by unknown authority | Self-signed certificate on the server or ingress | Add --insecure, or install a trusted certificate |
| Commands work over a port-forward but fail through the ingress | The proxy does not pass gRPC (HTTP/2) | Log in with --grpc-web |
new password does not match the following expression | The new password violates passwordPattern | Choose a password that matches the pattern, or change the pattern in argocd-cm |
| Commands act on the wrong Argo CD server | Another context is active | Run argocd context and switch to the right one |