tigris-sdk-guide

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/