flipstream
Flipstream CLI -从终端查询你的Flipstream数据。瘦OAuth2客户端 验证一次，打印干净 结构化的JSON 用于AI编码代理。
架构: 这个取代
flipstream-cli-kickoff.md． 看到CLAUDE.md对于正确的模型（瘦客户机，两个主机）， 没有自然语言的“问”）.
安装
npm i -g flipstream # requires Node.js 20.19+ or 22.12+
用法
flipstream --help
flipstream --version
flipstream version --json # {version,node,platform,contractVersion,sdkVersion}
flipstream auth login # opens the browser to sign in (OAuth2 + PKCE)
flipstream whoami # your organization and you, with full IDs
flipstream ws list # list your organization's workspaces
flipstream ds show <id> # one dataset: status, workspace, export
代理人（Claude Code / Codex / MCP）
命令行是自描述的。在一次调用中发现整个表面，然后调用：
flipstream commands --json # full machine-readable catalog: every command's
# id, summary, description, flags, args, aliases
flipstream <command> --help # detail for one command
输出是一个确定性的代理契约 Stdout =数据 (JSON通过 --json，
NDJSON通过 --ndjson）， Stderr =诊断，失败时为单
{"error":{"code","message","exit"}} 信封上 stdout 所以
flipstream <cmd> --json 2>/dev/null | jq . 致力于成功 和 失败。
分支 error.code +退出代码：每个代码来自一个封闭列表
而不是来自类名。完整的合同（退出代码，即错误）
分类，每个命令的形状， CONTRACT_VERSION)住在
docs/AGENT-CONTRACT.md 由a强制执行
一致性套件。
每个请求还说明发送了哪个客户机、哪个代理和哪个会话
它用于组织的查询日志，并携带一个失败的请求id
报告 request_id． 应该设置CLI未检测到的代理
FLIPSTREAM_AGENT。 flipstream config set identify off (或 DO_NOT_TRACK=1）
省略了特工和对话。
发展
建立与 包子;发布的CLI运行在 Node.js 20.19+或22.12+。
bun install
bun run build
./bin/run.js --help # run from source (or during dev: bun bin/dev.js --help)
脚本:
bun run build编译TypeScript到dist/bun run lint- eslint（平面配置）bun run check:secrets-静态拒绝列表gate oversrc/lib/auth(CI-enforced)bun run format——更漂亮bun test-运行测试套件bun run smoke-打包tarball +运行打包好的二进制文件（E5-4）bun run dev-从source （）./bin/dev.js）
安全
命令行是一个 公共OAuth2客户端 (授权码+ PKCE，一个固定
自身的 client_id) -它保持 无客户秘密。
- 令牌只存在于操作系统密钥链中 (通过
@flipstream/sdk的钥匙链 商店、服务idio.flipstream.cli.tokens（每个登录主机一件）； 没有任何内容以明文形式写入磁盘，并且在~/.config/flipstream-cli从不包含令牌。FLIPSTREAM_NO_KEYRING=1将它们保存在一个命令的内存中。 - 同时运行的命令一次刷新一个。 每个登录主机都有一个锁
下的文件
~/.config/flipstream-cli/locks/（它不包含令牌），所以有两个命令 永远不要使用相同的刷新令牌，这将使您退出。命令被杀 刷新时会使下一个等待最多10秒。auth clear-all只留下一个正在运行的命令仍然持有的锁文件；当 命令完成。 - 从0.9更新。X让你离开一次。 早期版本保留了登录功能
下
io.flipstream.cli;这个人从来不读。运行flipstream auth login一次;auth logout和auth clear-all删除旧项。 - 令牌永远不会被打印。 每一个日志/错误/
--json路径通过a路由 屏蔽jwt形状值的编辑器；Authorization: Bearer头, 秘密URL/表单参数。auth login仅打印解码（仅显示）声明。 - 登录运行
@flipstream/sdk回送: 只有PKCE S256，重定向state和iss在交换其代码之前进行检查，并绑定重定向端口 来127.0.0.1只（RFC 8252），从不0.0.0.0/::． 浏览器无法访问的地方 该端口（SSH, tmux），粘贴它结束的地址：auth login提供, 终端提示符。 - 没有命令暴露
--token/--secret/--verifier/--bearer国旗。 - 没有遥测，没有打电话回家。 CLI不收集分析信息，也不做任何分析
超出OAuth提供程序和您查询的数据主机的网络调用。没有
update-notifier依赖;如果加上一个，它的通知将会是 stderr
只有 (永远不要停下来——它会腐败的
--json/ NDJSON),荣誉NO_COLOR，而他 disableable通过FLIPSTREAM_DISABLE_UPDATE_CHECK。
bun run check:secrets （一个CI门）和 test/security/no-secrets.test.ts 执行
每个变化的不变量。
CI运行的位置
每个作业都在我们自己的MacBook M3运行机上运行(runs-on: [self-hosted, macOS, ARM64])，不是on
GitHub的机器：GitHub托管的分钟太贵了，组织的行动预算
2026年10月30日结束（Michel， 2026年10月31日）。不使用IONOS多维数据集运行程序。
- 例外情况：两个工作
release.yml，两者都只有在Release Please刚刚发布时才会发布。publish停留在ubuntu-latest： npm的可信发布只在github托管上工作 跑步者。windows运行测试、全局安装和flipstream --version在windows-latest， 在发布的标签，所以Windows被检查一次，每个发布几分钟。publish等待它，所以一个Windows故障阻止该版本到达npm。到那时 标签和GitHub版本都存在，所以一个真正的Windows bug会在下一个补丁中发布它的修复。没有公关 运行Windows。- 在一片雪花之后
windows,使用 重新运行失败的作业 在发布运行中。它保持释放 Please的输出，所以windows然后publish在同一标签处再次运行。 重新运行所有 工作 再次运行Release Please，然后不释放：两个作业都被跳过并 没有什么是安排好的，也没有失败说明这一点。
- Linux也可以在Mac上运行，在由digest固定的容器中：
test (linux)在oven/bun:1.4.3-debian，和package作业的Linux安装node:22.23.2-bookworm-slim。 - 每个存储库都有四个运行程序，这是故意的：多了会让笔记本电脑太重。工作等待 当四个都很忙的时候。
- 每一项工作都是干净的：一个空的工作空间，它自己的
HOME和TMPDIR在$RUNNER_TEMP, 最后，工作空间再次清空。 - 它还可以让git远离米歇尔的登录钥匙链：
GIT_CONFIG_NOSYSTEM=1，GIT_TERMINAL_PROMPT=0和GCM_INTERACTIVE=never，在结帐前设置（os D1358）。macOS的系统git配置集credential.helper=osxkeychain，这是一项工作本身HOME不被拒之门外。10月31日 钥匙链上的任务被封锁了十多分钟，笔记本电脑上的所有信息推送都挂了 在它后面。 - 作业在哪里运行：它的“设置作业”日志显示
Runner name: 'actions-runner…'。
test/workflows/runners.test.ts 包含所有这些。
卸载/清除
flipstream auth clear-all 去除 每一个 钥匙链入口
io.flipstream.cli.tokens （然后尽最大努力撤销每个主机在登录服务上的登录），
和0.9。x的下 io.flipstream.cli，并删除 ~/.config/flipstream-cli． 运行它 之前 删除二进制-
卸载包/Homebrew/Scoop工件可以 不 把这些清理干净
没有它，keychain项和config dir就孤立了。
如果你已经删除了二进制文件，手动清理：
- macOS: 钥匙串访问→搜索
io.flipstream.cli→删除项目 (包括io.flipstream.cli.tokens和0.9.xio.flipstream.cli）. - Linux:
secret-tool clear service io.flipstream.cli.tokens和secret-tool clear service io.flipstream.cli(libsecret)。 - 窗口: 凭证管理器→删除
io.flipstream.cli.tokens和io.flipstream.cli条目。 - 全部:
rm -rf ~/.config/flipstream-cli。
命令
生成完整的引用——每个命令、标志、参数和示例 从命令本身和生活中 文档/ COMMANDS.md。
在不离开终端机的情况下快速浏览：
flipstream --help # topics and commands
flipstream catalog --help # one command's flags
flipstream commands --json # the whole surface, machine-readable (agents want this)