# Tigris File Storage

Store and serve files with Tigris Object Storage. Covers CLI setup (bucket, access keys, auth) and the `@tigrisdata/storage` SDK for application code.

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

Use when working with Tigris file storage - uploading, downloading, deleting, listing files, presigned URLs, client uploads, or setting up Tigris CLI and SDK. Covers Next.js, Remix, Express, Rails, and Laravel. For Python/Django, see the tigris-python-sdk skill.

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

```
npx skills add tigrisdata/skills --skill file-storage
```

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

## Quick Start[​](#quick-start "Direct link to Quick Start")

```
# 1. Install CLI & authenticate

npm install -g @tigrisdata/cli

tigris login



# 2. Create bucket and access key

tigris buckets create my-app-uploads

tigris access-keys create "my-app-uploads-key"

# ⚠ Save the Secret Access Key — shown only once

tigris access-keys assign tid_xxx --bucket my-app-uploads --role Editor



# 3. Install SDK

npm install @tigrisdata/storage
```

```
# .env

TIGRIS_STORAGE_ACCESS_KEY_ID=tid_xxx

TIGRIS_STORAGE_SECRET_ACCESS_KEY=tsec_yyy

TIGRIS_STORAGE_ENDPOINT=https://t3.storage.dev

TIGRIS_STORAGE_BUCKET=my-app-uploads
```

```
import { put } from "@tigrisdata/storage";



// Files are private by default — only authenticated requests can access them

const result = await put("avatars/user-123.jpg", file);

if (result.error) throw result.error;

console.log(result.data?.url);



// Use access: "public" only when anonymous users need direct URL access

// const result = await put("avatars/user-123.jpg", file, { access: "public" });
```

See **Getting Started with CLI** below for detailed steps.

***

## Getting Started with CLI[​](#getting-started-with-cli "Direct link to Getting Started with CLI")

### Step 1: Install CLI[​](#step-1-install-cli "Direct link to Step 1: Install CLI")

```
npm install -g @tigrisdata/cli
```

Verify the installation:

```
tigris --version
```

`t3` is an alias for `tigris` — all commands work with either.

### Step 2: Authenticate[​](#step-2-authenticate "Direct link to Step 2: Authenticate")

```
tigris login
```

Opens browser for OAuth. After login, verify with:

```
tigris whoami
```

For CI/CD or non-interactive environments:

```
tigris configure --access-key <key> --access-secret <secret>
```

### Step 3: Create Bucket[​](#step-3-create-bucket "Direct link to Step 3: Create Bucket")

```
tigris buckets create my-app-uploads
```

Key points:

* Buckets are **private** by default. Use `--public` for publicly readable objects.
* Buckets are **global** by default. Use `--locations` to pin to specific regions.
* Type `help` after any command to see its options (e.g., `tigris buckets create help`).

### Step 4: Create Access Key[​](#step-4-create-access-key "Direct link to Step 4: Create Access Key")

```
tigris access-keys create "my-app-uploads-key"
```

This outputs an Access Key ID (`tid_xxx`) and Secret Access Key (`tsec_yyy`).

**The Secret Access Key is only shown once.** Copy it immediately. The Name field is only for human identification — it has no functional impact.

### Step 5: Configure Environment[​](#step-5-configure-environment "Direct link to Step 5: Configure Environment")

Create `.env` in your project root:

```
TIGRIS_STORAGE_ACCESS_KEY_ID=tid_xxx

TIGRIS_STORAGE_SECRET_ACCESS_KEY=tsec_yyy

TIGRIS_STORAGE_ENDPOINT=https://t3.storage.dev

TIGRIS_STORAGE_BUCKET=my-app-uploads
```

`TIGRIS_STORAGE_BUCKET` sets the default bucket for all SDK calls. Add `.env` to `.gitignore` — never commit credentials.

### Step 6: Assign Access Key to Bucket[​](#step-6-assign-access-key-to-bucket "Direct link to Step 6: Assign Access Key to Bucket")

```
tigris access-keys assign tid_xxx --bucket my-app-uploads --role Editor
```

**Roles:**

| Role       | Permissions                   | Use when                             |
| ---------- | ----------------------------- | ------------------------------------ |
| `Editor`   | Read + write + delete objects | App servers that upload/delete files |
| `ReadOnly` | Read objects only             | Apps that only serve/download files  |

Now you have:

* A bucket (`my-app-uploads`)
* An access key (`tid_xxx` / `tsec_yyy`)
* The key assigned to the bucket with Editor role
* A `.env` file ready for the SDK

### Step 7: Install SDK[​](#step-7-install-sdk "Direct link to Step 7: Install SDK")

```
npm install @tigrisdata/storage

# or

yarn add @tigrisdata/storage
```

Supports ES Modules and CommonJS.

***

## SDK Reference[​](#sdk-reference "Direct link to SDK Reference")

All methods return `TigrisStorageResponse<T, E>`. Always check `error` first:

```
const result = await put("file.txt", "hello");

if (result.error) {

  console.error(result.error);

  return;

}

console.log(result.data);
```

### config — Override Default Configuration[​](#config--override-default-configuration "Direct link to config — Override Default Configuration")

Every method accepts an optional `config` parameter of type `TigrisStorageConfig`:

```
type TigrisStorageConfig = {

  bucket?: string; // Override TIGRIS_STORAGE_BUCKET

  accessKeyId?: string; // Override TIGRIS_STORAGE_ACCESS_KEY_ID

  secretAccessKey?: string; // Override TIGRIS_STORAGE_SECRET_ACCESS_KEY

  endpoint?: string; // Override TIGRIS_STORAGE_ENDPOINT

};
```

Use `config` to target a different bucket or use different credentials per call:

```
// Upload to a different bucket

await put("report.pdf", data, { config: { bucket: "reports-archive" } });



// Use a separate read-only key for downloads

await get("file.txt", "string", {

  config: { accessKeyId: "tid_ro", secretAccessKey: "tsec_ro" },

});
```

### put — Upload[​](#put--upload "Direct link to put — Upload")

```
put(path: string, body: string | ReadableStream | Blob | Buffer, options?: PutOptions)
```

```
import { put } from "@tigrisdata/storage";



// Simple text upload

const result = await put("notes/hello.txt", "Hello, World!");



// Image with public access

const result = await put("avatars/user-123.jpg", file, {

  access: "public",

  contentType: "image/jpeg",

  addRandomSuffix: false,

});



// Large file with multipart and progress

const result = await put("videos/demo.mp4", fileStream, {

  multipart: true,

  onUploadProgress: ({ loaded, total, percentage }) => {

    console.log(`${loaded}/${total} bytes (${percentage}%)`);

  },

});



// Prevent accidental overwrite

const result = await put("config.json", data, {

  allowOverwrite: false,

});
```

**Put options:**

| Option             | Values                | Default   | Purpose                                                                            |
| ------------------ | --------------------- | --------- | ---------------------------------------------------------------------------------- |
| access             | `public`, `private`   | `private` | Object visibility                                                                  |
| addRandomSuffix    | boolean               | `false`   | Append random suffix to avoid collisions on user-uploaded files with the same name |
| allowOverwrite     | boolean               | `true`    | Allow replacing existing file                                                      |
| contentType        | MIME string           | inferred  | Content type header                                                                |
| contentDisposition | `inline`,`attachment` | `inline`  | Browser display behavior                                                           |
| multipart          | boolean               | `false`   | Enable for large files                                                             |
| onUploadProgress   | callback              | —         | `{loaded, total, percentage}`                                                      |
| config             | `TigrisStorageConfig` | —         | Override bucket/credentials (see config section above)                             |

**Response data:** `{ url, path, size, contentType, contentDisposition, modified }`

### get — Download[​](#get--download "Direct link to get — Download")

```
get(path: string, format: "string" | "file" | "stream", options?: GetOptions)
```

```
import { get } from "@tigrisdata/storage";



// Read as string (text, JSON)

const result = await get("notes/hello.txt", "string");

console.log(result.data); // "Hello, World!"



// Serve as file (for API routes)

const result = await get("avatars/user-123.jpg", "file", {

  contentDisposition: "inline",

});



// Trigger browser download

const result = await get("reports/q4.pdf", "file", {

  contentDisposition: "attachment",

});



// Stream large files

const result = await get("videos/demo.mp4", "stream");
```

**Get options:**

| Option             | Values                | Default     | Purpose                                                |
| ------------------ | --------------------- | ----------- | ------------------------------------------------------ |
| contentDisposition | `inline`,`attachment` | `inline`    | Display vs download                                    |
| contentType        | MIME string           | from upload | Override content type                                  |
| encoding           | string                | `utf-8`     | Text encoding                                          |
| config             | `TigrisStorageConfig` | —           | Override bucket/credentials (see config section above) |

### remove — Delete[​](#remove--delete "Direct link to remove — Delete")

```
remove(path: string, options?: RemoveOptions)
```

```
import { remove } from "@tigrisdata/storage";



const result = await remove("notes/hello.txt");

if (result.error) {

  console.error(result.error);

}
```

### list — List Objects[​](#list--list-objects "Direct link to list — List Objects")

```
list(options?: ListOptions)
```

```
import { list } from "@tigrisdata/storage";



// List all objects

const result = await list();

console.log(result.data?.items);



// Filter by prefix

const result = await list({ prefix: "avatars/" });



// Paginate through all objects

const allFiles = [];

let page = await list({ limit: 100 });

allFiles.push(...(page.data?.items ?? []));



while (page.data?.hasMore) {

  page = await list({

    limit: 100,

    paginationToken: page.data.paginationToken,

  });

  allFiles.push(...(page.data?.items ?? []));

}
```

**List options:**

| Option          | Purpose                                                                        |
| --------------- | ------------------------------------------------------------------------------ |
| prefix          | Filter keys starting with this string                                          |
| delimiter       | Group keys (e.g., `"/"` for folders)                                           |
| limit           | Max objects per page (default: 100)                                            |
| paginationToken | Continue from previous page                                                    |
| config          | `TigrisStorageConfig` — override bucket/credentials (see config section above) |

**Response data:** `{ items, paginationToken, hasMore }`

### head — Object Metadata[​](#head--object-metadata "Direct link to head — Object Metadata")

```
head(path: string, options?: HeadOptions)
```

```
import { head } from "@tigrisdata/storage";



const result = await head("avatars/user-123.jpg");

if (!result.error) {

  console.log(result.data);

  // { path, size, contentType, contentDisposition, modified, url }

}
```

### getPresignedUrl — Temporary URLs[​](#getpresignedurl--temporary-urls "Direct link to getPresignedUrl — Temporary URLs")

```
getPresignedUrl(path: string, options: GetPresignedUrlOptions)
```

```
import { getPresignedUrl } from "@tigrisdata/storage";



// Temporary download link (1 hour)

const result = await getPresignedUrl("reports/q4.pdf", {

  operation: "get",

  expiresIn: 3600,

});

console.log(result.data?.url);



// Temporary upload link (10 minutes)

const result = await getPresignedUrl("uploads/photo.jpg", {

  operation: "put",

  expiresIn: 600,

});
```

**Presigned URL options:**

| Option      | Values                | Default | Purpose                                                |
| ----------- | --------------------- | ------- | ------------------------------------------------------ |
| operation   | `get`,`put`           | —       | URL purpose                                            |
| expiresIn   | seconds               | `3600`  | Expiration time                                        |
| contentType | MIME string           | —       | Required for PUT                                       |
| config      | `TigrisStorageConfig` | —       | Override bucket/credentials (see config section above) |

**Response data:** `{ url, method, expiresIn }`

***

## Client-Side Uploads[​](#client-side-uploads "Direct link to Client-Side Uploads")

Upload files directly from the browser to Tigris without routing bytes through your server. Uses presigned URLs under the hood.

### Server — Handle Upload Requests[​](#server--handle-upload-requests "Direct link to Server — Handle Upload Requests")

```
// app/api/upload/route.ts

import { NextRequest, NextResponse } from "next/server";

import { handleClientUpload } from "@tigrisdata/storage";



export async function POST(request: NextRequest) {

  try {

    const body = await request.json();

    const { data, error } = await handleClientUpload(body);

    if (error) {

      return NextResponse.json({ error: error.message }, { status: 500 });

    }

    return NextResponse.json({ data });

  } catch (error) {

    return NextResponse.json(

      { error: "Failed to process upload request" },

      { status: 500 },

    );

  }

}
```

### Client — Direct Upload[​](#client--direct-upload "Direct link to Client — Direct Upload")

```
"use client";



import { upload } from "@tigrisdata/storage/client";

import { useState } from "react";



export default function FileUpload() {

  const [progress, setProgress] = useState(0);

  const [url, setUrl] = useState<string | null>(null);



  const handleFileChange = async (e: React.ChangeEvent<HTMLInputElement>) => {

    const file = e.target.files?.[0];

    if (!file) return;



    const result = await upload(file.name, file, {

      url: "/api/upload",

      access: "private",

      multipart: true,

      partSize: 10 * 1024 * 1024,

      onUploadProgress: ({ percentage }) => {

        setProgress(percentage);

      },

    });



    setUrl(result.url);

  };



  return (

    <>

      <input type="file" onChange={handleFileChange} />

      {progress > 0 && progress < 100 && <div>{progress}%</div>}

      {url && <div>Uploaded: {url}</div>}

    </>

  );

}
```

**Client upload options:**

| Option           | Required | Purpose                             |
| ---------------- | -------- | ----------------------------------- |
| url              | Yes      | Backend endpoint for presigned URLs |
| access           | No       | `public` or `private` (default)     |
| multipart        | No       | Enable for large files              |
| partSize         | No       | Bytes per part (default: 5 MiB)     |
| concurrency      | No       | Parallel part uploads (default: 4)  |
| contentType      | No       | MIME type                           |
| onUploadProgress | No       | `{loaded, total, percentage}`       |

### React Component (Optional)[​](#react-component-optional "Direct link to React Component (Optional)")

`npm install @tigrisdata/react` provides a drop-in `<Uploader>` component with file selection, progress, and error handling built in. See `@tigrisdata/react` docs for usage.

***

## Critical Rules[​](#critical-rules "Direct link to Critical Rules")

**Always:** Check `result.error` before `result.data` | Upload files as `private` by default — only set `access: "public"` when anonymous users need direct URL access | Use `handleClientUpload` for browser uploads (don't route bytes through server) | Use `multipart: true` for files over 100MB | Paginate `list()` with `hasMore` + `paginationToken` | Delete old files when replacing (no auto-cleanup) | Set `contentType` explicitly when it matters

**Never:** Expose access keys to the client (use `handleClientUpload` + `upload()` from `@tigrisdata/storage/client`) | Skip error checking | Use generic paths like `file.jpg` (use `avatars/${userId}.jpg` or timestamps) | Forget to save the Secret Access Key on creation (shown only once)

***

## Known Issues[​](#known-issues "Direct link to Known Issues")

| Problem                         | Cause & Fix                                                                                       |
| ------------------------------- | ------------------------------------------------------------------------------------------------- |
| "Access denied" on upload       | Key not assigned to bucket. Run `tigris access-keys assign tid_xxx --bucket <name> --role Editor` |
| "Bucket not found" from SDK     | Wrong bucket name in `.env`. Verify with `tigris buckets list`                                    |
| Secret Access Key lost          | Cannot recover. Create new: `tigris access-keys create "new-key"` and reassign                    |
| Files not publicly accessible   | Bucket is private by default. Use `--public` flag or `access: "public"` on `put()`                |
| Upload hangs on large files     | Add `multipart: true` to put options for files over 100MB                                         |
| List returns incomplete results | Default limit is 100. Use `hasMore` + `paginationToken` to paginate                               |
| Client upload fails (CORS/500)  | Server route must use `handleClientUpload` from `@tigrisdata/storage`                             |

***

## CLI Quick Reference[​](#cli-quick-reference "Direct link to CLI Quick Reference")

`t3` is an alias for `tigris`. Type `help` after any command for options.

```
# Auth

tigris login

tigris whoami



# Buckets

tigris buckets create <name> [--public] [--locations <region>]

tigris buckets list

tigris buckets delete <name>



# Access keys

tigris access-keys create "<name>"

tigris access-keys assign <tid_xxx> --bucket <name> --role Editor



# Objects

tigris cp <src> <dest> [-r]         # Upload/download/copy

tigris mv <src> <dest> [-rf]        # Move or rename

tigris rm <path> [-rf]              # Delete

tigris ls [bucket/prefix]           # List

tigris stat <path>                  # Metadata

tigris presign <path>               # Presigned URL

tigris touch <path>                 # Create empty object
```

Remote paths use `t3://` prefix: `t3://my-bucket/path/file.txt`

***

## Framework Integration Guides[​](#framework-integration-guides "Direct link to Framework Integration Guides")

For framework-specific upload/download patterns, read the resource file for your framework:

| Framework | SDK                                                  | Resource                                                                                |
| --------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Next.js   | `@tigrisdata/storage` (native)                       | Read `./resources/nextjs.md` — Server Actions, API Routes, next/image, client uploads   |
| Remix     | `@tigrisdata/storage` (native)                       | Read `./resources/remix.md` — action functions, loaders, client uploads                 |
| Express   | `@tigrisdata/storage` (native)                       | Read `./resources/express.md` — Multer, streaming uploads, client uploads               |
| Rails     | `aws-sdk-s3` (no native Ruby SDK yet)                | Read `./resources/rails.md` — Active Storage, direct uploads, image variants            |
| Django    | `tigris-boto3-ext` + `django-storages`               | Use the **tigris-python-sdk** skill — covers FileField, django-storages, presigned URLs |
| Laravel   | `league/flysystem-aws-s3-v3` (no native PHP SDK yet) | Read `./resources/laravel.md` — Storage facade, Livewire uploads, presigned URLs        |

### Deployment[​](#deployment "Direct link to Deployment")

| Framework | Platform       | Set env vars with                                      |
| --------- | -------------- | ------------------------------------------------------ |
| Next.js   | Vercel         | Dashboard → Settings → Environment Variables           |
| Remix     | Fly.io         | `fly secrets set TIGRIS_STORAGE_ACCESS_KEY_ID=... ...` |
| Express   | Docker         | `-e` flags or `.env` in Compose                        |
| Rails     | Fly.io / Kamal | `fly secrets set` or `kamal env push`                  |
| Laravel   | Forge / Vapor  | Dashboard → Environment or `vapor env:pull`            |

***

## Related Skills[​](#related-skills "Direct link to Related Skills")

* **tigris-python-sdk** — Python access via boto3, Django uploads, snapshots, forks, Bundle API
* **tigris-bucket-management** — Advanced bucket options (regions, tiers, snapshots)
* **tigris-object-operations** — Detailed SDK function reference
* **tigris-snapshots-forking** — Point-in-time recovery and bucket forking

## Official Documentation[​](#official-documentation "Direct link to Official Documentation")

* SDK: <https://www.tigrisdata.com/docs/sdks/tigris/>
* Client Uploads: <https://www.tigrisdata.com/docs/sdks/tigris/client-uploads/>
* Examples: <https://www.tigrisdata.com/docs/sdks/tigris/examples/>
