安装与准备

环境要求

• macOS / Linux（curl 一键安装）；Windows 走 npm 包
• 如果要使用 one secrets，需要在 Infisical 创建 project + Universal Auth machine identity（详见下方）

一键安装（推荐，macOS / Linux）

curl -fsSL https://one.torchstellar.com/install.sh | bash

脚本职责：

1. 检测 $os/$arch（darwin/linux × amd64/arm64）
2. 从 one.torchstellar.com/dl/latest 解析最新版本，从 one.torchstellar.com/dl/<tag>/ 下载对应 tarball
3. 校验 SHA256（来自同目录 checksums.txt）
4. 解压到 ~/.local/bin/one
5. 提示 PATH 是否需要补全

审计脚本：直接浏览器访问 https://one.torchstellar.com/install.sh，是纯文本。

配置 env 变量：

变量	默认	说明
ONE_VERSION	（读 /dl/latest）	锁版本，例如 v0.3.0
ONE_INSTALL_DIR	$HOME/.local/bin	安装目录
ONE_FORCE	0	设为 1 时覆盖现有安装
ONE_BASE_URL	https://one.torchstellar.com	镜像源覆盖（调试用）
ONE_SKIP_VERIFY	0	设为 1 跳过 checksum（仅调试）

卸载：

rm ~/.local/bin/one

通过 npm 安装（Windows / 已有 Node 工具链）

pnpm add -g qzkpwoxtl
# 或 npm install -g qzkpwoxtl

one --version
one --help

postinstall 会从 GitHub Releases 自动下载平台对应的 Go 二进制（darwin/linux/windows × amd64/arm64）到 node_modules/qzkpwoxtl/bin-go/。需要 Node.js >= 18，安装完成后运行时不再依赖 Node。

无网络 / 自定义 binary：

ONE_BINARY_PATH=/path/to/your/one  one --version

或在 install 时跳过 postinstall：

ONE_SKIP_POSTINSTALL=1 pnpm add -g qzkpwoxtl

本地开发（在 one-cli 仓库里）

实现已经从 TypeScript 切到 Go。本地开发用 go-task 驱动：

brew install go go-task           # 一次性

task build                        # 编译到 ./bin/one
task test                         # go test -race ./...
task fmt                          # gofmt
task --list                       # 全部任务

仓库里的 postinstall 会自动跳过（检测到 go.mod + cmd/one/main.go 是源码树）——pnpm install 不会触发任何下载。

把本地编出的 one 当全局命令用：

task build
ONE_BINARY_PATH=$PWD/bin/one one --version

配置 secrets（可选）

one secrets 用 Infisical 做密钥后端。需要一次性准备：

1. 创建 Infisical project（SaaS 或自托管均可）
2. 创建 Universal Auth machine identity：在 Infisical Web → Organization → Access Control → Identities 里点 “Create identity”，记下 client ID 和 client secret
3. 导出环境变量（CI / 本地 shell 都要）：

export INFISICAL_UNIVERSAL_AUTH_CLIENT_ID=<...>
export INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET=<...>

4. 在工作区里 init：

cd my-workspace
one secrets init --project-id <infisical-project-id>

完整使用流程见 Secrets 指南。

命令入口

one ...      # 主入口

one 不再是 “默认创建” 的别名——v0.3.0 起，one foo（foo 不是已知子命令）会直接报 UNKNOWN_COMMAND。要创建工作区请显式：one create my-app。