SongSmith CLI

AI-powered song creation from your terminal. Companion to songsmith.studio — a Pro ($35/mo) or Studio ($100/mo) subscription is required.

npm install -g songsmith-cli
songsmith login --email
songsmith status

What it does

Wraps the SongSmith webapp's API so you can plan albums, generate song concepts, render videos, and dispatch tracks to Suno without leaving the terminal. All credit-gated commands participate in the server's reservation ledger via a per-attempt operationId, so retrying a failed command never double-charges.

Common commands

# Concepts & lyrics
songsmith concept "rainy night in Tokyo" --style "lo-fi hip hop"
songsmith album plan "Neon Horizons" --theme "cyberpunk city" --genre synthwave --tracks 10

# Art & video
songsmith art generate "neon cityscape" --aspect 16:9
songsmith render song <id> --wait
songsmith render album <id> --wait

# Dispatch to Suno (requires the SongSmith Chrome extension)
songsmith suno send <song-id>
songsmith suno send --album <album-id> --on-error continue

# Recovery
songsmith songs retry <id>                       # reset a failed song to draft
songsmith songs fetch-audio <id> <suno-url>      # pull audio after a bridge timeout
songsmith album resume <id>                      # show missing tracks in a partial album

# Observability
songsmith songs events <id>                      # event timeline for a song
songsmith status --full                          # credits + Suno fleet health + render-queue lag

songsmith --help lists every command; songsmith <cmd> --help shows arguments for a specific one.

Global flags

• --format json — switch any command to JSON output (also auto-detects pipes).
• --quiet — suppress non-essential output.
• --verbose — log API calls + timing.
• --skip-preflight — bypass the pre-flight credit/kill-switch check (escape hatch for CI).
• --api-url <url> — point at a non-prod environment.

Auth & config

• Credentials are stored at ~/.config/songsmith/credentials.json with mode 0600.
• Tokens auto-refresh on 401.
• API errors include the server's x-request-id so support tickets can be correlated to backend logs.

Configuration

Firebase API key. The CLI uses Firebase Auth for sign-in. Firebase API keys are non-secret per Firebase's design — they identify the project, not the user — so an embedded fallback ships with the CLI. To override (e.g. self-hosted Firebase project), set one of:

export SONGSMITH_FIREBASE_KEY=your-key   # CLI-specific
# or
export NEXT_PUBLIC_FIREBASE_API_KEY=your-key   # matches the webapp env var

Precedence: SONGSMITH_FIREBASE_KEY > NEXT_PUBLIC_FIREBASE_API_KEY > embedded fallback.

Diagnostics. Run songsmith doctor for a fast checklist of credentials, API reachability, subscription tier, and the Suno bridge state. Add --deep to also probe the running extension via PING.

Suno bridge

Suno generation requires the SongSmith Chrome extension running in your browser. The CLI starts a localhost WebSocket server, opens a relay tab at songsmith.studio/cli-bridge, and proxies generation requests through it. songsmith suno connect starts a persistent bridge; subsequent suno send calls reuse it.

Links

• Web app: https://songsmith.studio
• Pricing: https://songsmith.studio/pricing
• Issues / feedback: https://github.com/NiroWeb/songsmith-2.0/issues

License

Proprietary — see SongSmith terms of service.