CLI Overview
Generate, list, and download AI music from your terminal with the ft command-line tool
ft is the official command-line companion to Finetuning.ai. Generate music, instrumental tracks, and sound effects, list past generations, download finished MP3s, and manage your playlists — all from your terminal.
The CLI uses the public API, which requires a Pro or Lifetime plan. Free and Plus tiers should use the web app.
Why use the CLI?
- Scriptable. Pipe
ft list --jsonintojq, kick off batches from a Makefile, wire it into CI. - Fewer clicks.
ft generate "lofi piano" --duration 60submits, 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 | bashThe 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 | iexInstalls 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 doctorft doctor runs a health check against the API and dumps the resolved config — use it any time the CLI feels off.
Upgrading
ft updateRe-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:
-
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. -
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. -
Confirm:
ft me # Email jane@example.com # Tier pro # Monthly remaining 463 / 500
Free and Plus accounts will hit 403 PRO_PLAN_REQUIRED on the verify step. Upgrade at finetuning.ai to use the API.
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 meYou 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.mp3ft 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-cf1e6db376f7If you Ctrl-C mid-poll, the generation keeps running server-side and still costs a credit. Resume with ft get <id> or ft download <id> — don't re-submit.
Instrumentals and sound effects
Beyond ft generate, two more commands submit, poll, and download in one shot:
# Instrumental, vocal-free track — the model picks the instrumentation
ft instrumental "dreamy lofi piano with soft vinyl crackle"
# Short sound effect (1–8s)
ft sfx generate "thunderclap with heavy rain" --duration 5Instrumentals share the generations store, so ft get, ft download, and ft list --type instrumental all work on them. Sound effects use their own ft sfx list / get / download commands. See the command reference for every flag.
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 confirmationBulk 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
Command reference
Every subcommand, flag, and exit code
Finetuning skill
Drive ft from Claude Code and other AI agents
Parameters
BPM, key, scale, language — what every flag does
MCP server
Chat agents (Claude, ChatGPT, Cursor) connect over MCP instead
Rate limits
Per-minute and monthly caps the CLI shares with the API