CLI
CLI Overview
Every tufty command and the conventions they share.
Commands
| Command | What it does |
|---|---|
tufty <tool> | Run a studio tool, e.g. tufty pet-dressup. See Tools |
tufty tools list | List every tool |
tufty tools describe <id> | Print everything about one tool: inputs, options, prices and limits |
tufty status <runId> | Look up a run; add --wait to wait until it finishes |
tufty upload <file> | Upload a file to tufty storage and print its public URL |
tufty login | Sign in with a browser device code |
tufty auth set <apiKey> | Save an API key |
tufty auth get | Show the key in use (masked by default) |
tufty logout | Remove the key from the config file |
Where tool commands come from
Tool commands and their flags aren't hard-coded into the CLI. At run time the CLI reads the server's tool manifest (cached locally for 10 minutes), registers a command per tool, and builds and validates the options from it. When the site adds a tool or changes a price or option, the CLI keeps up without an upgrade — which is why tufty <tool> -h is always the source of truth.
auth, login, logout, upload and status don't depend on the manifest and never fetch it.
Shared conventions
- Stdout carries exactly one JSON envelope; progress goes to stderr. See Output modes.
- Exit codes:
0success,1runtime or API error,2usage error. See Exit codes. - Input counts, file existence and option values are checked before anything is uploaded, so a typo never costs credits.
- A misspelled command returns
unknown_command, with the closest matches indetails.suggestions.
Common combinations
# What tools are there
tufty tools list
# A tool's current flags and prices
tufty pet-dressup -h
tufty tools describe pet-dressup
# Estimate first, then run
tufty pet-dressup --product ./sweater.jpg --model ./corgi.jpg --quality medium --dry-run
tufty pet-dressup --product ./sweater.jpg --model ./corgi.jpg --quality medium --save ./outIn this section
- Global flags: flags and environment variables shared by every command
- Output modes: the JSON envelope,
--format url,--save,--dry-run - Async runs and status:
--no-waitandtufty status - Local files and uploads: input handling, automatic cutout, limits
- Credits: estimating the cost before you run