Metadata-Version: 2.4
Name: suno-music-cli
Version: 0.1.2
Summary: CLI for generating music via sunoapi.org
Project-URL: Homepage, https://github.com/bengeos/suno-music-cli
Project-URL: Repository, https://github.com/bengeos/suno-music-cli
Project-URL: Issues, https://github.com/bengeos/suno-music-cli/issues
Author-email: Biniam Kassahun <george.beng@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,audio,cli,generation,music,suno
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.7
Requires-Dist: rich>=13.7
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

# suno-music-cli

[![PyPI version](https://img.shields.io/pypi/v/suno-music-cli.svg)](https://pypi.org/project/suno-music-cli/)
[![Python versions](https://img.shields.io/pypi/pyversions/suno-music-cli.svg)](https://pypi.org/project/suno-music-cli/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

A small, friendly command-line client for [sunoapi.org](https://sunoapi.org).
Submit lyrics or a description, get a task ID back, poll until ready, and
download the resulting MP3 — all from your terminal, scriptable end to end.

## Features

- **Generate** music from a description or your own lyrics, in any language.
- **Tune** the result with sliders for style adherence, weirdness, and audio
  weight; control vocal gender, models (`V4` through `V5_5`), and personas.
- **Extend** an existing track from any timestamp, with optional fresh
  parameters or inherited defaults.
- **Watch and download** with a single `--wait` flag, or fire-and-forget and
  poll later with `--last`.
- **URL-only mode** — get the 15-day CDN link without downloading the file.
- **Local job cache** so you never have to copy-paste task IDs.
- **JSON output** on every read command for `jq` pipelines.

## Install

```bash
pip install suno-music-cli
```

Requires Python 3.10 or newer.

## Configure

Get an API key from [sunoapi.org](https://sunoapi.org) and provide it one of
two ways:

```bash
export SUNO_API_KEY=sk-...                # ephemeral
suno config set-key sk-...                # persistent, in ~/.suno/config.toml
```

Optional overrides: `SUNO_BASE_URL`, `SUNO_CALLBACK_URL`. See
[Documentation.md §2](Documentation.md#2-configuration).

## Quick start

```bash
# Submit a job (the model writes its own lyrics from the description)
suno generate -p "ambient piano, soft rain, late night" -m V5

# Watch it through to completion
suno status --last --watch

# Save the audio
suno download --last -o ./out/
```

`--last` always points to the most recent job in your local cache.

## Commands at a glance

| Command | What it does |
|---|---|
| `suno generate` | Submit a generation job. Returns a `taskId`. |
| `suno status` | Poll `record-info` for a task. `--watch` blocks until done. |
| `suno download` | Save audio files to disk, or print URLs with `--url-only`. |
| `suno extend` | Continue an existing track from a timestamp. |
| `suno lyrics` | Submit a lyrics-only generation job. |
| `suno credits` | Show remaining account balance. |
| `suno list` | Show recently submitted jobs from local cache. |
| `suno config` | Manage API key and other settings. |

Every flag is documented in [Documentation.md §3](Documentation.md#3-command-reference).

## A richer example: custom lyrics with full control

```bash
suno generate \
  --custom \
  --lyrics-file ./lyrics.txt \
  --style-file  ./style.txt \
  --title       "Midnight Drive" \
  --model       V5 \
  --vocal-gender f \
  --style-weight 0.85 \
  --weirdness    0.20 \
  --negative-tags "metal, heavy distortion" \
  --wait
```

Custom mode lets you provide your own lyrics with section markers
(`[Verse 1]`, `[Chorus]`, `[Bridge]`), works in non-Latin scripts, and
honors a long, structured style descriptor. The three weight sliders fine-tune
how closely the model follows your direction. See
[§4 — Techniques](Documentation.md#4-techniques-getting-good-music) for the
craft side of getting good music out of Suno.

## URLs vs files

```bash
suno download --last --url-only          # print the CDN URLs (15-day links)
suno download --last -o ./out/           # save to ./out/<title>.mp3
suno download --last -o song.mp3 --track 1
```

A `taskId` typically returns two tracks; multi-track outputs are saved with
an 8-character suffix to keep filenames unique.

## Documentation

The full reference — every flag, every API field, all the music-creation
techniques (lyrics structure, style descriptors, slider pairings, language
handling, troubleshooting) — lives in **[Documentation.md](Documentation.md)**.

Highlights:

- [Concepts](Documentation.md#1-concepts) — modes, models, status lifecycle, character limits.
- [Command reference](Documentation.md#3-command-reference) — every flag mapped to its API field.
- [Techniques](Documentation.md#4-techniques-getting-good-music) — how to write a style descriptor that actually works, what the sliders do, multilingual lyrics tips.
- [Troubleshooting](Documentation.md#6-troubleshooting) — common errors and fixes.

## Limits and constraints (good to know)

- 20 requests per 10-second window (server rate limit).
- Stream URLs available 30–40s after submit, download URLs 2–3 minutes after.
- Generated files retained on the CDN for **15 days**, then deleted.
- Per-model character caps for `prompt`, `style`, and `title` —
  see [§1.5](Documentation.md#15-character-limits).

## Contributing

Issues and pull requests welcome at
[github.com/bengeos/suno-music-cli](https://github.com/bengeos/suno-music-cli).

## License

[MIT](LICENSE) © 2026 Biniam Kassahun
