tigris-sdk-guide

---
name: tigris-sdk-guide
description: Use when choosing between Tigris-native SDKs and AWS S3-compatible SDKs — covers which SDK to use per language, CLI preference, and when AWS SDKs are the only option
license: MIT
---

# 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:

```bash
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.

```bash
# ✅ 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

```bash
# 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:

```bash
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/