Suno CLI

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

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

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