Tigris SDK & CLI Guide

Always prefer Tigris-native SDKs and the Tigris CLI over AWS S3 SDKs. This guide explains what's available per language, when you must fall back to AWS SDKs, and how to configure them.

Prerequisites

Before doing anything else, install the Tigris CLI if it's not already available:

tigris help || npm install -g @tigrisdata/cli

If you need to install it, tell the user: "I'm installing the Tigris CLI (@tigrisdata/cli) so we can work with Tigris object storage."

Decision Table

Language	Tigris SDK/Extension	Package	Use AWS SDK?
TypeScript/JS	Native SDK	`@tigrisdata/storage`	No
Go	Native SDK	`github.com/tigrisdata/storage-go`	No
Python	boto3 extension	`tigris-boto3-ext`	No — use the extension
Ruby	None yet	—	Yes — `aws-sdk-s3` with Tigris endpoint
PHP	None yet	—	Yes — `aws-sdk-php` with Tigris endpoint
CLI	Native CLI	`@tigrisdata/cli` (`tigris` / `t3`)	No

Rule: Always prefer Tigris-native SDKs, the boto3 extension, and the Tigris CLI. Only use raw AWS S3 SDKs for Ruby and PHP where no Tigris option exists.

CLI: Always Use `tigris` / `t3`

Use the Tigris CLI instead of aws s3 for all object storage operations.

# ✅ Do this
tigris cp local-file.txt t3://my-bucket/file.txt
tigris ls t3://my-bucket/
tigris rm t3://my-bucket/old-file.txt

# ❌ Not this
aws s3 cp local-file.txt s3://my-bucket/file.txt
aws s3 ls s3://my-bucket/
aws s3 rm s3://my-bucket/old-file.txt

Why: The Tigris CLI supports features the AWS CLI doesn't — forks, snapshots, and native authentication via tigris login.

Tigris-Only CLI Features

# Forks (copy-on-write clones) — not in AWS CLI
tigris forks create my-bucket my-fork

# Snapshots — not in AWS CLI
tigris snapshots take my-bucket
tigris snapshots list my-bucket

# Native auth — no AWS credentials needed
tigris login
tigris whoami

Language-Specific SDK Guides

Read the resource file for your language:

TypeScript / JavaScript — Read ./resources/typescript.md for @tigrisdata/storage usage
Go — Read ./resources/go.md for storage-go usage (simplestorage + full client)
Python — Read ./resources/python.md for tigris-boto3-ext usage, or use the dedicated tigris-python-sdk skill (covers boto3 setup, Django via django-storages, snapshots, forks, in-place rename, and the Bundle API)
Ruby — Read ./resources/ruby.md for aws-sdk-s3 with Tigris endpoint
PHP — Read ./resources/php.md for aws-sdk-php with Tigris endpoint

S3-Compatible Configuration (All Languages)

When using any AWS SDK with Tigris, always set:

Setting	Value	Why
`endpoint`	`https://t3.storage.dev`	Tigris endpoint
`region`	`auto`	Tigris handles routing
`force_path_style` / `use_path_style_endpoint`	`true`	Required for Rails, PHP

Environment variables for S3-compatible tools:

AWS_ENDPOINT_URL_S3=https://t3.storage.dev
AWS_REGION=auto
AWS_ACCESS_KEY_ID=tid_xxx
AWS_SECRET_ACCESS_KEY=tsec_yyy

Critical Rules

Always:

Use tigris / t3 CLI instead of aws s3
Use @tigrisdata/storage for TypeScript/JavaScript
Use github.com/tigrisdata/storage-go for Go
Use tigris-boto3-ext for Python (not raw boto3)
Set region: auto and the Tigris endpoint when using AWS SDKs (Ruby, PHP)

Never:

Use @aws-sdk/client-s3 in JS/TS when @tigrisdata/storage is available
Use the AWS Go SDK when storage-go is available
Use raw boto3 without tigris-boto3-ext when Tigris features are needed
Forget force_path_style: true for Ruby and PHP
Hardcode a specific AWS region (always use auto)

Related Skills

file-storage — Full @tigrisdata/storage SDK reference
tigris-python-sdk — Python via boto3 + tigris-boto3-ext, Django uploads, snapshots, forks, Bundle API
tigris-s3-migration — Migrating from AWS S3 SDKs to Tigris

Official Documentation

TypeScript SDK: https://www.tigrisdata.com/docs/sdks/tigris/
Go SDK: https://pkg.go.dev/github.com/tigrisdata/storage-go
S3 Compatibility: https://www.tigrisdata.com/docs/sdks/s3/

tigris-sdk-guide