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

## When to use[​](#when-to-use "Direct link to When to use")

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

## Install the skill[​](#install-the-skill "Direct link to Install the skill")

```
npx skills add tigrisdata/skills --skill tigris-sdk-guide
```

This page is generated from [`skills/tigris-sdk-guide/SKILL.md`](https://github.com/tigrisdata/skills/blob/main/skills/tigris-sdk-guide/SKILL.md) in the [tigrisdata/skills](https://github.com/tigrisdata/skills) repository.

## Prerequisites[​](#prerequisites "Direct link to 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[​](#decision-table "Direct link to 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`[​](#cli-always-use-tigris--t3 "Direct link to 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[​](#tigris-only-cli-features "Direct link to 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[​](#language-specific-sdk-guides "Direct link to 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)[​](#s3-compatible-configuration-all-languages "Direct link to 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[​](#critical-rules "Direct link to 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[​](#related-skills "Direct link to 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[​](#official-documentation "Direct link to 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/>
