CLI Overview

ft is the official command-line companion to Finetuning.ai. Generate tracks, list past generations, download finished MP3s, and manage your playlists — all from your terminal.

Why use the CLI?

• Scriptable. Pipe ft list --json into jq, kick off batches from a Makefile, wire it into CI.
• Fewer clicks. ft generate "lofi piano" --duration 60 submits, polls, and saves the MP3 in one command.
• Secure auth. Your API key lives in the OS keychain (macOS Keychain, Windows Credential Manager, libsecret on Linux) — not in a dotfile.
• Cross-platform. Single static binary for macOS (arm64/amd64), Linux, and Windows.

Install

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/Nattothemoon/finetuning-cli/main/scripts/install.sh | bash

The installer drops ft into /usr/local/bin (with sudo) or ~/.local/bin (no sudo). If it lands in ~/.local/bin, make sure that's on your PATH:

export PATH="$HOME/.local/bin:$PATH"

Windows

iwr -useb https://raw.githubusercontent.com/Nattothemoon/finetuning-cli/main/scripts/install.ps1 | iex

Installs to %LOCALAPPDATA%\finetuning\bin and updates your user PATH. Open a fresh terminal afterwards so the PATH change takes effect.

Manual download

Grab a binary from the Releases page, unzip, and drop ft (or ft.exe) somewhere on your PATH.

Confirm it works

ft --version
ft doctor

ft doctor runs a health check against the API and dumps the resolved config — use it any time the CLI feels off.

Upgrading

ft update

Re-runs the install script for your OS to pull the latest release.

Authentication

The CLI cannot mint API keys — only the web app can. So step one is:

1. Sign in at finetuning.ai, go to Settings → API Keys, and create a new key. It starts with ft_live_ and is exactly 40 characters.

2. Store it on this machine:

   ft auth login
   # Paste your API key: ft_live_********************************

   The CLI prompts with echo off so the key never appears on screen, then stores it in your OS keychain and verifies it by calling /v1/me.

3. Confirm:

   ft me
   # Email             jane@example.com
   # Tier              pro
   # Monthly remaining 463 / 500

CI / non-interactive use

For shells where you can't paste, set the key as an environment variable. Every command honors it:

export FINETUNING_API_KEY=ft_live_...
ft me

You can also pass --api-key ft_live_... to a single command.

Your first generation

ft generate "lofi chill piano, mellow, late night" --duration 60
# ⠋ Generating... (12s elapsed, status=processing)
# ✓ completed in 48s
# Saved to ./lofi-chill-piano-07e8d430.mp3

ft generate is the orchestrator — it submits the job, polls until done (typically 30–90 seconds), and downloads the MP3 to your current directory.

Need to fire and forget instead? Add --no-wait:

ft generate "deep ambient drone" --no-wait
# Queued. id=07e8d430-2310-4c57-87a8-cf1e6db376f7 status=processing

# later:
ft download 07e8d430-2310-4c57-87a8-cf1e6db376f7

Managing your library

Beyond generating, the CLI manages what you've already made — in bulk, up to 100 tracks per request:

ft playlists                                  # list your playlists
ft playlist show "Focus Beats"                # one playlist with its tracks
ft playlist add "Focus Beats" <track-id>...   # add tracks (playlist by name or ID)
ft playlist remove "Focus Beats" <track-id>...
ft playlist move "Focus Beats" "Deep Work" <track-id>...
ft delete <track-id>...                       # permanent — asks for confirmation

Bulk operations are partial-success: one bad ID doesn't fail the batch, and failures print as per-track warnings. See the command reference for details, including the playlist privacy rules.

What's next