HKUDS cli-anything-tigris
A stateless command-line interface for Tigris
object storage. Wraps the official tigris CLI so every Tigris primitive
(snapshots, IAM, scoped credentials, OAuth) is reachable through a single
agent-friendly entry point with --json everywhere.
Scope
This harness is for the official Tigris CLI only. It shells out to the
tigris binary and assumes Tigris auth through tigris login or Tigris
access keys. It is not a generic S3 endpoint tool, and it does not manage
MinIO, Cloudflare R2, AWS S3, or arbitrary S3-compatible endpoints.
Installation
# 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
Prerequisites:
- Python 3.10+
tigrisCLI on PATH (the binary's alias ist3)
Usage
Basic Commands
# 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 Mode
When invoked without a subcommand, the CLI enters an interactive REPL with tab-completion and history.
Command Groups
auth
OAuth-based authentication.
| Command | Description |
|---|---|
login |
Browser OAuth login (tigris login) |
logout |
Log out of current session |
whoami |
Print authenticated user / org |
bucket
Bucket CRUD.
| Command | Description |
|---|---|
list |
List all buckets |
create --name NAME |
Create a bucket |
delete --name NAME --yes |
Delete an empty bucket (--yes required) |
info NAME |
Get bucket info |
object
Object operations (wraps tigris ls/cp/rm/stat).
| Command | Description |
|---|---|
list --bucket B [--prefix P] [--limit N] |
List objects |
put --bucket B --key K (--file F | --text T) |
Upload an object |
get --bucket B --key K --output F |
Download an object |
delete --bucket B --key K |
Delete an object |
info --bucket B --key K |
Object metadata (HEAD / stat) |
cp SRC DST [-r] |
Copy. Accepts t3:// or tigris:// URIs. |
presign
Time-limited URLs.
| Command | Description |
|---|---|
get --bucket B --key K [--expires SEC] |
Presigned download URL |
put --bucket B --key K [--expires SEC] |
Presigned upload URL |
snapshot
Point-in-time bucket snapshots — a Tigris-specific primitive.
| Command | Description |
|---|---|
list BUCKET |
List snapshots for a bucket |
take BUCKET [--name N] |
Take a snapshot |
access-key
Scoped programmatic credentials — combine with snapshot for per-agent isolation.
| Command | Description |
|---|---|
list |
List all access keys |
create NAME |
Create a new access key (secret shown ONCE) |
get KEY_ID |
Show key details |
delete KEY_ID --yes |
Permanently delete a key (--yes required) |
assign KEY_ID --bucket B --role R |
Scope a key to a bucket + role |
rotate KEY_ID --yes |
Rotate a key's secret (--yes required) |
iam
Policies and organization users.
| Command | Description |
|---|---|
policy list |
List IAM policies |
policy create NAME --document FILE |
Create a policy from a JSON file |
user list |
List org users |
user invite EMAIL [--role R] |
Invite a user |
Output Formats
All commands support dual output modes:
- Human-readable (default): tables, colors, formatted text
- Machine-readable (
--json): JSON envelope (or upstream CLI's--format jsonoutput, echoed verbatim)
For AI Agents
When using this CLI programmatically:
- Always pass
--jsonfor parseable output. - Check return codes — 0 for success, non-zero for errors.
- Read stderr for error messages.
object cpacceptst3://bucket/keyortigris://bucket/keyURIs; server-side copies (t3 → t3) skip the round trip entirely.presignreturns a URL on stdout in human mode; in JSON mode it's theurlfield.- For destructive work: bucket deletion, access-key deletion, and
access-key rotation require explicit
--yes; take asnapshotof the target bucket first, then do the work, then either keep the snapshot or discard. - For per-agent isolation:
access-key create+access-key assign --bucket B --role Editorto mint a key scoped to one bucket; revoke withaccess-key deletewhen the agent run ends.
Why Tigris
- Globally distributed. Data placed close to wherever it's read.
- No egress fees. Agents pulling artifacts from anywhere don't incur per-region bandwidth charges.
- Snapshots + scoped credentials. Primitives generic S3-compatible providers don't ship — the foundation for per-agent isolation.
- S3-compatible. Useful alongside S3-aware tools, but this harness itself is not a generic S3/MinIO/R2/AWS endpoint manager.
Version
1.0.0