fix: 按 issue #2 逐条订正 CLI 能力/flag/字段/脚本(实测 coolify-cli v1.6.2) - #3
Conversation
#1 的能力表与边界声明已在 16e372d 订正(README ✅、SKILL "Resource Creation"); 本提交补齐 issue 要求的"可走通路径"细节: - 在 SKILL.md 把 "Resource Creation" 升为决策树路径 F - 先 `server list` / `project list` / `project get` 拿 placement UUID,再 create - 标注 `app create public` 的最小必填 flag(git-repository/branch/build-pack/ports-exposes) - 保留保守提醒:create 类命令参数多且随版本变化,执行前 `--help` 核对 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
#2:原脚本用 `deploy list` 再按字段过滤取本 app 的最新部署。但全局列表无可靠 的 app-UUID 列(`application_id` 是内部数字 id,非 app uuid),by-uuid 部署永远 匹配不到。改用 issue 推荐的 `coolify app deployments list <app-uuid>`——该端点本 身就只返回该 app 的部署,无需任何字段过滤,jq 失败时回退到同一命令的 table 输出。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
#3:skill 面向"别人对着自己的生产 Coolify",token abilities 才是限制 Agent 跑飞破坏范围的根本控制,此前完全没提。补齐: - SKILL First-Time Setup:新增"Token permissions (least privilege)"表, 列出 read/deploy/write/read:sensitive/root 各 ability 含义与推荐组合 (日常 read+deploy;改配置才加 write;永不用 root) - safety-rules:新增 token 权限段——read:sensitive=服务端脱敏(非自觉)、 Allowed IPs、team scoping,以及"403 读返回体 missing permissions"定位法 - cheatsheet:403 troubleshooting 行升级为"--debug 读 403 body 的 missing permissions,补对应 ability,勿升级到 root" - README / README.zh-CN Requirements:API token 加最小权限说明 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
#4:`--build-time` 与 `--runtime` 注册默认值都是 true,但代码仅在显式传入时 才下发;`--help` 显示 default:true 会让人误以为"裸 sync 即全部 build-time", 也误以为"不加 --build-time 就能把密钥挡在 build 层外"——实则要排除 build 层 必须显式 `--build-time=false`。且 sync 是全文件一套 flag,敏感/非敏感须分两遍。 - deploy-patterns Next.js + env 分层:把"不加 --build-time"改为敏感那遍显式 `--build-time=false`,并写明 sync 全文件一套 flag - cheatsheet Env:补 `--runtime`(默认 true);加 --help default 与真实行为 不一致的显著警告;env create 同样有 build-time/runtime/is-multiline/comment - SKILL D 段:补 build-time 默认 true 的注意事项与 --build-time=false 排除法 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
#06:手维护的 cheatsheet 会持续 drift。CLI 自带 `coolify docs`(markdown/llms, llms 即"Generate llms.txt for AI agents")。新增 anti-drift 入口: - scripts/gen-reference.sh:跑 `coolify docs markdown` + `coolify docs llms`, 输出到 references/_generated/(含 VERSION.txt 标注版本);.gitignore 忽略之 - SKILL Core Principle #2:改为"flag 真实值以 --help 或生成参考为准;cheatsheet 仅高频速查 + jq + 故障表,可能 drift" - cheatsheet 顶部:注明生成参考为权威来源,本表仅速查 - SKILL Scripts 段 + 中英 README 项目结构:登记 gen-reference.sh Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
#07:以下命令组此前完全缺失,均按 v1.6.2 --help 核实补入: - GitHub App 集成(list/get/repos/branches/create/update/delete)—— app create github 依赖其 app-uuid;create 所需 8 个必填 flag 已列出 - Private keys(list/add/remove)——命令名是 `private-key`(非 privatekeys) - Storage 持久卷(app/database/service storage 同形,create --type persistent|file) - App previews delete(预览部署清理) - Server add / remove(原只有 list/get/validate/domains) - Database 也有 env 与 storage:Env 段说明从"仅 app/service"改为含 database; Database 段补 env/storage 指引 - Teams(list/current/get/members)——与 token team scoping 相关 - 目录补上述小节锚点 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
#08:把"The CLI is an HTTP API client, not SSH"的绝对化措辞,改为"本 skill 范围内 (deploy/app/service/database/env/logs/backup 全部 v1.6.2 命令)走 REST API,与 SSH 无关"。 实测说明:issue 提到的 `init` / `firewall` / `common sshmesh` 在已验证的 v1.6.2 二进制 中**并不存在**(`coolify --help` 无这些命令),故不为其编造稳定文档;仅作为"未来 Coolify v5 的实验命令、走 SSH+root、不在本 skill 范围"的 caveat 提及,并明确:加固 公网 DB 端口的源 IP 限制仍用 ufw / 云安全组,与(未来的)CLI firewall(管 mesh 容器 规则)不是一回事。README 中英版同步去掉"与 SSH 无关"的绝对措辞。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
#09:safety-rules 原写"不把 token 写进任何文件",与 CLI 自身行为矛盾——CLI 合法地 把 token 持久化在 `~/.config/coolify/config.json`(文件 0600 / 目录 0750)。改为: - 这是 CLI 的合法存储,不需要"修正"或搬移;但 Agent 不应 cat / 回显 / 复制该文件 - 补轮换命令 `coolify context set-token <name> <new-token>`;并提示该文件有本地读取 风险,主机疑似被入侵时应在 Web UI 吊销并立即轮换 - 中英 README 的"不写进文件"同步改为"不从 CLI 自身配置文件里复制出来" Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
#10:`env sync` 的 `-f` 是 `--file`(StringP("file","f",...)),与跳过确认无关,
原"绝不加 -f"会让 Agent 连 `-f .env` 都回避。实测进一步发现:
- v1.6.2 **没有全局 `--force`**;`--force` 是按命令注册的
- `app delete`:`-f`/`--force` = 跳过删除确认
- `deploy name|uuid`:只有 `--force`(强制重部署),**无 `-f` 短选项**
- `env sync`:`-f` = `--file`(.env 路径,必填,安全)
- `database delete`:无 force flag(改用 --delete-volumes 等,默认 true)
改动:safety-rules 入口与 deploy 行、SKILL 原则 #4 改为"绝不主动加跳过确认的
--force,但 env sync 的 -f 是 --file";cheatsheet 全局 flag 段移除误标的
`-f, --force`,补 per-command 的 `-f` 含义清单;修正 `deploy name -f` → `--force`。
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
#11:原脚本仅 `curl install.sh | bash` 一条路径,网络受限时无兜底。 - 安装顺序改为官方 curl 脚本 → Homebrew → `go install`,逐级回退;依赖 pipefail 确保 curl 失败不会被下游 bash 吞掉 - 全部失败时给出三条手动路径(brew / go / releases) - 顺手修正 `coolify --version`(实测会报 unknown flag)→ `coolify version` - go install 场景在 PATH 提示里补充 $(go env GOPATH)/bin README 兼容性版本号此前已填入实测 v1.6.2 / v4.1.1,无占位需处理。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…ssue #2-12) #12:`app logs` 支持 `-n/--lines`(默认 100)与 `-f/--follow`,原 cheatsheet 只写了 `coolify app logs <uuid>`。补上 -f / -n;并与 `deployments logs` 的 follow/lines 对齐说明(后者默认 0=全部,另有 --debuglogs 显示隐藏/内部构建命令)。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
#13:缺少"装上先自检"入口,环境问题(CLI 太旧 / context 没连 / token 权限不足 / 缺 jq)往往操作中途才暴露。新增 scripts/doctor.sh,一屏给出四项结论: ① coolify version ≥ 已验证基线 1.6.2(sort -V 比较,不支持时降级) ② jq 是否安装 ③ context verify 连通 + 鉴权 ④ token 权限:read 探测(resource list)+ 非破坏性 deploy 探测(故意用不存在的 uuid,deploy 权限不足会先 403,有权限则 404,绝不真的部署);write / read:sensitive 说明无法无副作用探测,指向 safety-rules 已对真实实例跑通(4 项全绿,exit 0,无任何部署副作用);shellcheck severity=warning 干净。SKILL Scripts 段加"首次/排障先跑 doctor",中英 README 项目结构登记。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
修 #10 时顺带发现:全局 flag 段列了 `--host <fqdn>` 用于"临时覆盖 URL",但 v1.6.2 实测 `coolify --host ... ` 直接报 `unknown flag: --host`——该 flag 不存在。v1.6.2 的 per-invocation 覆盖只有 `--context` 与 `--token`,无 URL 覆盖项。改为说明用 `--context=<name>` 临时切换实例。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Seems you are using me but didn't get OPENAI_API_KEY seted in Variables/Secrets for this repo. you could follow readme for more information |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 426fe27b93
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ## Env | ||
|
|
||
| > The env subcommands for app and service are identical; the example below uses app. | ||
| > The env subcommands are identical across **app, service, and database** (e.g. `coolify database env list <db-uuid>`, `coolify database env sync <db-uuid> --file .env`); the examples below use app. |
There was a problem hiding this comment.
When users apply the Env section to databases, this new statement sends them to the app/service flag set, but I checked coolify-cli v1.6.2 cmd/database/env/sync.go and the database sync command only registers --file/-f and --is-literal, not --build-time, --runtime, or --preview. As written, an agent following the new database-inclusive guidance can run coolify database env sync <db-uuid> --build-time=false or similar and get an unknown-flag failure instead of syncing the DB env file.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
✅ 已修复 (32f35d3)。本机 v1.6.2 --help 复核属实:database env sync 仅 -f/--file + --is-literal,database env create 也无 --build-time/--runtime/--preview(数据库无 build 步骤)。已把 Env 段与 Database 段的'与 app/service 一致'改为明确标注 database env 为 reduced flag 集。
将 #8C52FF/#A78BFA 两支紫色全部替换为 #2DD4BF/#5EEAD4, 并同步 style 属性中重复的 rgb() 值。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Seems you are using me but didn't get OPENAI_API_KEY seted in Variables/Secrets for this repo. you could follow readme for more information |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c525ceb284
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| LOWEST="$(printf '%s\n%s\n' "$VER" "$MIN_VER" | sort -V | head -n1)" | ||
| if [ "$LOWEST" = "$MIN_VER" ]; then |
There was a problem hiding this comment.
When coolify version returns a release string with the leading v (the v1.6.2 CLI source initializes version = "v1.6.2"), this raw sort -V comparison treats 1.6.2 as lower than any v1.x.y; for example v1.6.1 sorts after 1.6.2, so the doctor reports ≥ verified baseline instead of warning. This breaks the preflight precisely for users on older CLI versions where flag drift is most likely, so strip an optional v prefix before comparing.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
✅ 已修复 (32f35d3)。比较前用 ${VER#v} 去掉可选前导 v,避免 sort -V 把 1.6.2 排在 v1.x.y 之前导致旧版本(如 v1.6.1)被误判为 >= baseline。已用 v1.6.1/1.6.1/v1.6.2/v1.7.0 验证判定正确。
按用户批准,把 #08 原先的 inline caveat 升级为显著标注的 [ALPHA] 段落: 明确列出 init(WireGuard mesh + Podman 引导)/ firewall(COOLIFY-ALLOW iptables 链、跨主机容器规则)/ common sshmesh 这组走 SSH+root 的 Coolify v5 路线图命令, 并强调它们**不在已验证的 v1.6.2 二进制中**(`coolify --help` 无此命令)、本 skill 不使用也不当作可用功能文档化、使用前需对照自己的 CLI 构建核实;同时重申:加固 公网 DB 端口源 IP 仍用 ufw/云安全组,与(未来的)firewall 管 mesh 容器规则不是 一回事。不为 v1.6.2 里不存在的命令编造可用 flag。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Seems you are using me but didn't get OPENAI_API_KEY seted in Variables/Secrets for this repo. you could follow readme for more information |
经本机 v1.6.2 --help 复核,两条均属实,已修:
1. database env 并非"与 app/service 一致"(cli-cheatsheet):实测
`database env sync` 只有 `-f/--file` + `--is-literal`,`database env create` 也无
`--build-time/--runtime/--preview`(数据库无 build 步骤)。原"identical across
app/service/database"会让 Agent 跑 `database env sync --build-time=false` 得到
unknown-flag。改为明确标注 database env 是 reduced 集。
2. doctor.sh 版本比较未归一化前导 v:`coolify version` 在部分构建会返回 `v1.6.2`,
`sort -V` 会把 `1.6.2` 排在任何 `v1.x.y` 之前,导致 v1.6.1 用户被误判为
">= baseline"(恰恰在最易 flag drift 的旧版本上失效)。比较前 `${VER#v}` 去掉
可选前导 v(已用 v1.6.1/1.6.1/v1.6.2/v1.7.0 验证判定正确)。
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Seems you are using me but didn't get OPENAI_API_KEY seted in Variables/Secrets for this repo. you could follow readme for more information |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 32f35d3ca3
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| coolify app storage list <app-uuid> | ||
| coolify app storage create <app-uuid> --type persistent --name <vol> --mount-path /data | ||
| coolify app storage create <app-uuid> --type file --mount-path /etc/app/config.yml --content "$(cat config.yml)" | ||
| coolify app storage update <app-uuid> <storage-uuid> ... |
There was a problem hiding this comment.
When users follow this new Storage section to update an existing volume/file mount, the command will fail before reaching Coolify: in v1.6.2 cmd/application/storage/update.go, the update command is defined as Use: "update <app-uuid>", enforces exactly one positional arg, and requires the storage identifier via --uuid (or deprecated --id). Document this as coolify app storage update <app-uuid> --uuid <storage-uuid> --type ... rather than making <storage-uuid> a second positional argument.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
✅ 已修复 (69d3ad9)。本机 v1.6.2 --help 复核属实:app storage update <app_uuid> 仅一个位置参数,storage 标识须用 --uuid <storage-uuid>(--id 已弃用)。已改为 coolify app storage update <app-uuid> --uuid <storage-uuid> --type ...。另注:app storage delete <app-uuid> <storage-uuid> 经核实确实是两个位置参数(你也未误报),已补注两者差异。
经本机 v1.6.2 --help 复核属实:`app storage update` 只接受一个位置参数 `<app_uuid>`,storage 标识必须用 `--uuid <storage-uuid>`(`--id` 已弃用), 原 cheatsheet 写成第二个位置参数会直接失败。改为 `coolify app storage update <app-uuid> --uuid <storage-uuid> --type ...`。 注:`app storage delete <app-uuid> <storage-uuid>` 经核实确实是两个位置参数 (Codex 也未误报),保留并补注两者差异。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Seems you are using me but didn't get OPENAI_API_KEY seted in Variables/Secrets for this repo. you could follow readme for more information |
|
@copilot 再次严格的做一个code review |
|
Seems you are using me but didn't get OPENAI_API_KEY seted in Variables/Secrets for this repo. you could follow readme for more information |
完成了全量 code review，共发现并修复 8 处问题： P1 (correctness)
P2 (quality) 所有脚本通过 |
Copilot 的 afc1643 共 8 处改动,其中 6 处正确(命令拼写/缺参/sslmode 描述/ deploy-and-watch 解析逻辑/版本前缀/年份)予以保留;两处经实测为 regression,本提交修正: 1. health-check.sh 的 jq 匹配:`.status != "running"` 会把真实状态 `running:healthy` / `running:unknown`(实例实测值)全部误报为"not running"。改为 `(.status | startswith("running") | not)`——比原 `test("running")` 子串匹配更精确, 且能正确放过所有 running:* 状态。 2. 三个脚本的 `"${CTX_ARGS[@]}"` 数组写法:在 macOS 默认 `/bin/bash` 3.2 上, `set -u` 展开空数组会报 `unbound variable` 直接崩溃(env bash → /bin/bash 3.2)。 实测 Copilot 版 doctor.sh 不带 context 参数跑到第 3 步即 exit。改回 `CTX_FLAG=""` 字符串惯用法(兼容 bash 3.2;SC2086 仅 info 级,CI severity=warning 通过)。保留 Copilot 对 deploy-and-watch 解析逻辑的改进。 验证:三脚本 shellcheck --severity=warning 干净;doctor.sh / health-check.sh 在 /bin/bash 3.2、不带参数下均 exit 0 正常运行,health-check 正确识别 running:* 为健康。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Seems you are using me but didn't get OPENAI_API_KEY seted in Variables/Secrets for this repo. you could follow readme for more information |
|
感谢 review。8 处里 6 处正确已保留（ 1. health-check.sh 的 jq 匹配 — 误报健康资源
已改为 2. 你的 doctor.sh 不带 context 参数实跑到第 3 步即崩溃退出——而这三个恰是"先跑"的预检脚本。已改回 验证:三脚本 |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 02c3e413de
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| VER="$(coolify version 2>/dev/null | head -n1 || echo unknown)" | ||
| VER_DISPLAY="${VER#v}" # strip optional leading 'v' for display | ||
| echo "📚 Generating reference from coolify CLI v${VER_DISPLAY} → references/_generated/" | ||
| mkdir -p "$OUT_DIR" |
There was a problem hiding this comment.
When this script is re-run after coolify update or a downgrade where a command has been removed or renamed, mkdir -p leaves the old files under references/_generated/markdown in place and doc.GenMarkdownTree only overwrites files it emits for the current CLI. Because the new docs tell agents to treat this directory as authoritative, stale command pages from a previous CLI version can survive and be followed as if they were current; remove the generated subdirectories/files before regenerating.
Useful? React with 👍 / 👎.
对照 issue #2 的 13 条修复清单逐条处理,每条相关联的修复对应一个 commit,全部以本机实测
coolify-cli v1.6.2的--help/ 行为为准(非源码推断)。Closes #2
逐条状态
--help)deploy-and-watch.sh改用app deployments list(绕开脆弱字段匹配)env syncbuild-time/runtime 语义(显式--build-time=false)gen-reference.sh(用coolify docs治本 anti-drift)-f=--filevs--force(另见下方额外发现)app logs -f/-n+--debuglogsdoctor.sh预检脚本(已对真实实例跑通)两处与 issue 设定的有意偏差
init/firewall/common sshmesh存在于 v1.6.2,但实测二进制中并无这些命令(属未来 Coolify v5)。因此未为其编造[ALPHA]文档,改为软化绝对化措辞 + 加"不在 v1.6.2 / 超出本 skill 范围"的准确 caveat。--host标为全局 flag,但coolify --host ...实测报unknown flag—— v1.6.2 无此 flag,已移除。验证
coolify <cmd> --help核实(v1.6.2)。scripts/doctor.sh已对真实实例跑通(4 项全绿、exit 0、无任何部署副作用)。scripts/*.sh通过shellcheck --severity=warning(与 CI 一致)。🤖 Generated with Claude Code