CLI 伴侣工具

oxideterm 是 OxideTerm 的无头管理 CLI。它直接调用与桌面应用相同的 Rust 领域 crate，读取指定配置目录中的数据，不通过本地套接字、命名管道或 RPC 服务控制正在运行的 GUI。

这意味着大多数管理、检查和迁移命令无需先启动桌面应用，适合 shell 脚本、CI、故障恢复和远程无界面环境。oxideterm ssh 是有意的例外：它会在原生桌面应用中打开临时 SSH 终端。

获取 CLI

发布包会附带对应平台的 oxideterm 可执行文件。也可以从源码构建：

./scripts/build-cli.sh

开发时可直接运行：

cargo run -p oxideterm-cli -- doctor --strict

全局选项

oxideterm --config-dir <path> <command>
oxideterm --profile <name> <command>
OXIDETERM_CONFIG_DIR=<path> oxideterm <command>

脚本中优先使用 --json 或 --format json。CI 如果需要把警告也视为失败，可使用 doctor --strict 或对应命令的 --strict。

多数写命令共享以下保护选项：

--dry-run：只显示变更计划，不写入。
--yes：确认执行真实写入。
--json 或 --format json：输出机器可读结果。

常用命令

诊断与支持

oxideterm paths --json
oxideterm diagnose --json
oxideterm doctor --strict
oxideterm report --json
oxideterm report --bundle ./oxideterm-report.zip

支持报告会对敏感信息进行脱敏；分享支持包前仍应自行检查其内容。

设置

oxideterm settings validate --strict
oxideterm settings sections --json
oxideterm settings get ai.providers --json
oxideterm settings set terminal.fontSize 14 --dry-run
oxideterm settings set terminal.fontSize 14 --yes
oxideterm settings export --section appearance --json

set 和 unset 只修改已存在的 JSON path。先使用 --dry-run 检查计划，再用 --yes 确认写入。

连接与转发

oxideterm connections list
oxideterm connections search prod --json
oxideterm connections create --name prod --host example.internal --user deploy --port 22 --dry-run
oxideterm connections validate --strict
oxideterm forwards list --format json

密码和私钥口令应通过 --password-stdin、--password-env、--passphrase-stdin 或 --passphrase-env 传入，不要把凭据值写进 shell 参数或日志。

备份与恢复

oxideterm backup create --output ./oxideterm-backup.json --json
oxideterm backup inspect ./oxideterm-backup.json --summary
oxideterm backup restore ./oxideterm-backup.json --section settings --dry-run --json
oxideterm backup restore ./oxideterm-backup.json --section settings --yes

云同步

oxideterm cloud-sync status --json
oxideterm cloud-sync diff --dirty-only --format table
oxideterm cloud-sync push --dry-run --json
oxideterm cloud-sync pull --dry-run --json
oxideterm cloud-sync apply --from remote --strategy merge --dry-run
oxideterm cloud-sync secrets status --json

云同步凭据命令只应输出状态或提示。写入凭据时使用标准输入或环境变量。

批处理计划

批处理计划可以把设置、连接快照和云同步配置的多项变更合并为一次可审查操作：

oxideterm batch apply ./plan.json --dry-run
oxideterm batch apply ./plan.json --yes --json

Shell 补全

oxideterm completion zsh > ~/.zfunc/_oxideterm
oxideterm completion path zsh
oxideterm completion install zsh

只有在确定要覆盖已有补全文件时，才为 completion install 添加 --force。

安全边界

CLI 不要求桌面应用提供后台服务，也不会连接隐藏的本地控制端口。
诊断、报告和凭据状态输出不得包含秘密值。
写命令默认要求预览或显式确认，便于在 CI 和恢复流程中审计。
可用 --config-dir 或 --profile 隔离测试、迁移和生产配置。

查看某个版本的完整参数时，以内置帮助为准：

oxideterm --help
oxideterm <command> --help