ut — UploadThing CLI

Manage your UploadThing files straight from the terminal.
Upload, list, delete, rename, and sign files — scriptable, JSON-ready, zero friction.

---

Table of Contents

• Quick Start
• Installation
  • macOS — Homebrew
  • Linux — curl
  • Windows
  • Build from source
• Authentication
  • What token do I need?
  • Saving your token
  • Environment variable
  • Switching tokens / profiles
• Commands
• Global flags
• Examples

---

Quick Start

# 1. Add your token (interactive wizard)
ut auth add

# 2. Upload a file
ut upload photo.jpg

# 3. List all files
ut list --all

# 4. Delete a file
ut delete <file-key>

---

Installation

macOS — Homebrew

Works on Apple Silicon. Intel Mac: build from source (see below).

brew tap daikiejp/ut
brew install ut

Linux (x86_64 / ARM64)

# x86_64
curl -L https://github.com/daikiejp/uploadthing-cli/releases/latest/download/ut-linux-x86_64.tar.gz \
  | tar -xz && sudo mv ut-linux-x86_64 /usr/local/bin/ut

# ARM64 (Raspberry Pi, AWS Graviton, etc.)
curl -L https://github.com/daikiejp/uploadthing-cli/releases/latest/download/ut-linux-arm64.tar.gz \
  | tar -xz && sudo mv ut-linux-arm64 /usr/local/bin/ut

Windows

Download ut-windows-x86_64.zip from Releases, extract it, and add the folder to your PATH.

Scoop and winget support coming soon.

Build from source

Requires Rust ≥ 1.75.

git clone https://github.com/daikiejp/uploadthing-cli
cd uploadthing-cli
cargo install --path .

---

Authentication

What token do I need?

You need a V7 token from the UploadThing dashboard — a long base64 string (not an sk_live_... key).

1. Open uploadthing.com/dashboard
2. Select your app → API Keys
3. Click the V7 tab and copy the token

⚠️ The V7 token contains your appId, apiKey, and ingest URL.
Treat it like a password — it grants full access to your app's files.

Saving your token

The interactive wizard handles everything:

ut auth add

It asks for a profile name (default: default), prompts for your token (hidden input), verifies it live against the API, then saves it to:

Platform	Config path
macOS / Linux	~/.config/uploadthing/config.toml
Windows	%APPDATA%\uploadthing\config.toml

Non-interactive (scripts / CI setup):

ut auth add --name work --token <your-v7-token>

Environment variable

UPLOADTHING_TOKEN overrides every saved profile — perfect for CI/CD:

export UPLOADTHING_TOKEN=<your-v7-token>
ut list

Switching tokens / profiles

Save multiple tokens and switch between them freely:

ut auth list              # see all saved profiles
ut auth use work          # switch active profile to "work"
ut auth status            # show currently active token + config path
ut auth remove old-app    # delete a profile

Use a specific profile for a single command:

ut -p work list --all

Pass a token inline without saving it:

ut --token <your-v7-token> info

---

Commands

Command	Alias	Description
ut auth add	—	Add / update a saved profile (interactive)
ut auth remove <name>	—	Remove a saved profile
ut auth use <name>	—	Switch the active profile
ut auth list	—	List all saved profiles
ut auth status	—	Show active token and config file path
ut upload <file…>	—	Upload one or more local files
ut list	ut ls	List files in your UploadThing app
ut delete <key…>	ut rm	Delete files by key (with confirmation)
ut rename <key> <name>	ut mv	Rename a file
ut sign <key>	—	Generate a time-limited signed URL
ut info	—	Show app info and storage usage

Run ut <command> --help for all flags.

---

Global flags

Flag	Short	Description
--token <TOKEN>	—	Override token inline (UPLOADTHING_TOKEN env also works)
--profile <NAME>	-p	Use a specific saved profile
--json	—	Machine-readable JSON output (great for jq pipelines)
--debug	—	Print presigned URLs, raw HTTP responses, and other verbose info

---

Examples

# Upload multiple files
ut upload report.pdf banner.png logo.svg

# Upload as private (requires signed URLs to access)
ut upload secret.pdf --acl private

# List files as JSON and extract keys with jq
ut list --limit 100 --json | jq '.[].key'

# List every file (auto-pagination)
ut list --all

# Delete without confirmation prompt (safe for scripts)
ut delete abc123key xyz456key --force

# Rename a file
ut rename abc123key "Q3-Report-Final.pdf"

# Generate a signed URL valid for 24 hours
ut sign abc123key --expires-in 86400

# One-off command with a specific profile
ut -p staging list --all

# CI: token from env, JSON output
UPLOADTHING_TOKEN=<token> ut upload dist.zip --json

---

Contributing

PRs welcome. Please run cargo clippy and cargo fmt before submitting.

License

MIT