tigrisdata 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.mdfor@tigrisdata/storageusage - Go — Read
./resources/go.mdforstorage-gousage (simplestorage + full client) - Python — Read
./resources/python.mdfortigris-boto3-extusage, 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.mdforaws-sdk-s3with Tigris endpoint - PHP — Read
./resources/php.mdforaws-sdk-phpwith 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/t3CLI instead ofaws s3 - Use
@tigrisdata/storagefor TypeScript/JavaScript - Use
github.com/tigrisdata/storage-gofor Go - Use
tigris-boto3-extfor Python (not rawboto3) - Set
region: autoand the Tigris endpoint when using AWS SDKs (Ruby, PHP)
Never:
- Use
@aws-sdk/client-s3in JS/TS when@tigrisdata/storageis available - Use the AWS Go SDK when
storage-gois available - Use raw
boto3withouttigris-boto3-extwhen Tigris features are needed - Forget
force_path_style: truefor Ruby and PHP - Hardcode a specific AWS region (always use
auto)
Related Skills
- file-storage — Full
@tigrisdata/storageSDK 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/