Dex CLI
dexcli 提供以 JSON 为主的 Flow 运维和检查接口，适合 shell automation、AI agent 和人工操作。
启动本地开发服务器
dexcli dev 启动 server-zd 和内嵌 Dex Web。server-zd 是唯一的 engine。 现有脚本可以保留 --engine zd，该选项不产生额外效果。 发布包在 dexcli 旁边包含 dex-server-zd。CLI 依次查找 --zd-binary、 DEX_SERVER_ZD_BINARY、可执行文件所在目录（包括解析符号链接后的目录），最后查找 PATH。
dexcli dev --open=false --zd-data-dir ./dex-state
| Flag | 默认值和行为 |
|---|---|
| --engine | zd；为兼容现有脚本而保留。 |
| --zd-binary | 覆盖随包提供的 server-zd 可执行文件。 |
| --zd-data-dir | $HOME/.dex/zd/<dex-port>；本地持久化状态。 |
| --zd-config | 可选的 server-zd YAML 配置覆盖文件。 |
| --attribute-store-config | 可选 YAML 文件；server-zd 读取其中的 attributeStore 部分。支持 PostgreSQL。 |
| --bind-address | 127.0.0.1；本地服务绑定的 IP。 |
| --dex-port | 8801；Dex gRPC 端口。 |
| --web-port | 8802；内嵌 Dex Web 端口。 |
| --open | true；使用 --open=false 不打开浏览器。 |
| --server-log-folder | 默认为空，日志写入 stderr。设置后也会写入该目录的 dex-server-zd.log。 |
| --flow-rendering-dir | 可选的 Flow Definition Graph JSON 目录。 |
| --connector-config-dir | $HOME/.dex/connectors；本地 Connector 凭据。 |
| --connector-release-override | 可重复的 connector-id=artifact-directory，用于本地 Connector 发布包。 |
默认端口被占用时，Dex 会选择下一个可用端口并打印地址。显式指定的端口被占用时启动失败。 状态目录使用实际选中的 Dex 端口。Ctrl+C 会停止 Web 和 server-zd 子进程。 server-zd 支持 pull Worker。存储、持久性和 Attribute Store 配置见 server-zd 运维。
Temporal engine 已移除。--engine temporal、所有 --external-temporal-* 和 --temporal-* flag、--sqlite-db-filename、--verbose-engine-log 和 --blob-store-dir 现在都会报错，并明确说明 server-zd 是唯一的 engine。 请移除这些 flag，改用 --zd-data-dir 和 --zd-config。 请使用新的 server-zd 数据目录；Temporal SQLite 文件不能作为 server-zd 状态使用。
连接 Dex
command 默认连接 127.0.0.1:8801。可通过 DEX_FLOW_SERVICE_ADDRESS 设置 process 级目标，或为单次 command 传入 --server。Server address 必须是 gRPC host:port，不能是 HTTP URL。除非启用 TLS，connection 使用明文。
DEX_FLOW_SERVICE_ADDRESS=dex.example.internal:8801 dexcli health
dexcli --server 127.0.0.1:9901 flow search
通过 TLS 连接
当 Dex 或其前面的 load balancer 终止 TLS 时，传入 --tls 或设置 DEX_TLS=true。 CLI 随后使用 TLS 1.2 或更高版本，并用系统根 CA 验证 server certificate。 certificate 必须匹配 --server 的 host，CLI 也会把它作为 TLS server name 发送。 TLS 不会回退到明文。
dexcli --server dex.example.com:443 --tls health
DEX_TLS=true dexcli --server dex.example.com:443 flow search
以下两个可选设置需要启用 TLS：
- --tls-ca-file 或 DEX_TLS_CA_FILE 指定 PEM 格式的根 CA 文件，这些 CA 会在系统根 CA 之外被信任。server certificate 由私有或自签名 CA 签发时使用。
- --tls-server-name 或 DEX_TLS_SERVER_NAME 设置 server certificate 必须匹配的 名称，例如 --server 是 IP address 时。
dexcli --server 10.0.0.12:443 --tls \
--tls-ca-file /etc/dex/ca.pem --tls-server-name dex.example.internal health
CLI 通过 h2 ALPN protocol 协商 HTTP/2。终止 TLS 的 load balancer 必须接受 h2，并通过 HTTP/2 把 gRPC 转发给 Dex。
身份认证
Dex 要求 bearer credential 时，可用 --credential-file 指定 token 文件， 用 DEX_CREDENTIAL_FILE 指定 token 文件路径，或用 DEX_CREDENTIAL 提供 token 值。 优先级按上述顺序排列。CLI 会在首次调用前读取文件；flow watch 等长时间运行的 command 至多每秒检查一次文件变化。文件为空或无法读取时，调用会在连接 Dex 前失败。 CLI 会去除 token 两端的空白字符。
dexcli flow search --credential-file /run/secrets/dex/token
DEX_CREDENTIAL_FILE=/run/secrets/dex/token dexcli flow watch order-123
CLI 不提供原始 token flag，因为 command 参数可能出现在 shell history 和 process list 中。 未使用 --tls 时，FlowService 使用明文 gRPC connection，token 会以未加密形式经过网络。 请启用 TLS 或保护其 network path。
易用的 Flow 操作
使用 flow search、summary、state、history 和 inspect 获取有界的 JSON response。inspect 会组合 summary、current state 和 history，适合作为调查 Flow 时的起点。
dexcli flow inspect order-123 --all-history
stored string 和 object 默认会被 hydrate。只需要结构和 Blob identity 时，使用 --no-hydrate。此时输出包含稳定的 __dexBlobReference object，而不是 stored payload。
flow watch 会先输出已有的 semantic history event，再 long-poll 新 event。每行是一个 JSON object。Flow 到达 terminal status 后 command 会停止；--follow-runs 会持续 跟随该 Flow ID 的 current run。
stop 和 time travel 必须同时提供准确的 --run-id 和显式 --yes。这样可以防止在解析 旧 run 后误改较新的 run。
完整的 public API 访问
api command 暴露已安装 CLI 所知的全部 public FlowService RPC：
dexcli api list
dexcli api describe InvokeRPC
dexcli api call InvokeRPC --data @invoke.json --yes
api describe 返回 request 和 response field、oneof、enum、map 以及可达的 message definition。api call 通过 inline string、@file 或 --data - 的 stdin 接受 canonical protobuf JSON。它返回 canonical protobuf JSON，不执行易用层的 value hydration。
WorkerService 和 InternalService 是 Worker callback 与 Server internal protocol， 因此不会出现在 public operator API 中。
检查协议兼容性
dexcli version 输出 CLI build version。dexcli version check 调用 Server，并验证 Server 的闭协议区间是否与当前 CLI 内置的区间相交：
dexcli version check --server dex.example.internal:8801
dexcli version check --output table
成功结果包含 client 与 Server version、双方区间、作为 negotiatedProtocol 的最高公共 协议，以及 compatible: true，exit status 为 0。信息 RPC 未实现、response 无效、 连接失败或区间不相交时，command 会输出结构化 compatibility error，并以 status 1 退出。 该 command 支持通用的 --server、--timeout 和 --output flag。
输出和错误
JSON 是默认的稳定输出。--output table 用于人工阅读，不是 machine compatibility contract。对有界 command 使用 --timeout 0 可以关闭默认的 30 秒 client deadline； watch 会自行管理 long-poll lifecycle，直到被中断。
error 以 JSON 写入 stderr。其中包含 kind、operation 和 message；适用时还包含 grpcCode、grpcCodeName 和结构化 status detail。exit status 2 表示 usage 无效或 缺少 confirmation，status 1 表示 request 失败。