Consul CLI

Consul CLI command reference for service discovery, key-value store, health checks, cluster management, and service mesh operations. Use when executing Consu...

Security Scan

This is an instruction-only Consul CLI reference (documentation) and its content, requirements, and absence of installers/code are consistent with that purpose.

Purpose & Capability

The skill is purely a CLI reference for HashiCorp Consul and contains example commands, env var names, and file paths appropriate to that purpose. One minor inconsistency: it does not declare the 'consul' binary as a required binary even though the guidance is explicitly about running consul commands.

Instruction Scope

SKILL.md and the reference file provide command examples and describe environment variables and paths (e.g., CONSUL_HTTP_TOKEN, /etc/consul.d, backup.snap). These are presented as examples/documentation and do not instruct the agent to read or exfiltrate unrelated files or secrets.

Install Mechanism

No install spec and no code files are present (instruction-only). This is the lowest-risk install profile — nothing will be written or executed by the skill itself.

Credentials

The documentation references sensitive env vars (CONSUL_HTTP_TOKEN, CONSUL_HTTP_TOKEN_FILE, TLS cert/key paths) that are normal for Consul use. The skill does not request or require those values from the environment, which is proportionate, but users should be aware commands shown could be used with real tokens/paths and thus could act on sensitive data if executed.

Persistence & Privilege

always:false (default) and there is no install or configuration modification. The skill does not request persistent privileges or system-wide changes.

Assessment

This skill is a documentation-only Consul CLI reference and appears coherent. Before using it: (1) ensure the 'consul' binary is present and you understand the effects of commands you run (ACL, snapshot restore, force-leave, etc. can be destructive); (2) never paste real tokens or secrets into public prompts — the docs reference CONSUL_HTTP_TOKEN and token-management commands which are sensitive; (3) because the skill source is unknown, treat it as read-only documentation rather than an automated tool — if you permit the agent to execute commands, restrict or review those actions first.

HashiCorp Consul 命令行工具参考指南。

Quick Start

# 查看所有命令
consul

# 查看命令帮助
consul <command> -h
consul <command> <subcommand> -h

# 启用自动补全
consul -autocomplete-install

Global Options

consul [--version] [--help] <command> [<args>]

常用全局环境变量：

• CONSUL_HTTP_ADDR - Agent 地址 (默认 http://127.0.0.1:8500)
• CONSUL_HTTP_TOKEN - ACL Token
• CONSUL_HTTP_TOKEN_FILE - Token 文件路径
• CONSUL_HTTP_SSL - 启用 HTTPS
• CONSUL_HTTP_SSL_VERIFY - SSL 证书验证 (默认 true)
• CONSUL_CACERT - CA 证书路径
• CONSUL_NAMESPACE - 命名空间 (Enterprise)

Agent Commands

启动 Agent

# 开发模式 (快速测试)
consul agent -dev

# 开发模式 + 允许外部访问
consul agent -dev -client='0.0.0.0'

# 服务器模式
consul agent -server \
  -bootstrap-expect=3 \
  -data-dir=/opt/consul/data \
  -bind=192.168.1.1 \
  -client=0.0.0.0 \
  -ui

# 加入集群
consul agent -config-dir=/etc/consul.d \
  -retry-join="provider=aws tag_key=consul tag_value=server"

Agent 常用参数：

参数	说明
-dev	开发模式
-server	服务器模式
-bootstrap-expect=N	期望服务器数量
-data-dir=<path>	数据目录
-bind=<IP>	绑定地址
-client=<IP>	客户端接口地址
-ui	启用 Web UI
-join=<addr>	加入集群 (已弃用，用 -retry-join)
-retry-join=<addr>	重试加入集群
-datacenter=<name>	数据中心名称
-node=<name>	节点名称
-config-dir=<path>	配置目录
-config-file=<path>	配置文件
-encrypt=<key>	加密密钥

管理操作

# 重载配置
consul reload

# 优雅停止
consul leave

# 强制节点离开
consul force-leave <node>

# 查看成员
consul members
consul members -detailed
consul members -wan
consul members -status=alive

# 查看信息
consul info

KV Commands

consul kv <subcommand> [options] [args]

子命令

# 写入
consul kv put <key> <value>
consul kv put redis/config/connections 5
consul kv put -flags=123 mykey myvalue  # 附加 flags

# 读取
consul kv get <key>
consul kv get redis/config/connections
consul kv get -detailed <key>  # 详细信息

# 递归读取
consul kv get -recurse
consul kv get -recurse redis/

# 删除
consul kv delete <key>
consul kv delete -recurse <prefix>

# 导出/导入
consul kv export <prefix> > backup.json
consul kv import @backup.json

# 锁操作
consul kv put -acquire=<session-id> <key> <value>
consul kv put -release=<session-id> <key>

Catalog Commands

consul catalog <subcommand> [options]

子命令

# 列出数据中心
consul catalog datacenters

# 列出节点
consul catalog nodes
consul catalog nodes -service=redis
consul catalog nodes -detailed

# 列出服务
consul catalog services
consul catalog services -node=<node-name>

Services Commands

consul services <subcommand> [options]

子命令

# 注册服务 (命令行)
consul services register -name=web
consul services register -name=redis -tag=primary -port=6379

# 注册服务 (配置文件)
cat > web.json << 'EOF'
{
  "Service": {
    "Name": "web",
    "Tags": ["v1", "production"],
    "Port": 8080,
    "Check": {
      "HTTP": "http://localhost:8080/health",
      "Interval": "10s"
    }
  }
}
EOF
consul services register web.json

# 注销服务
consul services deregister -id=web
consul services deregister web.json

ACL Commands

consul acl <subcommand> [options]

Bootstrap

# 初始化 ACL 系统
consul acl bootstrap
# 返回: AccessorID, SecretID (root token)

Policy 管理

# 创建策略
consul acl policy create \
  -name "service-read" \
  -description "Read access to services" \
  -rules @policy.hcl

# 列出策略
consul acl policy list

# 读取策略
consul acl policy read -name "service-read"

# 更新策略
consul acl policy update -name "service-read" -rules @new-policy.hcl

# 删除策略
consul acl policy delete -name "service-read"

策略规则示例：

# policy.hcl
service_prefix "" {
  policy = "read"
}
key_prefix "config/" {
  policy = "write"
}
node "" {
  policy = "read"
}

Token 管理

# 创建 Token
consul acl token create \
  -description "My token" \
  -policy-name "service-read"

# 列出 Token
consul acl token list

# 读取 Token
consul acl token read -accessor-id=<id>

# 更新 Token
consul acl token update -accessor-id=<id> -description "Updated"

# 删除 Token
consul acl token delete -accessor-id=<id>

# 设置 Agent Token
consul acl set-agent-token default <secret-id>

Role 管理

consul acl role create -name="my-role" -policy-name="service-read"
consul acl role list
consul acl role read -name="my-role"
consul acl role delete -name="my-role"

Operator Commands

consul operator <subcommand> [options]

Raft 管理

# 列出 Raft 节点
consul operator raft list-peers

# 移除 Raft 节点
consul operator raft remove-peer <node-id>

# 集群状态
consul operator autopilot get-config

区域管理

# 列出区域
consul operator area list

# 创建区域
consul operator area create -name="us-west"

Snapshot Commands

# 创建快照
consul snapshot save backup.snap

# 从 Agent 保存
consul snapshot save -http-addr=http://192.168.1.1:8500 backup.snap

# 恢复快照
consul snapshot restore backup.snap

# 检查快照
consul snapshot inspect backup.snap

Connect / Service Mesh Commands

consul connect <subcommand> [options]

Intention 管理

# 列出意图
consul intention list

# 创建意图
consul intention create web db
consul intention create -deny web malicious

# 删除意图
consul intention delete web db

# 检查意图
consul intention check web db

代理配置

# 生成代理配置
consul connect proxy-config -service=web

Debug & Monitoring Commands

Monitor

# 实时日志
consul monitor

# 指定日志级别
consul monitor -log-level=debug

Debug

# 收集调试信息
consul debug -duration=30s -output=/tmp/consul-debug

Info

# 运行时信息
consul info

RTT

# 网络延迟估算
consul rtt <node1> <node2>
consul rtt dc1.node1 dc2.node2

Event & Exec Commands

Event

# 触发自定义事件
consul event -name="deploy" -node="web-*" "deploy v1.2.3"

# 列出事件
consul event -name="deploy" -list

Exec

# 在节点上执行命令
consul exec -service=web "uptime"
consul exec -node="web-01" "systemctl restart nginx"

# 注意: 需要启用 enable_script_checks

Lock Command

# 持有锁执行命令
consul lock my-lock "echo 'doing work'"

# 带超时
consul lock -timeout=30s my-lock "my-command"

# 监听模式
consul lock -monitor-retry=5 my-lock "my-command"

Watch Command

# 监听变更
consul watch -type=key -key=my-key "echo 'key changed'"
consul watch -type=services "echo 'services changed'"
consul watch -type=nodes "echo 'nodes changed'"
consul watch -type=checks -service=web "echo 'checks changed'"

TLS Commands

consul tls <subcommand> [options]

生成证书

# 创建 CA
consul tls ca create

# 创建服务器证书
consul tls cert create -server -dc=dc1

# 创建客户端证书
consul tls cert create -client -dc=dc1

# 指定域名
consul tls cert create -server -dc=dc1 -domain=consul -additional-dnsname=server.dc1.consul

Validate Command

# 验证配置文件
consul validate /etc/consul.d/

# 验证单个文件
consul validate config.json

Common Patterns

健康检查脚本

#!/bin/bash
# 检查服务健康状态
SERVICE=$1
STATUS=$(consul kv get -detailed "service/$SERVICE/health" | grep "Value" | awk '{print $2}')
if [ "$STATUS" != "passing" ]; then
  echo "Service $SERVICE is unhealthy"
  exit 1
fi

服务发现

# 获取服务地址
consul catalog nodes -service=web | tail -n +2 | awk '{print $3}'

# 获取服务端口
consul kv get service/web/port

集群启动脚本

#!/bin/bash
# 启动 3 节点集群
for i in 1 2 3; do
  mkdir -p /tmp/consul/node$i
  consul agent -server \
    -bootstrap-expect=3 \
    -data-dir=/tmp/consul/node$i \
    -bind=127.0.0.1 \
    -port=$((8300 + i - 1)) \
    -http-port=$((8500 + i - 1)) \
    -node=node$i &
done

Exit Codes

代码	说明
0	成功
1	错误
2	连接错误
3	速率限制

References

For detailed command reference, see:

• cli-reference.md - Complete CLI command reference