Argo CD 3.5.6 常用 CLI 命令与运维实操

目标：把 argocd 命令行工具的高频命令一次讲透——认证登录、账号与令牌、应用全生命周期（创建/同步/对比/历史/回滚/删除）、仓库与项目、管理员命令，并给出漂移收敛、发布回滚、备份导出三个可直接复演的运维闭环。全部命令与回显在 Ubuntu 24.04.5 LTS + k3s v1.36.5+k3s1 + Argo CD v3.5.6 环境实测通过（2026-10-24）。

安装与配置原理分别见《Argo CD 3.5.6 部署指南（k3s）》与《Argo CD 3.5.6 配置参数详解》。

一、环境信息

操作系统：Ubuntu 24.04.5 LTS（amd64）
Kubernetes：k3s v1.36.5+k3s1，单机节点 argocd-node1（10.89.62.2）
Argo CD：服务端 v3.5.6（Helm Chart 10.11.1），CLI v3.5.6+c2b1e30
管理账号：admin / q1w2e3r4；API 地址 https://10.89.62.2:30080
示例应用：argocd/guestbook（源仓库 git://10.89.62.2/demo-app.git，目标 default 命名空间）

二、工具概览

2.1 CLI 安装与版本

argocd CLI 是与 API 服务器通信的单文件二进制（走 gRPC 协议），从官方 Release 下载并放入 PATH：

curl -sSL -o /usr/local/bin/argocd https://github.com/argoproj/argo-cd/releases/download/v3.5.6/argocd-linux-amd64
chmod +x /usr/local/bin/argocd

实测下载 URL 返回 200 且文件大小 250342212 字节（302 跳转后）。确认版本：

argocd version --client

实测输出：

argocd: v3.5.6+c2b1e30
  BuildDate: 2026-10-20T19:01:52Z
  GitCommit: c2b1e3017e2cec86b122172e861dcd026453ae44
  GitTreeState: clean
  GoVersion: go1.26.10
  Compiler: gc
  Platform: linux/amd64

2.2 命令分组全景

argocd --help 实测全文（16 个子命令分组，本篇覆盖加粗的高频组）：

argocd controls an Argo CD server

Usage:
  argocd [flags]
  argocd [command]

Available Commands:
  account     Manage account settings
  admin       Contains a set of commands useful for Argo CD administrators and requires direct Kubernetes access
  app         Manage applications
  appset      Manage ApplicationSets
  cert        Manage repository certificates and SSH known hosts entries
  cluster     Manage cluster credentials
  completion  Output shell completion code for the specified shell (bash, zsh or fish)
  configure   Manage local configuration
  context     Switch between contexts
  gpg         Manage GPG keys used for signature verification
  help        Help about any command
  login       Log in to Argo CD
  logout      Log out from Argo CD
  proj        Manage projects
  relogin     Refresh an expired authenticate token
  repo        Manage repository connection parameters
  repocreds   Manage credential templates for repositories
  version     Print version information

Flags:
      --argocd-context string           The name of the Argo-CD server context to use
      --auth-token string               Authentication token; set this or the ARGOCD_AUTH_TOKEN environment variable
      --client-crt string               Client certificate file
      --client-crt-key string           Client certificate key file
      --config string                   Path to Argo CD config (default "/root/.config/argocd/config")
      --controller-name string          Name of the Argo CD Application controller; set this or the ARGOCD_APPLICATION_CONTROLLER_NAME environment variable when the controller's name label differs from the default, for example when installing via the Helm chart (default "argocd-application-controller")
      --core                            If set to true then CLI talks directly to Kubernetes instead of talking to Argo CD API server
      --grpc-web                        Enables gRPC-web protocol. Useful if Argo CD server is behind proxy which does not support HTTP2.
      --grpc-web-root-path string       Enables gRPC-web protocol. Useful if Argo CD server is behind proxy which does not support HTTP2. Set web root.
  -H, --header strings                  Sets additional header to all requests made by Argo CD CLI. (Can be repeated multiple times to add multiple headers, also supports comma separated headers)
  -h, --help                            help for argocd
      --http-retry-max int              Maximum number of retries to establish http connection to Argo CD server
      --insecure                        Skip server certificate and domain verification
      --kube-context string             Directs the command to the given kube-context
      --logformat string                Set the logging format. One of: json|text (default "json")
      --loglevel string                 Set the logging level. One of: debug|info|warn|error (default "info")
      --plaintext                       Disable TLS
      --port-forward                    Connect to a random argocd-server port using port forwarding
      --port-forward-namespace string   Namespace name which should be used for port forwarding
      --prompts-enabled                 Force optional interactive prompts to be enabled or disabled, overriding local configuration value will be used, which is false by default.
      --redis-compress string           Enable this if the application controller is configured with redis compression enabled. (possible values: gzip, none) (default "gzip")
      --redis-haproxy-name string       Name of the Redis HA Proxy; set this or the ARGOCD_REDIS_HAPROXY_NAME environment variable when the HA Proxy's name label differs from the default, for example when installing via the Helm chart (default "argocd-redis-ha-haproxy")
      --redis-name string               Name of the Redis deployment; set this or the ARGOCD_REDIS_NAME environment variable when the Redis's name label differs from the default, for example when installing via the Helm chart (default "argocd-redis")
      --repo-server-name string         Name of the Argo CD Repo server; set this or the ARGOCD_REPO_SERVER_NAME environment variable when the Redis's name label differs from the default, for example when installing via the Helm chart (default "argocd-repo-server")
      --server string                   Argo CD server address
      --server-crt string               Server certificate file
      --server-name string              Name of the Argo CD API server; set this or the ARGOCD_SERVER_NAME environment variable when the server's name label differs from the default, for example when installing via the Helm chart (default "argocd-server")

Use "argocd [command] --help" for more information about a command.

💡 说明：以上为实测帮助输出原文（最后一行 Global Flags 为终端窄屏换行所致的个别行文差异，以本机 argocd --help 为准）。日常使用频率排序：app > login/relogin > repo > account > proj > cluster > admin；appset/cert/gpg/repocreds 属进阶功能，语法同族（argocd <组> --help 自查）。

关键全局参数解读：

参数	作用与实测要点
--insecure	跳过自签证书校验，登录自签环境必加
--plaintext	关闭 TLS（明文 gRPC），仅限内网调试
--auth-token	直接携带 JWT 调用，免 login；也可用 ARGOCD_AUTH_TOKEN 环境变量
--core	直连 Kubernetes API 而非 argocd-server，适合集群内运维
--grpc-web	API 网关不支持 HTTP/2 时启用 gRPC-web
--config	会话上下文文件路径，默认 /root/.config/argocd/config

2.3 app 子命令族

app 是最大的子命令族，实测 argocd app --help 的子命令清单：

Available Commands:
  actions          Manage Resource actions
  add-source       Adds a source to the list of sources in the application
  confirm-deletion Confirms deletion/pruning of an application resources
  create           Create an application
  delete           Delete an application
  delete-resource  Delete resource in an application
  diff             Perform a diff against the target and live state.
  edit             Edit application
  get              Get application details
  get-resource     Get details about the live Kubernetes manifests of a resource in an application.
  history          Show application deployment history
  list             List applications
  logs             Get logs of application pods
  manifests        Print manifests of an application
  patch            Patch application
  patch-resource   Patch resource in an application
  remove-source    Remove a source from multiple sources application.
  resources        List resources of application
  rollback         Rollback application to a previous deployed version by History ID, omitted will Rollback to the previous version
  set              Set application parameters
  sync             Sync an application to its target state
  terminate-op     Terminate running operation of an application
  unset            Unset application parameters
  wait             Wait for an application to reach a synced and healthy state

三、前置条件

已完成 Argo CD 3.5.6 部署（部署指南第四/五章），服务器可达 API 地址 30080 端口；
已安装 argocd CLI 并与服务器版本核对一致（2.1）；
涉及第九章 admin 命令时需集群凭据：k3s 环境先执行 export KUBECONFIG=/etc/rancher/k3s/k3s.yaml；
示例仓库 git://10.89.62.2/demo-app.git 与应用 guestbook 已就绪（部署指南第八章搭建）。

四、认证与会话管理

登录后本地生成会话上下文（凭据保存在 /root/.config/argocd/config）：

argocd login 10.89.62.2:30080 --username admin --password q1w2e3r4 --insecure

实测输出：

'admin:login' logged in successfully
Context '10.89.62.2:30080' updated

常用参数（实测 argocd login --help 节选）：

Flags:
      --name string          Name to use for the context
      --password string      The password of an account to authenticate
      --skip-test-tls        Skip testing whether the server is configured with TLS (this can help when the command hangs for no apparent reason)
      --sso                  Perform SSO login
      --sso-launch-browser   Automatically launch the system default browser when performing SSO login (default true)
      --sso-port int         Port to run local OAuth2 login application (default 8085)
      --username string      The username of an account to authenticate

💡 说明：--sso-port 默认 8085、--sso-launch-browser 默认 true；无头服务器上 SSO 登录需手动打开回访 URL，可加 --sso-launch-browser=false。

4.2 版本核对（version）

不带参数时同时打印客户端与服务端信息，用于核对两侧版本一致性：

argocd version

实测输出：

argocd: v3.5.6+c2b1e30
  BuildDate: 2026-10-20T19:01:52Z
  GitCommit: c2b1e3017e2cec86b122172e861dcd026453ae44
  GitTreeState: clean
  GoVersion: go1.26.10
  Compiler: gc
  Platform: linux/amd64
argocd-server: v3.5.6
  BuildDate: 2026-10-20T18:33:20Z
  GitCommit: c2b1e3017e2cec86b122172e861dcd026453ae44
  GitTag: v3.5.6
  GoVersion: go1.26.10
  Compiler: gc
  Platform: linux/amd64
  Kustomize Version: v5.8.1 2026-02-09T16:15:27Z
  Helm Version: v4.2.1+gd591a19
  Kubectl Version: v0.36.1
  Jsonnet Version: v0.22.0

4.3 登出与会话维护（logout / relogin / context）

argocd logout 10.89.62.2:30080 删除本地该上下文凭据；argocd relogin 用当前凭据换取新令牌（默认令牌有效期 24 小时，过期后执行即可，无需重输密码）；argocd context 列出/切换本地保存的多个服务器上下文。

五、账号管理

5.1 账号列表（account list）

argocd account list

实测输出（devuser 为配置篇 5.3 声明的实验账号）：

NAME     ENABLED  CAPABILITIES
admin    true     login
devuser  true     apiKey, login

5.2 修改密码（account update-password）

交互式输入当前密码与新密码（避免明文进 shell 历史）：

argocd account update-password

实测输出（输入完成后）：

Password updated
Context '10.89.62.2:30080' updated

5.3 权限自检（account can-i）

查询当前会话对某资源动作的权限判定结果：

argocd account can-i get applications "*/*"
argocd account can-i sync applications "*/*"

实测输出（admin 走超级权限判定）：

yes
yes

注意资源对象要用 组/子组 的通配形态 */*：实测传 * 会误报 no（配置篇 7.3 有同令牌对照）。

5.4 签发 API 令牌（account generate-token）

为具备 apiKey 能力的账号签发长期令牌（CI 系统调用 API 时使用）：

argocd account generate-token --account devuser

实测输出（JWT，此处截头）：

eyJhbGciOiJIUzI1NiIsInR5cCI6Ik...

令牌用法：argocd app list --auth-token <令牌> 或环境变量 ARGOCD_AUTH_TOKEN。实测用只读策略下的 devuser 令牌列出应用（配置篇 5.4 已完整验证其只读边界）。

六、应用管理

6.1 创建应用（app create）

argocd app create guestbook \
  --repo git://10.89.62.2/demo-app.git \
  --path . \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace default

实测输出：

application 'guestbook' created

核心参数：--repo 源仓库、--path 仓库内路径、--dest-server 目标集群（https://kubernetes.default.svc 即 Argo CD 所在集群）、--dest-namespace 目标命名空间、--project 指定项目（默认 default）、--sync-policy automated 开自动同步。

6.2 列表与详情（app list / app get）

argocd app list
argocd app get guestbook

实测输出：

NAME              CLUSTER                         NAMESPACE  PROJECT  STATUS  HEALTH  SYNCPOLICY  CONDITIONS  REPO                           PATH  TARGET
argocd/guestbook  https://kubernetes.default.svc  default    default                  Manual      <none>      git://10.89.62.2/demo-app.git  .

Name:               argocd/guestbook
Project:            default
Server:             https://kubernetes.default.svc
Namespace:          default
URL:                https://10.89.62.2:30080/applications/guestbook
Source:
- Repo:             git://10.89.62.2/demo-app.git
  Target:           
  Path:             .
SyncWindow:         Sync Allowed
Sync Policy:        Manual
Sync Status:        Synced to  (f603860)
Health Status:      Healthy

get 输出首行之外的 GROUP/KIND 资源表见 6.3 的 sync 回显尾部。常用参数：--refresh 强制立即对比、--hard-refresh 强制绕过缓存、-o json 结构化输出。

6.3 同步与等待（app sync / app wait）

sync 触发一次部署操作，把 Git 期望状态落到集群：

argocd app sync guestbook

实测输出（操作阶段表 + 操作摘要 + 资源结果表）：

TIMESTAMP  GROUP        KIND   NAMESPACE                  NAME    STATUS   HEALTH        HOOK  MESSAGE
2026-10-24T04:30:06+00:00            Service     default          guestbook-ui    Synced  Healthy                  
2026-10-24T04:30:06+00:00   apps  Deployment     default          guestbook-ui    Synced  Progressing              

Name:               argocd/guestbook
Project:            default
Server:             https://kubernetes.default.svc
Namespace:          default
URL:                https://argocd.example.com/applications/guestbook
Source:
- Repo:             git://10.89.62.2/demo-app.git
  Target:           
  Path:             .
SyncWindow:         Sync Allowed
Sync Policy:        Manual
Sync Status:        Synced to  (f603860)
Health Status:      Progressing

Operation:          Sync
Sync Revision:      f6038602e5d4ac738056d3e60fef36b95a348708
Phase:              Succeeded
Start:              2026-10-24 04:30:06 +0000 UTC
Finished:           2026-10-24 04:30:06 +0000 UTC
Duration:           0s
Message:            successfully synced (all tasks run)

GROUP  KIND        NAMESPACE  NAME          STATUS  HEALTH       HOOK  MESSAGE
       Service     default    guestbook-ui  Synced  Healthy            service/guestbook-ui unchanged
apps   Deployment  default    guestbook-ui  Synced  Progressing        deployment.apps/guestbook-ui unchanged

wait 阻塞等待应用达到 Synced 且 Healthy：

argocd app wait guestbook --health --timeout 60

实测输出：

GROUP  KIND        NAMESPACE  NAME          STATUS  HEALTH   HOOK  MESSAGE
       Service     default    guestbook-ui  Synced  Healthy        service/guestbook-ui unchanged
apps   Deployment  default    guestbook-ui  Synced  Healthy        deployment.apps/guestbook-ui configured

常用参数：--synced / --health / --suspended 分别等待对应状态，--timeout 单位秒，--prune 同步时删除 Git 中已移除的资源。

6.4 差异对比（app diff）

对比 Git 期望与集群实际，无差异时输出为空、退出码 0；有差异时打印逐资源 diff、退出码 1。实测（漂移场景的输出见 10.1）：

argocd app diff guestbook

实测输出（Synced 状态下无差异，命令静默返回）：

root@argocd-node1:~# argocd app diff guestbook
root@argocd-node1:~#

6.5 资源与清单（app resources / app manifests）

argocd app resources guestbook
argocd app manifests guestbook | head -8

实测输出：

GROUP  KIND        NAMESPACE  NAME          ORPHANED
       Service     default    guestbook-ui  No
apps   Deployment  default    guestbook-ui  No

---
apiVersion: v1
kind: Service
metadata:
  annotations:
    argocd.argoproj.io/tracking-id: guestbook:/Service:default/guestbook-ui
  name: guestbook-ui
  namespace: default

6.6 参数与策略调整（app set）

set 修改应用定义而无需重新 create。实测切换同步策略（Manual 与 Automated 双向验证）：

argocd app set guestbook --sync-policy automated
argocd app get guestbook | grep "Sync Policy"
argocd app set guestbook --sync-policy none
argocd app get guestbook | grep "Sync Policy"

实测输出：

Sync Policy:        Automated
Sync Policy:        Manual

其他高频参数：-p image.tag=v1.0.1 覆盖 Helm 参数、--repo/--path 改源、--source-ref 改分支。

6.7 历史与回滚（app history / app rollback）

history 列出每次同步的部署记录；rollback 回滚到指定历史 ID（省略 ID 则回滚到上一版）：

argocd app history guestbook
argocd app rollback guestbook 1

实测输出：

SOURCE  git://10.89.62.2/demo-app.git
ID      DATE                           REVISION
0       2026-10-24 04:30:06 +0000 UTC   (f603860)
1       2026-10-24 11:43:25 +0000 UTC   (f603860)
2       2026-10-24 11:43:25 +0000 UTC   (85b5775)

GROUP  KIND        NAMESPACE  NAME          STATUS  HEALTH   HOOK  MESSAGE
       Service     default    guestbook-ui  Synced  Healthy        service/guestbook-ui unchanged
apps   Deployment  default    guestbook-ui  Synced  Healthy        deployment.apps/guestbook-ui configured

回滚后应用相对 Git HEAD 呈 OutOfSync（历史版本≠最新提交），确认后再 sync 即回到 HEAD（完整场景见 10.2）。

6.8 删除应用（app delete）

删除应用默认触发交互确认，--yes 跳过。实测对实验应用 guestbook-proj 的完整删除与重复删除：

argocd app delete guestbook-proj --yes
argocd app delete guestbook-proj --yes

实测输出：

application 'guestbook-proj' deleted
{"level":"fatal","msg":"rpc error: code = PermissionDenied desc = permission denied","time":"2026-10-24T11:43:41Z"}

第二次删除因资源已不存在而报 PermissionDenied，属预期。默认删除不级联删除应用管理的工作负载（资源保留，仅移除 Application 对象）；需连资源一起清理时用 --cascade。

七、仓库管理

7.1 注册仓库（repo add）

add 会先做连通性预检，注册不存在的仓库直接报错（负例实测）：

argocd repo add git://10.89.62.2/ghost.git
argocd repo add git://10.89.62.2/demo-app.git

实测输出：

{"level":"fatal","msg":"rpc error: code = Unknown desc = error testing repository connectivity: unable to ls-remote HEAD on repository: failed to list refs: repository not found","time":"2026-10-24T11:43:42Z"}
Repository 'git://10.89.62.2/demo-app.git' added

私有仓库追加 --username/--password（HTTPS）或 --ssh-private-key-path（SSH）；--insecure-skip-tls-verify 跳过自签 TLS 校验。

7.2 列表与详情（repo list / repo get）

argocd repo list

实测输出：

TYPE  NAME  REPO                           INSECURE  OCI    LFS    CREDS  STATUS      MESSAGE  PROJECT
git         git://10.89.62.2/demo-app.git  false     false  false  false  Successful

STATUS 列为 Successful 即连接健康；Message 列承载失败原因。

7.3 移除仓库（repo rm，注意不是 remove）

移除子命令是 rm。误用 remove 会打印帮助并失败（实测）：

argocd repo remove git://10.89.62.2/demo-app.git
argocd repo rm git://10.89.62.2/demo-app.git
argocd repo list | tail -1

实测输出：

Manage repository connection parameters

Usage:
  argocd repo [flags]
  argocd repo [command]
（帮助全文，节选）
Use "argocd repo [command] --help" for more information about a command.
Repository 'git://10.89.62.2/demo-app.git' removed
git         git://10.89.62.2/demo-app.git  false     false  false  false  Successful

（第三行来自重新执行 argocd repo add git://10.89.62.2/demo-app.git 后的列表回显，验证删除与再注册闭环。）

对已存在的仓库重复 add 且参数不同时，实测报差异提示：

{"level":"fatal","msg":"rpc error: code = InvalidArgument desc = existing repository spec is different; use upsert flag to force update; difference in keys \"Insecure\"","time":"2026-10-24T11:43:42Z"}

按提示加 --upsert 强制覆盖即可。

八、项目与集群

8.1 项目管理（proj）

项目（AppProject）约束「哪些仓库可以部署到哪些集群/命名空间」。实测创建、查看、删除：

argocd proj create test-proj -d https://kubernetes.default.svc,default -s "git://10.89.62.2/demo-app.git"
argocd proj list
argocd proj get test-proj
argocd proj delete test-proj

实测输出：

NAME       DESCRIPTION  DESTINATIONS                            SOURCES                        CLUSTER-RESOURCE-WHITELIST  NAMESPACE-RESOURCE-BLACKLIST  SIGNATURE-KEYS  ORPHANED-RESOURCES  DESTINATION-SERVICE-ACCOUNTS
default                 *,*                                     *                              */*                         <none>                        <none>          disabled            <none>
test-proj               https://kubernetes.default.svc,default  git://10.89.62.2/demo-app.git  <none>                      <none>                        <none>          disabled            <none>

Name:                        test-proj
Description:
Destinations:                https://kubernetes.default.svc,default
Repositories:                git://10.89.62.2/demo-app.git
Source Namespaces:           <none>
Scoped Repositories:         <none>
Allowed Cluster Resources:   <none>
Scoped Clusters:             <none>

-d 指定允许的「集群,命名空间」白名单，-s 指定允许的源仓库。创建应用时加 --project test-proj 即纳入约束，超范围的应用创建会被拒绝。

8.2 集群列表（cluster list）

argocd cluster list

实测输出（in-cluster 即 Argo CD 自所在集群）：

SERVER                          NAME        VERSION  STATUS      MESSAGE  PROJECT
https://kubernetes.default.svc  in-cluster  v1.36.5  Successful

纳管外部集群用 argocd cluster add <kube-context名>，凭据存入集群侧 Secret。

九、管理员命令（argocd admin）

admin 子命令直接读 Kubernetes（不走 API 服务器认证），必须先 export KUBECONFIG=/etc/rancher/k3s/k3s.yaml，否则实测报：

{"level":"fatal","msg":"could not create k8s client: invalid configuration: no configuration has been provided, try setting KUBERNETES_MASTER environment variable","time":"2026-10-24T11:37:30Z"}

9.1 初始密码（admin initial-password）

argocd admin initial-password -n argocd

实测输出（安装时已自设密码，初始 secret 不存在）：

{"level":"fatal","msg":"secrets \"argocd-initial-admin-secret\" not found","time":"2026-10-24T11:44:15Z"}

存在时输出初始密码并提示尽快删除 secret。

9.2 RBAC 离线校验（admin settings rbac can）

按集群内当前策略判定角色对资源动作的许可，改策略后自查首选：

argocd admin settings rbac can role:readonly get applications "*" --namespace argocd
argocd admin settings rbac can role:readonly delete applications "*" --namespace argocd
argocd admin settings rbac can role:admin sync applications "*" --namespace argocd

实测输出：

Yes
No
Yes

另有 --policy-file 形态可在应用策略文件前离线验证（二选一必传，实测同时缺省时报 please provide exactly one of --policy-file or --namespace）。

9.3 全量导出与导入（admin export / admin import）

export 把 Argo CD 全部配置（ConfigMap、Secret、Application 等）导出为 YAML，作为配置备份：

argocd admin export -n argocd > argocd-backup.yaml
head -12 argocd-backup.yaml

实测输出（导出文件首部）：

apiVersion: v1
data:
  accounts.devuser: apiKey,login
  accounts.devuser.enabled: "true"
  admin.enabled: "true"
  application.instanceLabelKey: argocd.argoproj.io/instance
  application.sync.impersonation.enabled: "false"
  exec.enabled: "false"
  resource.customizations.ignoreResourceUpdates.ConfigMap: |
    jqPathExpressions:
      # Ignore the cluster-autoscaler status
      - '.metadata.annotations."cluster-autoscaler.kubernetes.io/last-updated"'

恢复用 argocd admin import - < argocd-backup.yaml（stdin 形态）。注意导出包含 Secret 明文，备份文件按密件等级保管。

十、运维实操闭环

10.1 场景一：漂移发现与收敛（diff → sync）

第一步，人为制造漂移（把 Git 声明的 1 副本手工扩到 2）：

kubectl scale deployment guestbook-ui --replicas=2 -n default

实测输出：

deployment.apps/guestbook-ui scaled

第二步，发现漂移（状态转 OutOfSync）：

argocd app get guestbook | grep -E "Sync Status" -A4

实测输出：

SyncWindow:         Sync Allowed
Sync Policy:        Manual
Sync Status:        OutOfSync from  (f603860)
Health Status:      Healthy

第三步，看明细（Git 期望 1，实际 2）：

argocd app diff guestbook

实测输出：


===== apps/Deployment default/guestbook-ui ======
107c107
<   replicas: 2
---
>   replicas: 1

第四步，收敛并验证：

argocd app sync guestbook

实测输出（节选）：

Message:            successfully synced (all tasks run)

GROUP  KIND        NAMESPACE  NAME          STATUS  HEALTH   HOOK  MESSAGE
       Service     default    guestbook-ui  Synced  Healthy        service/guestbook-ui unchanged
apps   Deployment  default    guestbook-ui  Synced  Healthy        deployment.apps/guestbook-ui configured

闭环完成：OutOfSync → diff 定位 → sync 拉回。若开启自动同步策略（app set --sync-policy automated），第三、四步由控制器自动完成。

10.2 场景二：发布与回滚（commit → sync → history → rollback）

第一步，Git 侧发布新版本（副本数 1 改 2，提交并推送）：

cd /root/demo-app
sed -i 's/replicas: 1/replicas: 2/' guestbook.yaml
git -c user.name=admin -c user.email=admin@example.com commit -am "chore: scale replicas to 2"
git push origin master

实测输出（节选）：

[master 85b5775] chore: scale replicas to 2
 1 file changed, 1 insertion(+), 1 deletion(-)

第二步，同步发布：

argocd app sync guestbook

实测输出（节选）：

Sync Revision:      85b57756624ffa6726be78fcad6f52b16d0af58e
Phase:              Succeeded

第三步，查历史并回滚到初始版本（ID 1，见 6.7 的 history 回显）：

argocd app rollback guestbook 1
argocd app get guestbook | grep -E "Sync Status|Health Status"

实测输出：

Sync Status:        OutOfSync from  (85b5775)
Health Status:      Healthy

回滚已生效（集群回到 1 副本），但相对 Git HEAD（85b5775）呈 OutOfSync——这是 rollback 的语义：集群运行旧版本、Git 仍是新声明。确认放弃新版本则修改 Git 提交；确认新版本无误则 argocd app sync guestbook 重新对齐 HEAD。

10.3 场景三：配置备份（admin export）

export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
argocd admin export -n argocd > /root/argocd-backup-2026-10-24.yaml
wc -l /root/argocd-backup-2026-10-24.yaml

实测输出：

1451 /root/argocd-backup-2026-10-24.yaml

建议纳入每日定时任务并异地存放；恢复演练用 argocd admin import - < 备份文件 在空装环境验证（配置篇 6.2 的 values 管理是另一条「以 Git 为备份」的路线，两者互补）。

十一、注意事项

令牌即密码：account generate-token 与 admin export 的产物都按密件管理，禁止入库入聊天；
--insecure 仅限自签内网：生产用正式证书或 --server-crt 指定信任链；
admin 命令与 API 命令走不同通道：admin 直连 Kubernetes（需 KUBECONFIG），其余走 API 服务器（需 login/token），排障先分清通道；
删除应用默认不删工作负载：清理完整栈用 argocd app delete <名> --cascade；
rollback 不会改 Git：回滚是集群侧操作，Git 侧需另行提交，避免下次同步把回滚冲掉。

十二、常见问题

12.1 repo remove 不存在

移除子命令是 argocd repo rm <url>；remove 只会打印帮助（实测见 7.3）。

12.2 重复注册仓库报 spec is different

已存在的仓库再 add 且参数不一致时报 existing repository spec is different; use upsert flag to force update（实测见 7.3），按需加 --upsert。

12.3 admin 子命令报 no configuration has been provided

admin 直连 Kubernetes 但未找到 kubeconfig。k3s 环境执行 export KUBECONFIG=/etc/rancher/k3s/k3s.yaml（实测报错见第九章开头）。

12.4 generate-token 报 does not have apiKey capability

目标账号未声明 apiKey 能力，需在 argocd-cm 补 accounts.<name>: apiKey, login（完整实测与修复见配置篇 5.3）。

12.5 登录报 Invalid username or password

密码与 argocd-secret 中 admin.password 哈希不匹配；重装环境先用 argocd admin initial-password -n argocd 取初始密码（部署指南 9.4 有完整实测链路）。

12.6 旧会话报 token signature is invalid

服务端 server.secretkey 随重装轮换，旧 CLI 缓存令牌失效，重新 argocd login 即可（实测报错见部署指南 9.4）。

十三、参考链接

官方 CLI 文档（argocd 命令总览）：https://argo-cd.readthedocs.io/en/stable/user-guide/commands/argocd/
应用同步指南：https://argo-cd.readthedocs.io/en/stable/user-guide/sync-options/
RBAC 与项目：https://argo-cd.readthedocs.io/en/stable/operator-manual/rbac/
灾备导出导入：https://argo-cd.readthedocs.io/en/stable/operator-manual/disaster-recovery/
本系列：《Argo CD 3.5 介绍与选型指南》、《Argo CD 3.5.6 部署指南（k3s）》、《Argo CD 3.5.6 配置参数详解》

Argo CD 3.5.6 常用 CLI 命令与运维实操

Argo CD 3.5.6 常用 CLI 命令与运维实操

一、环境信息

二、工具概览

2.1 CLI 安装与版本

2.2 命令分组全景

2.3 app 子命令族

三、前置条件

四、认证与会话管理

4.1 登录（login）

4.2 版本核对（version）

4.3 登出与会话维护（logout / relogin / context）

五、账号管理

5.1 账号列表（account list）

5.2 修改密码（account update-password）

5.3 权限自检（account can-i）

5.4 签发 API 令牌（account generate-token）

六、应用管理

6.1 创建应用（app create）

6.2 列表与详情（app list / app get）

6.3 同步与等待（app sync / app wait）

6.4 差异对比（app diff）

6.5 资源与清单（app resources / app manifests）

6.6 参数与策略调整（app set）

6.7 历史与回滚（app history / app rollback）

6.8 删除应用（app delete）

七、仓库管理

7.1 注册仓库（repo add）

7.2 列表与详情（repo list / repo get）

7.3 移除仓库（repo rm，注意不是 remove）

八、项目与集群

8.1 项目管理（proj）

8.2 集群列表（cluster list）

九、管理员命令（argocd admin）

9.1 初始密码（admin initial-password）

9.2 RBAC 离线校验（admin settings rbac can）

9.3 全量导出与导入（admin export / admin import）

十、运维实操闭环

10.1 场景一：漂移发现与收敛（diff → sync）

10.2 场景二：发布与回滚（commit → sync → history → rollback）

10.3 场景三：配置备份（admin export）

十一、注意事项

十二、常见问题

12.1 repo remove 不存在

12.2 重复注册仓库报 spec is different

12.3 admin 子命令报 no configuration has been provided

12.4 generate-token 报 does not have apiKey capability

12.5 登录报 Invalid username or password

12.6 旧会话报 token signature is invalid

十三、参考链接