{"id":48963780,"url":"https://github.com/paperfoot/suno-cli","last_synced_at":"2026-05-03T22:03:07.610Z","repository":{"id":349623845,"uuid":"1203166818","full_name":"paperfoot/suno-cli","owner":"paperfoot","description":"Generate AI music from your terminal — Suno v5.5 with tags, exclude, vocal control, and all generation features","archived":false,"fork":false,"pushed_at":"2026-04-17T20:03:11.000Z","size":368,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-17T22:29:22.513Z","etag":null,"topics":["ai-music","audio","chirp-fenix","cli","command-line","music","music-generation","rust","rust-cli","song-generator","suno","suno-ai","suno-api","suno-v5","terminal","text-to-music"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paperfoot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-06T19:36:18.000Z","updated_at":"2026-04-17T20:03:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/paperfoot/suno-cli","commit_stats":null,"previous_names":["199-biotechnologies/suno-cli","paperfoot/suno-cli"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/paperfoot/suno-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperfoot%2Fsuno-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperfoot%2Fsuno-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperfoot%2Fsuno-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperfoot%2Fsuno-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paperfoot","download_url":"https://codeload.github.com/paperfoot/suno-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperfoot%2Fsuno-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31954738,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-music","audio","chirp-fenix","cli","command-line","music","music-generation","rust","rust-cli","song-generator","suno","suno-ai","suno-api","suno-v5","terminal","text-to-music"],"created_at":"2026-04-18T03:04:05.524Z","updated_at":"2026-05-03T22:03:07.603Z","avatar_url":"https://github.com/paperfoot.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# suno\n\n**Generate AI music from your terminal — full Suno v5.5 support**\n\n\u003cbr /\u003e\n\n[![Star this repo](https://img.shields.io/github/stars/paperfoot/suno-cli?style=for-the-badge\u0026logo=github\u0026label=%E2%AD%90%20Star%20this%20repo\u0026color=yellow)](https://github.com/paperfoot/suno-cli/stargazers)\n\u0026nbsp;\u0026nbsp;\n[![Follow @longevityboris](https://img.shields.io/badge/Follow_%40longevityboris-000000?style=for-the-badge\u0026logo=x\u0026logoColor=white)](https://x.com/longevityboris)\n\n\u003cbr /\u003e\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue?style=for-the-badge)](LICENSE)\n\u0026nbsp;\n[![Rust](https://img.shields.io/badge/Rust-2024-orange?style=for-the-badge\u0026logo=rust)](https://www.rust-lang.org/)\n\u0026nbsp;\n[![crates.io](https://img.shields.io/crates/v/suno?style=for-the-badge)](https://crates.io/crates/suno)\n\u0026nbsp;\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=for-the-badge)](https://github.com/paperfoot/suno-cli/pulls)\n\n---\n\nA single Rust binary that talks directly to Suno's API. Generate songs with custom lyrics, style tags, your own voice persona, vocal control, weirdness/style sliders, covers, remasters, and every v5.5 feature. Zero-friction auth — one command extracts credentials from your browser automatically.\n\n[Install](#install) | [Quick Start](#quick-start) | [Commands](#commands) | [Features](#features) | [Contributing](#contributing)\n\n\u003c/div\u003e\n\n## Why\n\nSuno has no official API. The web UI works, but you can't script it, pipe lyrics from a file, batch-generate, or integrate it into a music production workflow.\n\nThis CLI fixes that. Auto-auth from your browser, every generation parameter exposed as a flag, dual JSON/table output for both humans and AI agents. Downloads auto-embed synced lyrics into MP3 files.\n\n## Install\n\n### Homebrew (macOS/Linux)\n\n```bash\nbrew tap paperfoot/tap\nbrew install suno\n```\n\n### Cargo (any platform)\n\n```bash\ncargo install suno\n```\n\n### Pre-built binaries\n\nDownload from [GitHub Releases](https://github.com/paperfoot/suno-cli/releases) — binaries for macOS (Apple Silicon + Intel), Linux (x86_64 + ARM), and Windows.\n\n### Self-update\n\nAlready have `suno` installed? Pull the latest binary from GitHub Releases without touching your package manager:\n\n```bash\nsuno update --check    # see what's available\nsuno update            # install the latest release\n```\n\n\u003e Tip: when Suno changes their API mid-cycle, run `suno update` first — it's faster than `cargo install suno` or waiting for the Homebrew bottle to refresh.\n\n## Quick Start\n\n```bash\n# 1. Authenticate (auto-extracts from Chrome/Arc/Brave/Firefox/Edge)\nsuno auth --login\n\n# 2. Check your credits\nsuno credits\n\n# 3. Generate a song with full control\nsuno generate \\\n  --title \"Weekend Code\" \\\n  --tags \"indie rock, guitar, upbeat\" \\\n  --exclude \"metal, heavy\" \\\n  --lyrics-file lyrics.txt \\\n  --vocal male \\\n  --weirdness 40 \\\n  --style-influence 65 \\\n  --wait --download ./songs/\n\n# 4. Generate with your voice persona\nsuno generate \\\n  --title \"My Song\" \\\n  --tags \"pop, warm\" \\\n  --persona e483d2f0-50ca-4a09-8a74-b9e074646377 \\\n  --lyrics \"[Verse]\\nHello from the CLI\"\n\n# 5. Let Suno write the lyrics for you\nsuno describe --prompt \"a chill lo-fi track about rainy mornings\" --wait\n```\n\n## Commands\n\n### Create\n\n```\nsuno generate        Custom mode — lyrics + tags + title + sliders + voice persona\nsuno describe        Description mode — Suno writes lyrics from your prompt\nsuno lyrics          Generate lyrics only (free, no credits)\nsuno extend          Continue a clip from a timestamp\nsuno concat          Stitch clips into a full song\nsuno cover           Create a cover with different style/model\nsuno remaster        Remaster with a different model version\nsuno stems           Extract vocals and instruments\n```\n\n### Browse \u0026 Inspect\n\n```\nsuno list            List your songs\nsuno search \u003cquery\u003e  Search songs by title or tags\nsuno info \u003cid\u003e       Detailed view of a single clip\nsuno persona \u003cid\u003e    View a voice persona\nsuno status \u003cids\u003e    Check generation progress\nsuno credits         Show balance and plan info\nsuno models          List available models with limits\n```\n\n### Manage\n\n```\nsuno download \u003cids\u003e  Download audio/video with embedded lyrics\nsuno delete \u003cids\u003e    Delete/trash clips\nsuno set \u003cid\u003e        Update title, lyrics, caption, or remove cover\nsuno publish \u003cids\u003e   Toggle public/private visibility\nsuno timed-lyrics    Get word-level timestamped lyrics (--lrc for LRC format)\n```\n\n### Config \u0026 Auth\n\n```\nsuno auth            Set up authentication\nsuno config          show | set | check\nsuno agent-info      Machine-readable capabilities JSON\nsuno install-skill   Install agent skill into Claude Code / Cursor\nsuno update          Self-update from GitHub Releases (--check to peek first)\n```\n\n## Features\n\n### Zero-Friction Auth\n\n```bash\nsuno auth --login    # Extracts session from your browser automatically\n```\n\nReads the Clerk auth cookie from Chrome, Arc, Brave, Firefox, or Edge. Exchanges it for a JWT via Clerk token exchange, stores the refreshable session in a `0600` local auth file, and refreshes stale JWTs automatically when the underlying browser session is still valid.\n\nAuth methods (in order of convenience):\n1. `suno auth --login` — automatic browser extraction (recommended)\n2. `suno auth --cookie \u003ccookie\u003e` — manual paste for headless servers; accepts either raw `__client` or a full browser `Cookie` header\n3. `suno auth --jwt \u003ctoken\u003e` — direct JWT, expires in ~1 hour\n4. `suno auth --refresh` — force a fresh JWT from the stored Clerk session\n\n`suno auth` with no flags checks the existing session, or starts browser login if no auth is configured. `suno auth --logout` removes stored credentials.\n\n### Generation Parameters\n\n| Flag | What it does | Values |\n|---|---|---|\n| `--title` | Song title | up to 100 chars |\n| `--tags` | Style direction | `\"pop, synths, upbeat\"` (1000 chars) |\n| `--exclude` | Styles to avoid | `\"metal, heavy, dark\"` (1000 chars) |\n| `--lyrics` / `--lyrics-file` | Custom lyrics with `[Verse]` tags | up to 5000 chars |\n| `--prompt` (describe) | Free text description | up to 500 chars |\n| `--model` | Model version | v5.5, v5, v4.5+, v4.5, v4, v3.5, v3, v2 |\n| `--vocal` | Vocal gender | male, female |\n| `--persona` | Voice persona ID | UUID from Suno voice creation |\n| `--weirdness` | How experimental | 0-100 |\n| `--style-influence` | How strictly to follow tags | 0-100 |\n| `--variation` | Output variation | high, normal, subtle |\n| `--instrumental` | No vocals | flag |\n| `--wait` | Block until done | flag |\n| `--download \u003cdir\u003e` | Auto-download after generation | directory path |\n\n### Voice Personas\n\nGenerate songs using your own voice. Create a voice in Suno's web UI, then use the persona ID:\n\n```bash\n# View persona details\nsuno persona \u003cpersona_id\u003e\n\n# Generate with your voice\nsuno generate --persona \u003cpersona_id\u003e --title \"My Song\" --tags \"pop\" --lyrics \"[Verse]\\nHello world\"\n\n# Works with describe mode too\nsuno describe --persona \u003cpersona_id\u003e --prompt \"a warm ballad about starlight\"\n```\n\n### Covers \u0026 Remasters\n\nCreate covers with different styles or remaster clips with newer models:\n\n```bash\n# Cover with different style tags\nsuno cover \u003cclip_id\u003e --tags \"jazz, smooth piano\" --model v5.5 --wait\n\n# Remaster an old clip with the latest model\nsuno remaster \u003cclip_id\u003e --model v5.5 --wait --download ./remastered/\n```\n\nBoth route through Suno's unified web generation endpoint (`/api/generate/v2-web/`).\n\n### Clip Info\n\n```bash\n# Full details for any clip\nsuno info \u003cclip_id\u003e\n\n# JSON for scripting\nsuno info \u003cclip_id\u003e --json | jq '.data.audio_url'\n```\n\n### Edit \u0026 Manage\n\n```bash\n# Update title and lyrics on an existing clip\nsuno set \u003cclip_id\u003e --title \"New Title\" --lyrics-file updated.txt\n\n# Make clips public\nsuno publish \u003cclip_id_1\u003e \u003cclip_id_2\u003e\n\n# Get timed lyrics in LRC format\nsuno timed-lyrics \u003cclip_id\u003e --lrc \u003e song.lrc\n```\n\n### Downloads with Embedded Lyrics\n\nDownloads automatically embed lyrics into MP3 files via ID3 tags:\n- **USLT** (plain lyrics) — shown in most music players\n- **SYLT** (synced word-by-word timestamps) — shown in Apple Music with timing\n\n```bash\nsuno download \u003cid1\u003e \u003cid2\u003e --output ./songs/\n```\n\nFiles use slug format: `title-slug-clipid8.mp3` — no overwrites when Suno generates 2 variations.\n\n### Models\n\n| Version | Codename | Default | Notes |\n|---|---|---|---|\n| **v5.5** | chirp-fenix | Yes | Latest, best quality |\n| v5 | chirp-crow | | Previous generation |\n| v4.5+ | chirp-bluejay | | Extended capabilities |\n| v4.5 | chirp-auk | | Stable |\n| v4 | chirp-v4 | | Legacy |\n\nRemaster models: v5.5 = chirp-flounder, v5 = chirp-carp, v4.5+ = chirp-bass.\n\n### Agent-Friendly\n\nEvery command supports `--json` for structured output. When stdout is piped, JSON is auto-detected. Progress and errors go to stderr. Exit codes are semantic:\n\n| Code | Meaning | Agent action |\n|---|---|---|\n| 0 | Success | Continue |\n| 1 | Runtime error (network, API) | Retry with backoff |\n| 2 | Config error | Fix config, don't retry |\n| 3 | Auth error | Run `suno auth --login` |\n| 4 | Rate limited | Wait 30-60s, retry |\n| 5 | Not found | Verify resource ID |\n\nError responses include actionable suggestions:\n\n```json\n{\n  \"version\": \"1\",\n  \"status\": \"error\",\n  \"error\": {\n    \"code\": \"auth_expired\",\n    \"message\": \"JWT expired — run `suno auth` to refresh\",\n    \"suggestion\": \"Run `suno auth --login` to refresh your session\"\n  }\n}\n```\n\n```bash\n# Pipe-friendly: auto-JSON when piped\nsuno list | jq '.data[0].title'\n\n# Agent capabilities discovery\nsuno agent-info\n```\n\n### Install as a Coding Agent Skill\n\nTeach Claude Code (or Cursor) how to use `suno` with one command:\n\n```bash\n# Claude Code (~/.claude/skills/suno/SKILL.md)\nsuno install-skill\n\n# Cursor (./.cursor/rules/suno.mdc in the current workspace)\nsuno install-skill --target cursor\n\n# Print the skill content without writing\nsuno install-skill --print\n\n# Custom path\nsuno install-skill --path ~/my-agents/suno.md --force\n```\n\nAfter installation, your coding agent automatically picks up the skill on the next session and knows how to invoke `suno` for music generation, downloads, stems, covers, and remasters.\n\n### API Endpoint Versions (Confirmed)\n\n| Endpoint | Version | Status |\n|---|---|---|\n| Feed | **v3** (`POST /api/feed/v3`) | Latest |\n| Generate | **v2-web** (`POST /api/generate/v2-web/`) | Latest web generation route |\n| Concat | **v2** (`POST /api/generate/concat/v2/`) | Latest |\n| Aligned lyrics | **v2** (`GET /api/gen/{id}/aligned_lyrics/v2/`) | Latest |\n| Persona | `GET /api/persona/get-persona-paginated/{id}/` | Confirmed |\n\nGeneration tasks use `/api/generate/v2-web/` with the current web request shape. Normal generation and voice-persona generation are verified; cover/remaster support is implemented but should be recaptured whenever Suno changes the web schema.\n\n## Contributing\n\n1. Fork the repo\n2. Create a branch (`git checkout -b feature/your-idea`)\n3. Make your changes and test with `cargo test`\n4. Open a PR\n\nWe especially welcome:\n- Audio upload implementation (S3 presigned flow documented in `API_INTELLIGENCE.md`)\n- Voice persona creation workflow (endpoints captured, request bodies needed)\n- Integration tests with `assert_cmd`\n- OS keychain/Secret Service/CredMan storage for auth secrets\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\nBuilt by [Boris Djordjevic](https://github.com/longevityboris) at [199 Biotechnologies](https://github.com/199-biotechnologies)\n\n\u003cbr /\u003e\n\n**If this saves you time:**\n\n[![Star this repo](https://img.shields.io/github/stars/paperfoot/suno-cli?style=for-the-badge\u0026logo=github\u0026label=%E2%AD%90%20Star%20this%20repo\u0026color=yellow)](https://github.com/paperfoot/suno-cli/stargazers)\n\u0026nbsp;\u0026nbsp;\n[![Follow @longevityboris](https://img.shields.io/badge/Follow_%40longevityboris-000000?style=for-the-badge\u0026logo=x\u0026logoColor=white)](https://x.com/longevityboris)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaperfoot%2Fsuno-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaperfoot%2Fsuno-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaperfoot%2Fsuno-cli/lists"}