Suno by Ace Data Cloud — CLI

Install the Ace integration

This integration is maintained by Ace Data Cloud and uses your Ace API key. It is not an official client published by the model owner. Check the PyPI package and its AceDataCloud repository before installing.

python -m pip install suno-cli
suno --help
suno models

The commands above show local help/reference information and do not submit a generation. Then follow Get API Token below: register/sign in, initialize General application if needed, create/copy an application key, and store it in the terminal's ACEDATACLOUD_API_TOKEN environment variable. Do not use a platform management token.

Generation follows your account's current service access, balance and pricing. Save the returned task ID and query that same ID; do not repeat generation while a task is pending.

suno task <task-id>
suno wait <task-id> --interval 5

A successful command or running preview does not prove a completed media result. Check the task's terminal outcome and returned media link. 中文首次使用指南 · Service-name package directory

A command-line tool for AI music generation using Suno through the AceDataCloud API.

Generate AI music, lyrics, and manage audio projects directly from your terminal — no MCP client required.

Features

• Music Generation — Generate from prompts, custom lyrics, extend, cover, remaster, concat
• Lyrics — Generate lyrics, mashup, optimize style descriptions
• Media Conversion — Get MP4, WAV, MIDI, timing, extract vocals
• Task Management — Query tasks, batch query, wait with polling
• Custom Models — Train, inspect, generate with, and archive custom music models
• Rich Output — Beautiful terminal tables and panels via Rich
• JSON Mode — Machine-readable output with --json for piping
• File Input — Read lyrics from files with @filename syntax

Quick Start

1. Get API Token

1. Open Ace Data Cloud → Applications. Sign in, or register an account first.
2. Find General application. If it has not been created, choose Initialize General Application. A general key can use the services available to your account; a dedicated application's key is limited to its service. Check the required service/model access and current pricing.
3. Copy the API Key from the application card, or open Keys / Manage Keys → Create to create a separate key for this integration. Give it a recognizable name so you can revoke or rotate it independently.
4. When creating a key, review Expiration Time, Set Usage Limitation, and Allowed APIs. Enable only the restrictions you need, allow the operations you will call, then click Create and copy the token from the key list. Task lookup does not grant permission to submit a generation. Confirm the application's balance can cover your first request; any trial allowance is whatever your account currently displays.
5. Copy only the token value, without quotation marks, spaces, or Bearer . An API Key / API Token field expects this raw value; only a manually configured HTTP Authorization header needs the Bearer prefix. A platform-... account-management token cannot replace a generation API key.

Save the key in the client's credential store or the environment variable shown below. Never put it in a prompt, shared workflow, screenshot, or Git commit. If authentication fails, check the full copied value, application/service access, expiration, usage limit, and balance before creating another key.

2. Install

# Install with pip
pip install suno-cli

# Or with uv (recommended)
uv pip install suno-cli

# Or from source
git clone https://github.com/AceDataCloud/SunoCli.git
cd SunoCli
pip install -e .

3. Configure

# Set your API token
export ACEDATACLOUD_API_TOKEN=your_token_here

# Or use .env file
cp .env.example .env
# Edit .env with your token

4. Use

# Generate music from a prompt
suno generate "A happy birthday song with acoustic guitar"

# Generate with custom lyrics
suno custom -l "[Verse]\nHello world\n[Chorus]\nLa la la" -t "Hello" -s "pop, upbeat"

# Read lyrics from a file
suno custom -l @lyrics.txt -t "My Song" -s "rock, powerful"

# Generate lyrics
suno lyrics "A love song about the ocean at sunset"

# Check task status
suno task <task-id>

# Wait for completion with polling
suno wait <task-id> --interval 5

# Get MP4 video
suno mp4 <audio-id>

# List available models
suno models

Commands

Music Generation

Audio availability precheck

suno availability 33333333-3333-4333-8333-333333333333 --json

Replace the example UUID with the song's audio_id from a completed Suno task, not its task_id. suno availability <audio_id> calls authenticated POST /suno/availability synchronously before operations such as extend or cover. It currently consumes no Credits and does not submit a generation or poll a task.

A successful check returns data.id and data.available: true: positive evidence on the current channel, not a guarantee that a later operation will succeed. The state can change between the check and processing. Unknown availability returns an error (including 503 availability_unknown), never available: false. Invalid audio ID format returns 400 at the API boundary; the CLI rejects non-UUID input locally. Authentication, rate-limit and upstream errors also exit nonzero without automatic retries; retain the returned task/trace IDs for support. --json preserves the full successful response, including task_id and trace_id; without it, the command prints the data object.

Audio generation and processing failures

An audio_id identifies reference music for operations such as cover, extend and stem separation. A downloadable audio file does not guarantee that its ID remains available for further processing.

If one of these errors occurs, retain the original task_id (when available) and the error's trace_id, and contact support. The CLI displays the HTTP error body and exits nonzero; it does not automatically resubmit the operation. Do not treat a working download link as evidence that another processing attempt will succeed.

Lyrics

Media Conversion

Task Management

Custom Models

Utilities

Global Options

--token TEXT    API token (or set ACEDATACLOUD_API_TOKEN env var)
--version       Show version
--help          Show help message

Most commands support:

--json          Output raw JSON (for piping/scripting)
--model TEXT    Suno model version (default: chirp-v6)

The generate and custom commands also support:

--duration INT  Target track length in seconds

--negative-style maps to the API's negative_tags field and takes effect only in custom mode (suno custom, which sends custom: true). There is currently no fixed character limit for this field, but overly long input may still fail; keep it concise. The option on suno generate is preserved, but that command does not enable custom mode.

suno custom -l @lyrics.txt -t "My Song" -s "pop, upbeat" --negative-style "metal, harsh vocals"

Scripting & Piping

The --json flag outputs machine-readable JSON suitable for piping:

# Generate and extract task ID
TASK_ID=$(suno generate "rock song" --json | jq -r '.task_id')

# Wait for completion and get audio URL
suno wait $TASK_ID --json | jq -r '.data[0].audio_url'

# Batch generate from a file of prompts
while IFS= read -r prompt; do
  suno generate "$prompt" --json >> results.jsonl
done < prompts.txt

Available Models

Configuration

Environment Variables

Development

Setup Development Environment

# Clone repository
git clone https://github.com/AceDataCloud/SunoCli.git
cd SunoCli

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # or `.venv\Scripts\activate` on Windows

# Install with dev dependencies
pip install -e ".[dev,test]"

Run Tests

# Run unit tests
pytest

# Run with coverage
pytest --cov=suno_cli

# Run integration tests (requires API token)
pytest tests/test_integration.py -m integration

Code Quality

# Format code
ruff format .

# Lint code
ruff check .

# Type check
mypy suno_cli

Build & Publish

# Install build dependencies
pip install -e ".[release]"

# Build package
python -m build

# Upload to PyPI
twine upload dist/*

Docker

# Pull the image
docker pull ghcr.io/acedatacloud/suno-cli:latest

# Run a command
docker run --rm -e ACEDATACLOUD_API_TOKEN=your_token \
  ghcr.io/acedatacloud/suno-cli generate "A happy song"

# Or use docker-compose
docker compose run --rm suno-cli generate "A happy song"

Project Structure

SunoCli/
├── suno_cli/               # Main package
│   ├── __init__.py
│   ├── __main__.py        # python -m suno_cli entry point
│   ├── main.py            # CLI entry point
│   ├── core/              # Core modules
│   │   ├── client.py      # HTTP client for Suno API
│   │   ├── config.py      # Configuration management
│   │   ├── exceptions.py  # Custom exceptions
│   │   └── output.py      # Rich terminal formatting
│   └── commands/          # CLI command groups
│       ├── generate.py    # Music generation commands (12 commands)
│       ├── lyrics.py      # Lyrics & style commands
│       ├── media.py       # Media conversion commands
│       ├── persona.py     # Persona & upload commands
│       ├── task.py        # Task management commands
│       └── info.py        # Info & utility commands
├── tests/                  # Test suite (80+ tests)
├── .github/workflows/      # CI/CD (lint, test, publish to PyPI)
├── Dockerfile             # Container image
├── deploy/                # Kubernetes deployment configs
├── .env.example           # Environment template
├── pyproject.toml         # Project configuration
└── README.md

Suno CLI vs MCP Suno

Both tools use the same AceDataCloud API and share the same API token.

API Reference

This tool wraps the AceDataCloud Suno API:

• Suno Audios API — Music generation
• Suno Lyrics API — Lyrics generation
• Suno Tasks API — Task queries
• Suno Persona API — Persona management

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing)
5. Open a Pull Request

License

MIT License - see LICENSE for details.

Links

• AceDataCloud Platform
• MCP Suno — MCP server version
• Suno Official

Made with ❤️ by AceDataCloud