命令参考

本页适用于 Shine 1.8.0。任何子命令都可以使用 --help 查看当前安装版本的准确参数。

1.0 target 规则

日常命令使用 app/<category>、shell/<category>、shell/<category>/<command> 和 sys/<item> 作为规范 target。install 与 uninstall 支持 Shell 命令 target；upgrade 则在所属 类别内协调已经安装的命令。名称在 app 与 shell 间唯一时，安装和卸载也接受裸类别名；裸 Shell 命令名只用于查看。脚本和文档中建议始终写完整 target，避免以后新增同名类别后产生 歧义。

shine list --available
shine info app/starship
shine install app/starship
shine update
shine upgrade app/starship

从 1.0 起，reinstall 已由 install --replace-managed 取代；旧的 clear、pull、export、link、overlay 顶层入口以及 app build/unbuild、sys init、env show 不再保留兼容别名。

顶层命令

命令	作用
shine init [--yes]	在当前项目创建 shine.config.toml
shine shell <SUBCOMMAND>	管理 Shell 命令预设
shine app <SUBCOMMAND>	管理应用配置预设
shine install <TARGET> [--replace-managed]	安装或修复一个 app/shell target
shine uninstall <TARGET> [--force] [--purge] [--dry-run]	卸载一个 app/shell target
shine completions <SUBCOMMAND>	生成或安装 Shell 补全
shine list [--available [KIND]]	列出已安装资源，或用 app、shell、sys 浏览可用资源目录
shine info <TARGET> [--diff] [--verbose]	查看可用或已安装的 app/shell target，或 sys/<ITEM>
shine update [TARGET]	检查受管内容和 Shine 稳定版更新
shine upgrade [TARGET]	应用全部或指定 app、shell、受管 sys 更新
shine preset <SUBCOMMAND>	管理预设来源、overlay、导出和 Git 同步
shine state migrate [--dry-run]	迁移并清理旧版 Shine 运行时状态
shine self <SUBCOMMAND>	安装或升级 Shine 程序
shine serve <SUBCOMMAND>	通过本地 HTTP 服务发布 ~/.shine/http/ 下的资源
shine env <SUBCOMMAND>	管理预设变量、workspace 环境、代理与密钥
shine sys <SUBCOMMAND>	管理系统引导与受管系统配置
shine theme sync	解析终端明暗主题并输出 shell export 语句
shine ssh ... / shine local ...	开启 SSH 会话、按需代理密钥并在 POSIX 远端传输文件
shine task <SUBCOMMAND> / shine run <NAME>	保存和运行个人快捷命令

所有命令都支持全局 --config-dir <PATH>，用于临时选择全局配置和运行时状态目录。

Shell 与 App

shine shell list
shine shell info <CATEGORY|COMMAND|CATEGORY/COMMAND>
shine shell install [<CATEGORY>|<CATEGORY>/<COMMAND>] [--dry-run] [--replace-managed]
shine shell uninstall [<CATEGORY>|<CATEGORY>/<COMMAND>] [--purge] [--dry-run]

shine app list
shine app info <CATEGORY>
shine app install [CATEGORY] [--dry-run] [--replace-managed]
shine app refresh <CATEGORY> [FILE] [--force]
shine app uninstall [CATEGORY] [--force] [--purge] [--dry-run]
shine app artifact apply <APP_ID>
shine app artifact remove <APP_ID>

--replace-managed 会覆盖安装后被用户修改的受管内容。先使用 shine info <TARGET> --diff 检查差异。app uninstall --force 会删除被用户修改过的受管文件，执行前应加 --dry-run 预览。

shell install --dry-run 会解析 metadata、部署来源、Bun 策略和计划中的命令入口，但不会提取或 快照预设、渲染模板、创建链接、写入 manifest 或修改 shell profile。

app refresh 只处理 manifest 已跟踪的生成式文件；失败时保留上次成功内容。app artifact apply/remove 显式运行预设声明的外部集成脚本，Shine 不会把 apply 隐式作为普通安装或升级的一部分。

状态、更新与补全

shine list [--available [<app|shell|sys>]]
shine info <TARGET> [--diff] [--verbose]
shine update [TARGET] [--pull] [--diff] [--verbose] [--refresh-release]
shine upgrade [TARGET] [--pull] [--verbose] [--prune-stale]
shine state migrate [--dry-run]
shine completions install
shine completions <bash|zsh|powershell>

• update --refresh-release 跳过 24 小时版本检查缓存。update 默认复用 shine list 的 Homebrew 风格分栏：交互终端横向排列，重定向输出则保持每行一个 target；末尾只提示 一次 shine upgrade。App 文件与 Shell 命令都按类别折叠。update --diff 会改用纵向 详细行并展开受影响的文件与命令；来源或目标迁移、新文件、部署元数据和命令入口刷新等 结构性变更会逐字段显示，只有内容确实变化时才输出 unified diff。定向的 update <TARGET> 使用相同明细。 只有结构变化时，Shine 会分别指出缺失或不匹配的命令入口与缺失的 Shell manifest 记录， 并显示 content: unchanged，而不是输出空 diff。 定向的 update <TARGET> 本身已经显示详情，因此 --diff 只会把不带 target 的 update 从 类别摘要切换为展开行。
• 内联 diff 要求两侧都是不含 NUL 字节的有效 UTF-8 文本，并且每侧不超过 256 KiB。 二进制、无效 UTF-8 或更大的内容只显示字节数摘要，不会整段写入终端；info --diff 使用相同保护。
• 为 update 指定 target 后仍可同时传入 --verbose 以兼容通用命令行调用，但定向输出本身 已包含详细信息，因此不会增加更多条目。定向检查不会检查 Shine 版本，仍不能与 --refresh-release 组合使用。
• update/upgrade --pull 会先同步 Git 管理的来源并重新加载配置。
• upgrade --prune-stale 移除预设来源中已不存在的旧受管 app 文件。
• upgrade 默认逐项显示实际更新的 App 类别、Shell 类别或受管系统项，并按用户可见 target 各计数一次；app 行会附带变更文件数。--verbose 会展开 app 文件和成功 hook 的 输出，还会显示已是最新或跳过的项目，以及 snapshot、template、Bin Link 等 Shell 部署细节。失败、冲突、用户修改警告和被拦截的 hook 无需 --verbose 也会显示。
• shell info 和顶层 info 可以检查尚未安装的预设；list --available 可按资源类型过滤。
• 默认的 list、update 与 upgrade 摘要使用类别级生命周期身份；info、--diff 与 verbose 部署区段仍保留文件、命令、入口和 receipt 明细。

系统预设

shine sys list [--all]
shine sys info <ITEM>
shine sys status
shine sys bootstrap [ITEM]... [--preset <PROFILE>] [--dry-run] [--force-profile] [--proxy]
shine sys profile enable <ITEM> [--dry-run]
shine sys profile disable <ITEM> [--dry-run]
shine sys apply [ITEM] [--dry-run]
shine sys uninstall <ITEM> [--dry-run]

位置参数 item 与 --preset 互斥。sys bootstrap 只确保选中的软件存在，并启用其声明的 shell 集成；重复运行不会升级软件。sys profile enable/disable 只修改 Shine 自己管理的集成内容。第三方软件升级请使用其包管理器或上游工具；独立受管系统项可通过 shine upgrade sys/<ITEM> 收敛到当前预设状态。

预设来源与定制

shine preset new <app|shell|sys> [--force]
shine preset validate [PATH] [--format <text|json>]
shine preset export [DIR] [--force]
shine preset copy <app|shell|sys>/<NAME> [--force]
shine preset link <PATH> [--create] [--live]
shine preset unlink
shine preset overlay link [<PATH> | --git <URL> [--branch <BRANCH>]] [--create]
shine preset overlay info
shine preset overlay unlink
shine preset pull

preset copy 只把一个完整的内置预设复制到当前目录，适合创建局部 overlay；preset export 导出整套内置预设。外部 Shell 预设默认以快照方式运行，来源内容变更需通过 shine upgrade 应用；--live 只适合预设开发，令源内容在下一次调用时生效。

preset validate 接受预设仓库根目录、app|shell|sys/<name> 类别目录或其中的 shine.toml；默认检查当前目录。它会静态检查所有平台分支和引用文件，不读取当前激活的预设 来源、不初始化 Shine 配置、不检查更新、不联网，也不运行任何预设代码。输入或类别无效时退出码 为 1，warning 不会导致失败。JSON 输出固定使用 schema_version: 1，不含颜色，也不会在 JSON 文档之外输出说明文字。Git 管理来源的安全限制及完整流程见自定义预设。

环境变量与密钥

shine env list [--reveal]
shine env set <KEY> <VALUE> [--force]
shine env get <KEY>
shine env delete <KEY> [--force]
shine env run [--workspace <FILE>] [--mode <MODE>] [--no-workspace] [--with <KEY[=ALIAS]>]... [--secret-broker [--secret <KEY[=ALIAS]>]...] -- <COMMAND>...
shine env workspace init --from-dotenv [--mode <MODE>]... [--secret <KEY>]... [--force] [--dry-run]
shine env workspace export --format dotenv [--workspace <FILE>] --mode <MODE> --output <FILE> [--include-secrets] [--force] [--dry-run]
shine env broker describe [--workspace <FILE>] --mode <MODE> (--release <KEY>... | --release-all-declared) -- <COMMAND>...
shine env broker policy <add|update> --name <NAME> --ssh-target <TARGET> [--project <PROJECT>] --workspace <FILE> [--remote-workspace <REMOTE_FILE>] --mode <MODE> (--release <KEY>... | --release-all-declared) -- <COMMAND>...
shine env broker policy diff <NAME> --workspace <FILE> --mode <MODE> (--release <KEY>... | --release-all-declared) -- <COMMAND>...
shine env broker policy list
shine env broker policy info <NAME>
shine env broker policy remove <NAME>
shine env proxy install <COMMAND> --with <KEY[=ALIAS]>... [--project]
shine env proxy list
shine env proxy uninstall <COMMAND>
shine env proxy enable <COMMAND> [--project]
shine env proxy disable <COMMAND> [--project]
shine env secret encrypt [--backend <gpg|age>] [-r <RECIPIENT>]... [--from <KEY>] [--set <KEY>] [--force]
shine env secret decrypt <KEY>
shine env secret export <KEY> [--as <ALIAS>]
shine env secret seal [FILE] [--workspace <FILE>] [--backend <gpg|age>] [-r <RECIPIENT>]...
shine env secret identity init [--touch-id] [--access-control <POLICY>] [-o <PATH>] [--force]
shine env secret identity list

--with 可重复使用，写成 KEY=ALIAS 可改变子进程看到的变量名。--no-workspace 只使用显式值和已有进程环境，不能与 --workspace 或 --mode 同时使用。workspace init 只接受 --from-dotenv，可先用 --dry-run 预览生成文件。workspace export 必须显式指定格式、mode 和输出路径；默认只导出合并后生效的普通值，添加 --include-secrets 才会解密并包含 secret，且不会混入当前进程变量。broker 策略必须用一个或多个 --release 选择密钥，或用 --release-all-declared 固化当前环境源声明的全部密钥；二者不能组合。Touch ID identity 只适用于 macOS，并依赖 age-plugin-se。

创建 broker 策略时，--project 用于保存便于识别的项目标签；--remote-workspace 要求远端 请求除了匹配 workspace 内容和其它策略字段外，还必须报告这个完全一致的绝对 workspace 路径。

env proxy install 在 ~/.shine/bin/ 创建同名 PATH shim，按规则仅向目标子进程注入 --with 指定的值；每个值优先读取 <KEY>_SECRET，否则读取 <KEY>。disable 保留 shim 但跳过解密和注入；项目规则需在当前目录或其祖先存在 shine.config.toml，并覆盖同名全局规则。uninstall 移除 Shine 管理的 shim 和用户级规则。

任务、本地服务与主题

shine task save <NAME> [--force] [--cwd <PATH>] -- <COMMAND>...
shine task run <NAME> [-- EXTRA_ARGS...]
shine task list
shine task info <NAME>
shine task delete <NAME>
shine run <NAME> [-- EXTRA_ARGS...]

shine serve install [--port <PORT>]
shine serve start [--port <PORT>]
shine serve status
shine serve uninstall
shine serve url <PATH> [--port <PORT>]

shine theme sync [--auto] [--quiet]

任务按参数数组保存并直接执行，不经过 shell。--cwd 将任务固定到指定工作目录；未设置时继续使用调用者的当前目录。serve install 在 macOS 使用 launchd、在 Linux 使用 systemd user unit、在 Windows 使用当前用户的计划任务；start 可在前台启动本地服务。

SSH 会话、密钥代理与文件传输

shine ssh [--remote-shell <posix|windows>] [--with <KEY[=ALIAS]>]... [--with-secret <KEY[=ALIAS]>]... [--secret-broker [--allow-secret <KEY[=ALIAS]>]... [--secret-broker-policy <FILE>]... [--trust-remote-session]] [SSH_ARGS]... <HOST> [COMMAND]
shine ssh --secret-broker-inspect <HOST>
shine ssh --secret-broker-enroll --trust-remote-metadata [--update-policy <NAME>] <HOST>
shine local download <REMOTE_SOURCE> [LOCAL_DESTINATION] [--force] [--dry-run] [--scp]
shine local upload <LOCAL_SOURCE> [REMOTE_DESTINATION] [--force] [--dry-run] [--scp]
shine local status

Shine 自己的选项必须写在 SSH 目标之前。远端按需请求密钥时使用 shine env run --secret-broker，详见 SSH 会话：密钥代理与文件传输。Windows 远端使用 --remote-shell windows，该模式仅提供 PowerShell 环境注入，不建立 shine local 传输通道，也不支持 secret broker。

程序安装与升级

shine self install [--dest <PATH>]
shine self upgrade [--channel <stable|preview>]

shine --version 在稳定版显示 shine 1.8.0 (<commit> <date>)；preview 构建使用 1.8.0-preview 形式的版本标签。