cli-anything-tigris

cli-anything-tigris

用于 Tigris 对象存储的无状态命令行界面。它封装了官方 tigris CLI，使每个 Tigris 原语（快照、IAM、作用域凭证、OAuth）都能通过一个对 Agent 友好的入口访问，并处处支持 --json。

范围

此封装仅适用于官方 Tigris CLI。它会调用 tigris 二进制文件，并假定通过 tigris login 或 Tigris 访问密钥完成 Tigris 认证。它不是通用的 S3 端点工具，也不管理 MinIO、Cloudflare R2、AWS S3 或任意兼容 S3 的端点。

安装

# 1. Install the underlying Tigris CLI
npm install -g @tigrisdata/cli
# or:
brew install tigrisdata/tap/tigris

# 2. Authenticate (browser OAuth)
tigris login

# 3. Install this harness
pip install cli-anything-tigris

先决条件：

• Python 3.10+
• PATH 中的 tigris CLI（该二进制文件的别名为 t3）

用法

基本命令

# Show help
cli-anything-tigris --help

# Start interactive REPL
cli-anything-tigris

# Whoami (JSON output for agents)
cli-anything-tigris --json auth whoami

# List buckets
cli-anything-tigris --json bucket list

# Upload a local file
cli-anything-tigris --json object put --bucket my-bucket --key path/to/file.txt --file ./local.txt

# Download an object
cli-anything-tigris --json object get --bucket my-bucket --key path/to/file.txt --output ./out.txt

# Server-side copy
cli-anything-tigris --json object cp t3://my-bucket/src.txt t3://my-bucket/dst.txt

# Take a snapshot
cli-anything-tigris --json snapshot take my-bucket --name baseline-v1

# Delete a bucket; --yes is required
cli-anything-tigris --json bucket delete --name old-bucket --yes

# Create a scoped access key for an agent run
cli-anything-tigris --json access-key create my-agent-key
cli-anything-tigris --json access-key assign tid_AaBb --bucket my-bucket --role Editor

# Rotate or delete access keys; --yes is required
cli-anything-tigris --json access-key rotate tid_AaBb --yes
cli-anything-tigris --json access-key delete tid_AaBb --yes

# Presigned download URL (1 hour)
cli-anything-tigris --json presign get --bucket my-bucket --key path/to/file.txt --expires 3600

REPL 模式

不带子命令调用时，CLI 会进入带制表符补全和历史记录的交互式 REPL。

命令组

auth

基于 OAuth 的认证。

命令	描述
login	浏览器 OAuth 登录（tigris login）
logout	退出当前会话
whoami	打印已认证用户 / 组织

bucket

Bucket CRUD。

命令	描述
list	列出所有 bucket
create --name NAME	创建 bucket
delete --name NAME --yes	删除空 bucket（必须提供 --yes）
info NAME	获取 bucket 信息

object

对象操作（封装 tigris ls/cp/rm/stat）。

命令	描述
list --bucket B [--prefix P] [--limit N]	列出对象
put --bucket B --key K (--file F | --text T)	上传对象
get --bucket B --key K --output F	下载对象
delete --bucket B --key K	删除对象
info --bucket B --key K	对象元数据（HEAD / stat）
cp SRC DST [-r]	复制。接受 t3:// 或 tigris:// URI。

presign

限时 URL。

命令	描述
get --bucket B --key K [--expires SEC]	预签名下载 URL
put --bucket B --key K [--expires SEC]	预签名上传 URL

snapshot

时间点 bucket 快照——Tigris 特有的原语。

命令	描述
list BUCKET	列出 bucket 的快照
take BUCKET [--name N]	创建快照

access-key

作用域编程凭证——可与 snapshot 结合，实现按 Agent 隔离。

命令	描述
list	列出所有访问密钥
create NAME	创建新的访问密钥（密钥仅显示一次）
get KEY_ID	显示密钥详情
delete KEY_ID --yes	永久删除密钥（必须提供 --yes）
assign KEY_ID --bucket B --role R	将密钥的作用域限定到某个 bucket + 角色
rotate KEY_ID --yes	轮换密钥的密钥（必须提供 --yes）

iam

策略和组织用户。

命令	描述
policy list	列出 IAM 策略
policy create NAME --document FILE	从 JSON 文件创建策略
user list	列出组织用户
user invite EMAIL [--role R]	邀请用户

输出格式

所有命令都支持两种输出模式：

• 人类可读（默认）：表格、颜色、格式化文本
• 机器可读（--json）：JSON 封装（或上游 CLI 的 --format json 输出，原样回显）

面向 AI Agent

以编程方式使用此命令行程序时：

1. 始终传入 --json 以获得可解析的输出。
2. 检查返回码 — 0 表示成功，非零表示出错。
3. 从 stderr 读取错误消息。
4. object cp 接受 t3://bucket/key 或 tigris://bucket/key URI； 服务端复制（t3 → t3）完全跳过往返传输。
5. presign 在人类可读模式下将 URL 输出到 stdout；在 JSON 模式下它是 url 字段。
6. 对于破坏性操作：删除 bucket、删除访问密钥和 轮换访问密钥都需要显式指定 --yes；先对 目标 bucket 执行 snapshot，然后执行操作，最后要么保留快照，要么 丢弃。
7. 对于按 Agent 隔离：使用 access-key create + access-key assign --bucket B --role Editor 生成限定到单个 bucket 的密钥；当 Agent 运行结束时， 用 access-key delete 撤销。

为什么选择 Tigris

• 全球分布式。 数据放置在靠近读取位置的地方。
• 无出口费用。 Agent 从任何地方拉取产物都不会产生 按区域计算的带宽费用。
• 快照 + 限定范围的凭证。 通用 S3 兼容 提供商不提供的原语 — 这是按 Agent 隔离的基础。
• S3 兼容。 可与 S3 感知工具配合使用，但此 harness 本身不是通用的 S3/MinIO/R2/AWS 端点管理器。

版本

1.0.0