Skip to content
Documentation Background

Argo CD cheatsheet

A reference for day-to-day work, grouped by task. Each section links to the page that explains the behavior. Examples assume a server at argocd.example.com.


Terminal window
argocd login argocd.example.com --grpc-web # username and password
argocd login argocd.example.com --grpc-web --sso # single sign-on
argocd login --core # core install, talk to the Kubernetes API directly
argocd context # list saved contexts
argocd logout argocd.example.com
argocd version

Environment variables avoid repeating flags in scripts: ARGOCD_SERVER, ARGOCD_AUTH_TOKEN, ARGOCD_OPTS (extra flags, such as --grpc-web). See web UI and CLI.


Terminal window
argocd app create catalog-api \
--project shop \
--repo https://git.example.com/shop/deploy-config.git \
--revision main \
--path services/catalog-api/overlays/prod \
--dest-server https://kubernetes.default.svc \
--dest-namespace catalog \
--sync-policy automated --auto-prune --self-heal \
--sync-option CreateNamespace=true
argocd app set catalog-api --revision v2.3.0 # change a field
argocd app set catalog-api --sync-policy none # back to manual sync
argocd app set catalog-api --self-heal=false # turn a setting off
argocd app edit catalog-api # open the manifest in an editor

In a GitOps workflow, prefer committing the Application manifest to Git over argocd app create. See Applications.

Terminal window
argocd app list # all applications (-p <project>, -l key=value)
argocd app get catalog-api # status, source, resources
argocd app get catalog-api --refresh # re-read Git, using the manifest cache
argocd app get catalog-api --hard-refresh # re-render, bypassing the cache
argocd app resources catalog-api # managed resources as a tree
argocd app manifests catalog-api # rendered desired manifests
argocd app manifests catalog-api --source live # live manifests
argocd app diff catalog-api # desired vs live
argocd app diff catalog-api --exit-code # non-zero exit when different, for pipelines
argocd app history catalog-api # deployment history with IDs
argocd app logs catalog-api --kind Deployment --name catalog-api --follow
Terminal window
argocd app sync catalog-api # sync now
argocd app sync catalog-api --dry-run # preview without applying
argocd app sync catalog-api --prune # also delete resources removed from Git
argocd app sync catalog-api --revision <commit-sha> # sync an exact revision
argocd app sync catalog-api --resource apps:Deployment:catalog-api # one resource (GROUP:KIND:NAME)
argocd app sync -l team=shop # every application with a label
argocd app wait catalog-api --sync --health --timeout 300
argocd app rollback catalog-api <history-id> # needs automated sync off
argocd app terminate-op catalog-api # cancel a running operation
Terminal window
argocd app delete catalog-api # cascading, removes managed resources
argocd app delete catalog-api --cascade=false # keep the managed resources
argocd app delete catalog-api --propagation-policy background
Terminal window
argocd appset list
argocd appset get catalog
argocd appset generate -f catalog-appset.yaml # render the Applications without creating them
argocd appset create -f catalog-appset.yaml
argocd appset delete catalog

Terminal window
argocd proj create shop -d https://kubernetes.default.svc,catalog -s https://git.example.com/shop/*
argocd proj list
argocd proj get shop
argocd proj add-source shop https://git.example.com/shop/deploy-config.git
argocd proj add-destination shop https://kubernetes.default.svc catalog
argocd proj allow-cluster-resource shop "" Namespace
argocd proj deny-namespace-resource shop "" ResourceQuota
argocd proj role create shop ci-deployer
argocd proj role add-policy shop ci-deployer --action sync --permission allow --object catalog-api
argocd proj role create-token shop ci-deployer --expires-in 24h

See multi-tenancy and projects.


Terminal window
# Repositories
argocd repo add https://git.example.com/shop/deploy-config.git --username git --password <token> --project shop
argocd repo add [email protected]:shop/deploy-config.git --ssh-private-key-path ~/.ssh/argocd_deploy_key
argocd repo list
argocd repo rm https://git.example.com/shop/deploy-config.git
# Credential templates, applied to every repository under a URL prefix
argocd repocreds add https://git.example.com/shop --username git --password <token>
argocd repocreds list
# Trust material
argocd cert add-tls git.example.com --from ca.crt
argocd cert add-ssh --batch --from known_hosts
argocd gpg add --from signing-key.pub
# Clusters
argocd cluster add prod-eu-context --name prod-eu --label env=prod
argocd cluster list
argocd cluster get prod-eu
argocd cluster set prod-eu --namespace catalog,payments
argocd cluster rotate-auth prod-eu
argocd cluster rm prod-eu

See TLS and repository credentials and cluster management.


Terminal window
argocd account list
argocd account update-password
argocd account generate-token --account automation --expires-in 30d
argocd account can-i sync applications 'shop/catalog-api'
# Validate and test policies offline
argocd admin settings rbac validate --policy-file policy.csv
argocd admin settings rbac can role:developers sync applications 'shop/catalog-api' --policy-file policy.csv
# Operations
argocd admin initial-password -n argocd
argocd admin cluster stats -n argocd # shard distribution
argocd admin export -n argocd > backup.yaml # back up Applications, projects, and settings
argocd admin import - < backup.yaml
argocd admin notifications template notify <template> <app> --recipient slack:ops-alerts

See accounts and RBAC.


KeyValuesEffect
argocd.argoproj.io/sync-waveInteger string, default "0"Orders resources within a sync. Lower first
argocd.argoproj.io/hookPreSync, Sync, PostSync, SyncFail, PreDelete, PostDelete, SkipRuns the resource as a hook in that phase
argocd.argoproj.io/hook-delete-policyHookSucceeded, HookFailed, BeforeHookCreationWhen a finished hook is deleted
argocd.argoproj.io/sync-optionsComma-separated, for example Prune=false,Validate=falsePer-resource sync behavior
argocd.argoproj.io/compare-optionsIgnoreExtraneousExcludes the resource from out-of-sync status
KeyValuesEffect
argocd.argoproj.io/manifest-generate-pathsPaths separated by ;Limits refreshes to commits that touch these paths
argocd.argoproj.io/refreshnormal, hardRequests a refresh. Argo CD removes it afterwards
argocd.argoproj.io/skip-reconcile"true"Pauses reconciliation of the Application
notifications.argoproj.io/subscribe.<trigger>.<service>Recipient, for example ops-alertsSubscribes a channel to a trigger
metadata.finalizersresources-finalizer.argocd.argoproj.io, .../backgroundDeletes managed resources with the Application
KeyValueEffect
app.kubernetes.io/part-ofargocdRequired on ConfigMaps and Secrets that Argo CD should read
argocd.argoproj.io/secret-typerepository, repo-creds, clusterMarks a Secret as a repository, a credential template, or a cluster

KeyPurpose
urlExternal URL, used in SSO redirects and notification links
admin.enabledTurns the built-in admin account on or off
accounts.<name>Declares a local account (apiKey, login)
oidc.config, dex.configSingle sign-on provider settings
timeout.reconciliation, timeout.reconciliation.jitterPolling interval (120s) and added random delay (60s)
resource.customizations.health.<group>_<Kind>Lua health check
resource.customizations.ignoreDifferences.<group>_<Kind>Fields to ignore when diffing
resource.customizations.ignoreResourceUpdates.<group>_<Kind>Fields whose changes do not trigger a refresh
resource.compareoptionsGlobal diff behavior
application.sync.impersonation.enabledSyncs with a project-defined service account
application.sync.requireOverridePrivilegeForRevisionSyncRequires override to sync a different revision
kustomize.buildOptionsExtra arguments for kustomize build
webhook.maxPayloadSizeMBLargest accepted webhook body
ui.bannercontent, ui.cssurlUI banner and custom CSS
KeyPurpose
server.insecureServe plain HTTP, for TLS terminated at a gateway
controller.status.processorsWorkers for status reconciliation (default 20)
controller.operation.processorsWorkers for sync operations (default 10)
controller.sharding.algorithmlegacy, round-robin, or consistent-hashing
controller.repo.server.timeout.secondsController wait for manifest generation
controller.kubectl.parallelism.limitConcurrent kubectl runs
application.namespacesNamespaces where Applications may live
KeyPurpose
policy.csvRole definitions and group assignments
policy.<name>.csvExtra policy files, appended in key order
policy.defaultRole given to authenticated users with no match
policy.matchModeglob (default) or regex
scopesOIDC claims read for group membership, for example [groups, email]
ObjectHolds
argocd-secretadmin.password, server.secretkey, and webhook secrets (webhook.github.secret)
argocd-server-tlsThe API server’s certificate
argocd-tls-certs-cm, argocd-ssh-known-hosts-cm, argocd-gpg-keys-cmTrusted Git TLS certificates, SSH host keys, and GPG keys
argocd-notifications-cm, argocd-notifications-secretNotification services, triggers, templates, and their tokens
argocd-app-controller-shard-cmShard assignments with dynamic distribution

p, <subject>, <resource>, <action>, <object>, <effect>
g, <subject>, <role>
p, role:developers, applications, get, shop/*, allow
p, role:developers, applications, sync, shop/*, allow
p, role:developers, applications, delete, shop/*, deny
g, shop-developers, role:developers
PartNotes
SubjectA user, a group from the SSO claim, or role:<name>
Resourceapplications, applicationsets, clusters, projects, repositories, certificates, accounts, gpgkeys, logs, exec, extensions
Actionget, create, update, delete, sync, override, action/<group>/<kind>/<name>, *
Object<project>/<application> for applications, a name or URL for the rest. Glob patterns allowed
Effectallow or deny. A matching deny always wins

Built-in roles: role:readonly (read everything) and role:admin (everything). The admin account is separate, so disable it once SSO works.


Set at the Application (spec.syncPolicy.syncOptions) or on a resource (argocd.argoproj.io/sync-options).

OptionUse it when
CreateNamespace=trueThe destination namespace may not exist
ServerSideApply=trueResources are too large for client-side apply, such as big CRDs
ApplyOutOfSyncOnly=trueLarge Applications where most resources are unchanged
PruneLast=trueDeleted resources should go only after everything else is healthy
Prune=false / Delete=falseA resource must survive removal from Git or deletion of the Application
Replace=true / Force=trueA resource cannot be patched. Destructive, so scope it to one resource
SkipDryRunOnMissingResource=trueA CRD and its custom resource arrive in the same sync
RespectIgnoreDifferences=trueignoreDifferences rules must also apply during sync

Automated sync policy:

spec:
syncPolicy:
automated:
prune: true # delete what Git no longer defines
selfHeal: true # revert manual changes
retry:
limit: 5
backoff: { duration: 5s, factor: 2, maxDuration: 3m }

See sync policies and options.


Sync statusMeaning
SyncedLive state matches Git
OutOfSyncLive state differs from Git
UnknownComparison failed, usually a repository or cluster connectivity problem
Health statusMeaning
HealthyAll resources are running and ready
ProgressingA resource is still rolling out. Argo CD expects it to become healthy
DegradedA resource failed or timed out
SuspendedPaused on purpose, for example a Deployment with spec.paused: true
MissingA resource is defined in Git but absent from the cluster
UnknownNo health check applies

For a fuller, symptom-based guide, see troubleshooting.

SymptomWhere to look
ComparisonError or manifest generation failedargocd app get <app>, then the argocd-repo-server logs
Stuck OutOfSync with no real changeargocd app diff <app>, then diffing and ignore rules
Sync does not startSync policy, sync windows, and the application-controller logs
permission deniedargocd account can-i, project roles, and policy.csv
Repository not accessibleargocd repo list, credentials, and trusted certificates
Slow or lagging reconciliationController queue metrics, repo server load, and high availability and scaling
No notification arrivedargocd admin notifications trigger run and the notifications controller logs
Terminal window
kubectl logs -n argocd statefulset/argocd-application-controller
kubectl logs -n argocd deploy/argocd-repo-server
kubectl logs -n argocd deploy/argocd-server