Authentication

Browser sign-in (recommended)

tufty login

The CLI prints an authorization link, tries to open your browser, then checks every 2 seconds whether you've approved it. The link is valid for 30 minutes and can be opened in a browser on any device, so it works from SSH sessions and containers too. Once approved, the API key is written to the config file automatically.

Save an API key yourself

1. Sign in to tufty.ai and open Account settings → API keys.
2. Create or copy a key (it starts with sk-).
3. Save it on this machine:

tufty auth set sk-xxxx

Inspect and remove

tufty auth get          # the key in use and where it came from, masked: sk-***1234
tufty auth get --show   # print the full key
tufty logout            # remove the key from the config file

result.data.source from tufty auth get is env (from TUFTY_API_KEY) or config (from the config file). If TUFTY_API_KEY is set, it still applies after tufty logout — unset it as well.

Key lookup order

Commands that need a key look in this order and stop at the first hit:

1. The --api-key <key> flag
2. The TUFTY_API_KEY environment variable
3. The config file ~/.tufty/config.json (written by tufty login / tufty auth set; change the directory with TUFTY_CONFIG_DIR)
4. Interactive sign-in — only in an interactive terminal. In CI (when CI is set), agents and pipes it never starts; the command returns no_api_key instead

The config file is written readable by the current OS user only. On Windows the path is %USERPROFILE%\.tufty\config.json.

What works without signing in

• tufty tools list, tufty tools describe <id>, tufty <tool> -h
• Any tool command with --dry-run
• tufty upload of a URL that is already on static.tufty.ai

Credits and top-ups

Generating uses your account's credits; when you run out, commands return insufficient_balance. Check your balance under Account settings → Credits, or pick a plan on the pricing page. How costs add up: Credits.