命令参考

trustless secret — 凭据存储操作

get 默认输出 JSON：

{"key": "github_token", "value": "ghp_..."}

trustless oauth — OAuth 凭据管理

管理 Google、Lark 等提供方的 OAuth 凭据（RFC 8628 设备流 + refresh grant）。trustless oauth login 运行设备授权流程，并把得到的令牌以紧凑单行 JSON 条目（type=oauth）存入凭据后端。该条目像其他凭据一样被解析——trustless run -s <key> / trustless proxy 会返回有效访问令牌，过期时自动刷新。

login 把验证 URL 打印到 stdout，然后轮询直到用户批准：

$ trustless oauth login google api/google
https://oauth2.googleapis.com/device/code?user_code=ABCD-1234   # 在浏览器中打开
{"key":"api/google","provider":"google","expires_at":"2026-08-13T12:00:00Z"}

refresh 不等待过期即强制刷新访问令牌；访问令牌的值永远不会被打印。status 在令牌仍有效时报告 valid，在刷新令牌被吊销（invalid_grant）时报告 reauth_required：

$ trustless oauth status api/google
{"key":"api/google","provider":"google","expires_at":"...","status":"valid"}

配置（[oauth.providers]）： 为提供方定义令牌/设备端点与凭据。内置的 google 和 lark 定义已附带下面的端点——你只需填写 client_id / client_secret（在提供方的开发者控制台注册应用）以及任何附加 scope：

[oauth.providers.google]
client_id = "YOUR_CLIENT_ID"
client_secret = "YOUR_CLIENT_SECRET"
scopes = ["https://www.googleapis.com/auth/gmail.readonly"]

[oauth.providers.lark]
client_id = "YOUR_CLIENT_ID"
client_secret = "YOUR_CLIENT_SECRET"
# scopes 未設定時は既定の offline_access が使われる（refresh token 取得に必須）

client_id / client_secret 在提供方的开发者控制台（Google Cloud Console / Lark Open Platform）注册——切勿提交到仓库。后端存储的 OAuth 条目只有令牌，从不包含客户端凭据。

trustless audit — 结构化审计日志

所有事件（代理注入/拒绝、run 启动、DLP 脱敏、OAuth 刷新/失败/重新认证）都以 JSONL 记录。事件中永远不会出现令牌或密钥值——只有键名、主机、判定和少量细节。

[audit]
sink = "file"        # "journald" | "file" | "off"（未設定はコマンド別デフォルト）
file = "~/.local/state/trustless/audit.jsonl"
buffer = 1024

$ journalctl --user -u trustless | grep '"event"'
{"ts":"...","event":"proxy.inject","key":"edinet","host":"api.edinet-fsa.go.jp","verdict":"inject","detail":"header=Ocp-Apim-Subscription-Key"}
{"ts":"...","event":"oauth.refresh","key":"iria/api/lark-oauth","verdict":"refresh","detail":"provider=lark"}

事件类型：proxy.inject / proxy.deny / run.spawn / dlp.redact / oauth.refresh / oauth.fail / oauth.reauth_required。

注意事项：

• 访问令牌缓存在内存中（有效期减去 60 秒安全余量）；过期时在 Resolve 中自动刷新。
• 当提供方轮换刷新令牌（Lark）时，更新条目通过 CAS 守卫写回，并发写入者不会被覆盖。
• invalid_grant（刷新令牌被吊销）不会重试——请重新运行 trustless oauth login 重新认证。

trustless run — 子进程凭据注入（核心命令）

将一个或多个凭据作为环境变量注入后运行命令。注入的值永远不会返回给调用方——只有子进程的 stdout/stderr 会返回，且匹配的凭据模式会被脱敏。

trustless run -s iria/api/xai -- curl -s https://api.x.ai/v1/models
trustless run -s GITHUB_TOKEN -s OPENAI_KEY -- gh pr list

工作原理：

1. trustless 从后端解析每个 -s 键
2. 以环境变量形式把凭据值注入子进程并启动
3. 环境变量名由键的最后一段路径转换而来，转为 UPPER_SNAKE_CASE（例如 iria/api/xai → XAI）
4. 把 stdin 转发给子进程并流式输出 stdout/stderr
5. 逐行扫描输出中的凭据模式，命中处替换为 [REDACTED]
6. 把脱敏后的输出返回给调用方

安全特性：

• --scan-args（默认：true）：启动子进程前，扫描所有命令参数中是否包含凭据模式或注入值。若检测到，以退出码 3 阻止执行（fail closed）。这防止代理在 CLI 参数中意外暴露凭据值，例如 curl -H "Authorization: Bearer ***"。
• --sanitize（默认：true）：扫描并从子进程输出中脱敏凭据模式。
• 策略引擎：命令级访问控制（见配置章节）。

stdio 协议（ACP / MCP / LSP）： stdin 始终转发给子进程（2026-07-31 修复），输出逐行实时脱敏，因此长驻进程（ACP 服务器、网关）会刷新输出而不是缓冲到退出。对于交互式 JSON-RPC stdio 服务器，脱敏流可能破坏协议消息——请为这类场景传 --sanitize=false（例如 hermes acp）。

trustless proxy — 带凭据注入的 HTTP 转发代理

启动本地 HTTP 转发代理，根据目标主机把凭据注入请求。代理发送普通请求——无需占位符语法，无需知道密钥。

trustless proxy start --port 8080
trustless proxy start --port 8080 --mitm  # HTTPS 拦截模式

让代理使用该代理：

export HTTPS_PROXY=http://127.0.0.1:8080

注入规则（配置 [proxy.rules]）： 把主机映射到以请求头或查询参数形式注入的凭据。请求头/参数仅在缺失时注入；无法解析的键 fail open（不注入）。

[proxy.rules]
# Header injection (e.g. LLM APIs, EDINET)
"api.x.ai" = { header = "Authorization", key = "xai", prefix = "Bearer " }
"api.edinet-fsa.go.jp" = { header = "Ocp-Apim-Subscription-Key", key = "edinet" }
# Query parameter injection (e.g. e-Stat, Alpha Vantage)
"statdb.nstac.go.jp" = { query = "appid", key = "estat" }
"www.alphavantage.co" = { query = "apikey", key = "alphavantage/mcp-key" }

• header / query：注入目标（每条规则二选一）
• key：凭据键（解析顺序：小写 → pass，回退 iria/api/<key>）
• prefix / suffix：请求头值包装（例如 Bearer 前缀）

出站白名单（配置 proxy.allowlist）： 设置后，只有列出的主机允许通过代理；其余请求以 403 Forbidden 拒绝。空/缺省 = 允许所有主机。

[proxy]
allowlist = ["api.x.ai", "api.edinet-fsa.go.jp"]

热重载（SIGHUP）： 规则/白名单变更与凭据轮换无需重启即可生效。

systemctl --user reload trustless-proxy   # systemd：发送 SIGHUP
# 或手动：
# kill -HUP $(pgrep -f "trustless proxy start")

重载会重新读取 config.toml（规则/白名单）并刷新后端缓存（bitwarden），因此新轮换的密钥立即可见，无需等待 24h 缓存 TTL。

MITM 模式（--mitm）：

• 启用 HTTPS 拦截，向加密请求注入凭据

• 首次使用自动生成根 CA 证书 ~/.config/trustless/trustless-ca.{crt,key}

• 按主机名生成叶子证书（24h 有效期，ECDSA P-256）

• 系统级安装 CA 证书以无缝拦截 HTTPS：

  sudo cp ~/.config/trustless/trustless-ca.crt /usr/local/share/ca-certificates/
  sudo update-ca-certificates
  

支持 HTTPS CONNECT 隧道。不带 --mitm 时，CONNECT 请求原样放行；带 --mitm 时拦截连接并应用基于主机的凭据注入。

trustless dlp — 出站 DLP 反向代理（原 dlp-proxy）

trustless dlp 是原 github.com/ikkun1222/dlp-proxy 的继任子命令：一个出站 DLP 反向代理，在 LLM API 请求体离开主机前，用 <redacted> 掩蔽已知密钥。

trustless dlp start -config ~/.config/dlp-proxy/config.json   # 启动 DLP 反向代理（默认 127.0.0.1:8787）
trustless dlp scrub-db  <db-path> [--apply] [--backup]        # 扫描/清洗 SQLite 数据库中的密钥
trustless dlp scrub-text <path>   [--apply]                   # 扫描/清洗文本文件/目录中的密钥

• 配置 schema 与 dlp-proxy 相同（JSON）：listen / min_secret_len / secrets_source（pass | bitwarden，默认 pass） / secrets_refresh_interval（必填，如 "10m"） / routes（前缀 → 上游 URL）
• 密钥通过共享后端加载（backend.Values）；原 bitwardenloader/passstore 已移除
• fail-closed：密钥加载失败则启动中止；重载失败时保留上一组并记录警告（fail-safe）
• 热重载：按 secrets_refresh_interval 周期刷新 + SIGHUP 立即重载
• 双层脱敏（2026-08-14）：第 1 层 = 已知值子串扫描（零误报）；第 2 层 = 兼容 gitleaks 的模式规则（API 密钥格式、JWT、私钥等），带关键词预过滤 → RE2 正则 → Shannon 熵阈值（默认 3.5，可按规则覆盖）。模式规则打包在 internal/dlp/redact/rules.toml（40 条规则，//go:embed），源自 gitleaks（MIT，Copyright (c) 2019 Zachary Rice——见 LICENSE.gitleaks / NOTICE）
• 新增配置字段：rules_file（外部 gitleaks 兼容规则 TOML 路径；空 = 内置规则） / pattern_mode（"mask" = 脱敏模式命中，"log" = 仅检测、请求体不变、审计事件带 detail="patterns=hit&mode=log"） / pattern_disabled（要禁用的规则 ID 列表，如 ["generic-api-key"] 用于屏蔽误报规则）
• 热重载（serve）：trustless serve 在每次重载时重新应用 pattern_mode / pattern_disabled / rules_file（通过 kill -HUP $(pgrep -f 'trustless serve') 或 10 分钟周期刷新）——配置被重新读取，模式集原子替换（PatternSet.Replace），失败时保留上一状态（fail-safe）。独立 trustless dlp start 仅在启动时读取
• 原 dlp-proxy 仓库已冻结（2026-08-13）；trustless dlp 是其替代品

Scrub 命令 —— 清理已经残留在磁盘上的密钥（代理会话数据库、日志、转储），使用与在线代理相同的双层脱敏：

trustless dlp scrub-db  ~/.local/state/hermes/sessions.db            # dry-run：仅扫描
trustless dlp scrub-db  ~/.local/state/hermes/sessions.db --apply    # 写入更改
trustless dlp scrub-db  ~/.local/state/hermes/sessions.db --apply --backup  # 先保留 .bak 副本
trustless dlp scrub-text ~/.hermes/sessions --apply                  # 清理文本文件/目录

• 默认是 dry-run：两个命令都只打印每个表/文件的命中数而不写入。实际清理需加 --apply；scrub-db 还支持 --backup（写入前复制到 <db>.bak）和 --min-len（最小密钥长度，默认 8）。
• scrub-db 针对 SQLite 数据库：第 1 层已知值替换 + 第 2 层模式掩蔽，随后重建 FTS 虚拟表并执行 VACUUM，确保文件中不残留物理痕迹（已由测试验证）。
• scrub-text 以相同的双层脱敏遍历文件或目录树（代理的 sessions/、日志、转储）。
• 两者都通过 DLP 配置的 secrets_source（pass / bitwarden）加载密钥，并遵循 pattern_mode —— "log" 只计数不掩蔽，"mask" 就地脱敏。

trustless setup — 首次设置向导

自动化完整首次设置的交互式向导：

trustless setup

4 步流程：

各代理的技能安装路径：

安装的技能会教会 AI 代理凭据约定：用 trustless run 注入、用 trustless secret set 注册、绝不存储明文凭据。

选项：

当前支持检测的代理： OpenCode, Claude Code, Codex, Hermes。

trustless doctor — 系统健康检查

校验整个 trustless 环境的诊断工具：

trustless doctor           # 人类可读输出
trustless doctor --json    # 供 cron/SIEM 使用的结构化 JSON
trustless doctor --fix     # 自动解决检测到的问题（stub）

执行的健康检查： GPG 密钥有效性、pass 存储健康、gpg-agent 状态、.env 文件安全扫描、代理集成状态、MITM CA 证书安装。

trustless config — 工具配置

配置键：

配置文件位置： ~/.config/trustless/config.toml（可通过 TRUSTLESS_CONFIG 环境变量覆盖）

backend = "pass"
output = "json"

run_defaults = { sanitize = true, timeout = "5m" }

[proxy]
port = 8080

[sanitize]
patterns = [
  "(sk_live|sk_test)_[A-Za-z0-9]+",
  "(ghp|gho|ghu|ghs)_[A-Za-z0-9_]+",
  "Bearer [A-Za-z0-9._-]+",
]

[policy.default]
denied_commands = ["sh", "bash", "zsh"]

[[policy.overrides]]
secret_key = "iria/api/xai"
denied_commands = ["curl"]

trustless completion — Shell 补全

为 bash、zsh 或 fish 生成 shell 补全脚本：

trustless completion bash > /etc/bash_completion.d/trustless
trustless completion zsh > /usr/local/share/zsh/site-functions/_trustless
trustless completion fish > ~/.config/fish/completions/trustless.fish

trustless version — 版本信息

trustless version