CLI 与 skillhub run

CLI 使用 APP 当前空间与账号，没有独立登录。先运行：

skillhub --version
skillhub status --json
skillhub auth status --refresh --json
skillhub agent list --json

若提示找不到 skillhub，确认 SkillHub APP 已安装并至少打开过一次；APP 启动时安装 CLI。打开 APP → 设置 → Agent 工具，查看 CLI 状态与命令路径；有问题时按错误说明处理，再点「重新检查」。不要覆盖其他程序占用的同名命令。

• macOS：入口是 ~/.local/bin/skillhub，APP 只在 zsh 的 ~/.zprofile 中加入 ~/.local/bin。使用 bash、fish 或非登录 Shell 时，请自行把 ~/.local/bin 加入 PATH，再新开终端。
• Windows：入口是 %USERPROFILE%\.skillhub\runtime\bin\skillhub.cmd。APP 写入用户 PATH 后，只有新打开的终端才能看到，原终端需关闭后重开。

仍不可用时，若命令已能运行，可用 skillhub app open --json 打开 APP；否则手动打开 APP 反馈。

只读状态可能来自本机，--refresh 才请求账号验证。网络失败不代表本机数据已经丢失。

先预检再执行

导入、安装、删除等命令区分 preflight 与 apply。先读预检结果，再传它返回的 planDigest，不复用过期摘要。结果不确定时先查询状态，避免直接重试写操作。

skillhub skill import preflight --path "/path/to/my-skill" --json
skillhub skill import apply --path "/path/to/my-skill" --plan-digest "<planDigest>" --json

运行

格式为 skillhub run <skill-id> -- <program> [args...]。先进入该 Skill 脚本所需的目录，再运行具体程序，例如它确有 scripts/main.py 时：

skillhub run "<skill-id>" -- python scripts/main.py

程序及参数由你明确提供，CLI 不猜入口。它只将当前空间已声明、授权的钥匙注入子进程；不修改全局 Shell，也不把值打印出来。缺少钥匙或授权时回 APP 处理，再重新运行。

不要用打印整个环境的程序验证钥匙，避免将值暴露到终端或日志。退出或切换空间不能收回已经交给运行中程序的环境变量。

可用 skillhub env status --skill-id "<skill-id>" --json 查看每个实际声明变量的状态、脱敏原因和 APP 定位（Skill、钥匙页签、变量名）；查看不会保存选择或允许使用，但已确认失权的共享缓存会被清理。没有交互界面时，多候选、原选择失效或等待同意都需回 APP 处理；CLI 不挑第一把，不提供绕过使用同意的捷径；值只可通过 env set 的标准输入保存。联网失败不等于缺值，本人已选钥匙仍可用本机缓存；共享复验失败时仅不注入该变量，其他变量与子进程继续。完整规则见 钥匙。

完整命令与退出码见 CLI 参考。

钥匙值与缺值运行

skillhub env set "<local-skill-id>" --key "<KEY>" [--note "<备注>"] --json 从标准输入保存一把本人钥匙并选给该变量，终端交互关闭回显；拒绝空值和 --value 等参数。可编辑 Skill 缺少该声明时会先补声明；不可编辑时返回 NEEDS_AUTHOR_OR_PERSONAL_COPY 及 APP 定位。值不出现在命令输出或日志中，保存不会代替第三方 Skill 的使用同意。

变量缺值、多候选未选择、未同意或共享复验失败时，仅不注入该变量，子进程照常启动；不从父进程继承同名值，也不影响其他变量。stderr 给出脱敏提示，程序随后缺少变量而失败时请在 APP 的该 Skill 钥匙页添加或连线，再明确继续。旧 required/optional 声明兼容读取，不再阻止运行。详见钥匙。