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:

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/