Introduction
rs-suno is a download-only command line tool that mirrors your Suno.ai
library to local files. It is written in Rust and modelled on
rclone: you point it at a destination directory and it
keeps that directory in step with your Suno library.
The binary is called suno. The crate published to crates.io
is rs-suno, so you install it with cargo install rs-suno and then run suno.
What it does
- Downloads your whole library, plus liked songs and playlists, as tagged audio files (MP3, FLAC, ALAC, or WAV).
- Mirrors changes on every run: it downloads new clips, updates tags and
artwork, renames or re-encodes files that changed, and, with
sync, removes local files whose clips have left your library. - Embeds rich metadata: core tags (title, artist, album, date) plus Suno details
(style, model, creator, and remix lineage), a front cover, and lyrics,
including optional synced (timed) lyrics as an
.lrcsidecar and MP3/WAVSYLTframes. - Groups remixes and edits into lineage albums and writes M3U8 playlists, including a synthetic “Liked Songs” list.
- Is safe to run unattended from cron or a systemd timer, with careful deletion rules so a bad listing can never wipe your library.
Two verbs, like rclone
rs-suno follows the rclone model of two clear verbs:
syncmirrors a source to a destination, including deleting local files that are no longer present upstream. This is the full mirror.copyis additive: it downloads and updates, but never deletes.
If you only ever want to accumulate files, use copy. If you want the
destination to be a faithful mirror of your library, use sync. Deletion is
governed by strict safety rules described in
Sync, copy and deletion safety.
Requirements
- A Suno account and its
__clientsession token (see Authentication). ffmpegon yourPATH, built with FLAC and animated-WebP support (see Installation and ffmpeg).
Quick start
cargo install rs-suno
suno config init
suno check ~/Music/Suno
suno sync ~/Music/Suno --yes
check is the safest first run: it shows what a mirror would change and writes
nothing. When the plan looks right, use sync for a faithful mirror or copy
for an archive that only grows.
Safety:
syncdeletes only after a complete, authoritative listing. It never deletes after an empty, failed, partial,--limit, or--sincelisting.
Where to go next
- New here? Start with Installation and ffmpeg, then Authentication.
- Setting up more than one account? See Configuration.
- Ready to run? See Commands reference and Sync, copy and deletion safety.
- Automating it? See Scheduling and exit codes.
Installation and ffmpeg
Install the CLI
With Cargo
If you have a Rust toolchain, install the published crate from crates.io:
cargo install rs-suno
This builds and installs the suno binary into ~/.cargo/bin. Make sure that
directory is on your PATH.
Pre-built binaries
Pre-built binaries are attached to each GitHub release. The following platforms are published:
| Platform | Asset | Notes |
|---|---|---|
| Linux x86_64 | suno-vX-x86_64-linux.tar.gz | statically linked (musl) |
| Linux aarch64 | suno-vX-aarch64-linux.tar.gz | statically linked (musl) |
| Windows x86_64 | suno-vX-x86_64-windows.zip | native MSVC |
| Windows aarch64 | suno-vX-aarch64-windows.zip | native MSVC |
Download the archive for your platform, extract the suno binary, and place it
somewhere on your PATH.
Each archive ships a matching .sha256 checksum and a build-provenance
attestation. The binaries are unsigned, so Windows may show a SmartScreen
“unknown publisher” prompt on first run; verify the download against its
.sha256 and attestation if you want to confirm its integrity.
Container image
The official Linux amd64 and arm64 image includes ffmpeg and CA certificates:
podman run --rm ghcr.io/teh-hippo/rs-suno:latest version
Read Containers for persistent config and library mounts, token handling, host scheduling, and Proxmox VE deployment.
Verify the install
suno version
This prints the build version and target, the resolved config path, and the
detected ffmpeg:
suno 0.1.0 (x86_64-unknown-linux-gnu)
config: /home/alice/.config/suno/config.toml
ffmpeg: 6.1.1 (detected at /usr/bin/ffmpeg)
If the last line reads ffmpeg: not found on PATH, install ffmpeg as below.
ffmpeg
rs-suno shells out to ffmpeg for two jobs:
- transcoding the server-rendered lossless audio to FLAC or ALAC, and
- transcoding a clip’s video preview to an animated WebP cover when you pass
--animated-covers.
You therefore need an ffmpeg build with FLAC, ALAC (the alac encoder and the
ipod/MP4 muxer), and animated-WebP (libwebp_anim) support. Most distribution
packages include all of them. suno runs the first ffmpeg it finds on your
PATH.
Install ffmpeg
| Platform | Command |
|---|---|
| Debian, Ubuntu | sudo apt install ffmpeg |
| Fedora | sudo dnf install ffmpeg |
| Arch | sudo pacman -S ffmpeg |
| macOS (Homebrew) | brew install ffmpeg |
| Windows (winget) | winget install Gyan.FFmpeg |
Check ffmpeg has what you need
Confirm ffmpeg is on your PATH and can encode the formats:
ffmpeg -hide_banner -encoders | grep -E 'flac|alac|libwebp'
You should see the flac and alac audio encoders and the
libwebp/libwebp_anim video encoders. FLAC (the default) or ALAC output needs
ffmpeg; the WebP encoder is only needed if you use --animated-covers. MP3 and
WAV downloads do not need ffmpeg for the audio itself, but FLAC and ALAC do, so
keeping a full ffmpeg build is the simplest path.
Next steps
With the binary and ffmpeg in place, set up your token in
Authentication, then create a config with
suno config init.
Containers
The official image is published at:
ghcr.io/teh-hippo/rs-suno
It contains suno, ffmpeg, CA certificates, and a POSIX shell. This supports
the full audio and artwork feature set without requiring ffmpeg on the host.
The image does not include a scheduler, rclone, or secret-manager clients.
The image is available for Linux amd64 and arm64. Release tags include the
exact release tag, the semantic version, the minor version, and latest.
Prefer an exact version for unattended use.
Quick start with Podman
Create named volumes for the config and library:
podman volume create suno-config
podman volume create suno-library
Create the config interactively:
podman run --rm -it \
-v suno-config:/config \
-v suno-library:/library \
ghcr.io/teh-hippo/rs-suno:latest \
config init
Use /library as the destination when prompted. The config is stored at
/config/suno/config.toml.
Run an additive copy:
podman run --rm \
-v suno-config:/config \
-v suno-library:/library \
ghcr.io/teh-hippo/rs-suno:latest \
copy /library
Run a full mirror:
podman run --rm \
-v suno-config:/config \
-v suno-library:/library \
ghcr.io/teh-hippo/rs-suno:latest \
sync --yes /library
Docker accepts the same commands with docker in place of podman.
Supplying the token
The normal token precedence still applies inside the image. To pass an environment variable without putting its value in the command line:
export SUNO_TOKEN='__client=...'
podman run --rm \
--env SUNO_TOKEN \
-v suno-library:/library \
ghcr.io/teh-hippo/rs-suno:latest \
copy /library
unset SUNO_TOKEN
For a mounted secret, put this in the container config:
[accounts.default]
root = "/library"
token_command = "cat /run/secrets/suno_token"
Then mount a root-only token file:
podman run --rm \
-v suno-config:/config \
-v suno-library:/library \
-v /secure/suno_token:/run/secrets/suno_token:ro \
ghcr.io/teh-hippo/rs-suno:latest \
copy
The image includes sh and BusyBox utilities, so simple token_command
pipelines work. A command that uses bws, op, pass, or another external
client requires that executable to be supplied separately.
Bind mounts and permissions
The image runs as UID and GID 10001 by default. Named volumes inherit the
image directory ownership. For host bind mounts, either make the directories
writable by 10001:10001 or override the container user to match the host.
For rootless Podman:
mkdir -p "$HOME/.config/rs-suno-container" "$HOME/Music/Suno"
podman run --rm \
--userns=keep-id \
--user "$(id -u):$(id -g)" \
-v "$HOME/.config/rs-suno-container:/config" \
-v "$HOME/Music/Suno:/library" \
--env SUNO_TOKEN \
ghcr.io/teh-hippo/rs-suno:latest \
copy /library
Add the appropriate SELinux relabelling option, such as :Z, when the host
requires it.
The manifest, lineage store, audit log, failure log, and last-run state live in the library mount beside the downloaded media. Keep that mount persistent.
Scheduling
The image is a one-shot CLI. Let the host scheduler start it, wait for its exit code, and remove it.
Example systemd service:
[Unit]
Description=Mirror the Suno library
Wants=network-online.target
After=network-online.target
[Service]
Type=oneshot
ExecStart=/usr/bin/podman run --rm --name rs-suno \
-v /srv/rs-suno/config:/config:ro \
-v /srv/rs-suno/library:/library \
-v /srv/rs-suno/secrets:/run/secrets:ro \
ghcr.io/teh-hippo/rs-suno:0.37 \
sync --yes /library
Example timer:
[Unit]
Description=Run the Suno mirror every 30 minutes
[Timer]
OnCalendar=*-*-* *:00,30:00
Persistent=true
[Install]
WantedBy=timers.target
Cron can invoke the same podman run --rm command. Do not run cron or systemd
inside the image.
Proxmox VE
Proxmox VE 9 can import OCI images directly as LXC application containers. Proxmox documents this feature as a technology preview, so validate it with scratch storage before mounting an existing library.
This image has no init system or DHCP client. A suitable one-shot deployment uses:
- an unprivileged application container;
- a host-managed network interface;
- the entrypoint overridden to
/bin/sleep infinity; - persistent config and library mount points; and
- a host systemd service that starts the CT, runs
sunowithpct exec, and stops the CT afterwards.
Create the container before attaching its mount points. The image ships a
/config directory, and Proxmox cannot extract an OCI rootfs onto a path that a
bind mount already occupies, so passing the config mount to pct create fails
while the extractor sets ownership on that directory:
Error while extracting OCI image: ... failed to set ownerships to
uid=10001, gid=10001 for `/var/lib/lxc/<vmid>/rootfs/config`:
Operation not permitted (os error 1)
Give pct create the rootfs and network only, then attach the mount points and
override the entrypoint. Mount points are applied when the container starts
rather than when it is created, so the order costs nothing:
pct create 106 local:vztmpl/rs-suno-0.40.0.tar \
--arch amd64 --ostype unmanaged --hostname rs-suno \
--memory 1024 --swap 256 --cores 2 \
--rootfs local-lvm:2 --unprivileged 1 \
--net0 name=eth0,bridge=vmbr0,ip=dhcp --onboot 0
pct set 106 --mp0 /srv/suno/library,mp=/library,backup=0
pct set 106 --mp1 /srv/suno/config,mp=/config,backup=0,ro=1
pct set 106 --entrypoint "/bin/sleep infinity"
Running suno through pct exec preserves its exit code for the host service
and monitoring. The CT should remain stopped between runs and should not be
treated as an always-on network service.
If native application containers do not meet the deployment’s stability requirements, run the same OCI image with Podman in a suitably configured guest. That fallback has more runtime and nesting overhead, but does not require a different image.
Updating
Pull or import the new version, run suno version, and perform a dry run before
changing the scheduled version:
podman pull ghcr.io/teh-hippo/rs-suno:0.40.0
podman run --rm ghcr.io/teh-hippo/rs-suno:0.40.0 version
Pinning the exact version keeps unattended runs reproducible. The latest and
minor-version tags are convenient for manual testing and controlled update
workflows.
On Proxmox, every durable thing lives on the /library and /config mount
points, so the container’s rootfs holds nothing worth keeping and an upgrade is
a recreate: import the new image, recreate the container, and reattach the
mounts as above. Keep the previous template and a copy of the container config
until the first run has succeeded, which makes a rollback a recreate rather than
a rebuild.
Authentication
Suno has no public API and issues no API keys. rs-suno authenticates the same
way the Suno web app does: with your Clerk __client session cookie. You copy
that cookie into rs-suno once, and it mints the short-lived tokens it needs
from there.
How it works
- You supply your
__clientsession token (a long string). - On each run,
rs-sunosends that token to Clerk (auth.suno.com) and mints a short-lived JSON Web Token (JWT). - It refreshes the JWT automatically, shortly before it expires, so long runs do not stall.
- Only the minted JWT is sent to the Suno API. Your
__clientcookie is sent only to Clerk, never to Suno’s API host.
If authentication fails partway through a run, rs-suno stops that account
cleanly rather than hammering the server, and re-authenticates on the next run.
Get your __client token
The token lives in your browser once you are logged in to Suno. It belongs to
the auth.suno.com origin (not suno.com), and it is marked HttpOnly,
so no script or bookmarklet can read it. Your browser’s developer tools show it
to you directly, on every platform. Pick your browser below and follow the
steps.
Which browser are you using?
- Sign in at suno.com.
- Open DevTools: press F12 (or Ctrl+Shift+I; Cmd+Option+I on a Mac).
- Open Application › Storage › Cookies and select
https://auth.suno.com. - Type
__clientin the Filter box and click the__clientrow. - Copy its Value (right-click the value, or select it and copy).
- Sign in at suno.com.
- Open DevTools: press F12 (or Ctrl+Shift+I).
- Open Application › Cookies and select
https://auth.suno.com. - Type
__clientin the Filter box and click the__clientrow. - Copy its Value.
- Sign in at suno.com.
- Open DevTools: press F12.
- Open the Storage tab › Cookies and select
https://auth.suno.com. - Find the
__clientrow in the list. - Double-click its Value, then copy it.
- Enable the tools once: Safari › Settings › Advanced, then tick Show features for web developers.
- Sign in at suno.com.
- Open Develop › Show Web Inspector (Cmd+Option+I).
- Open the Storage tab › Cookies and select the
auth.suno.comdomain. - Find
__clientand copy its Value.
The __client row shows a tick in the HttpOnly column. That is expected:
the developer tools can display it even though page scripts cannot read it.
Cannot find the auth.suno.com entry? Use the Network tab (works in every browser)
- Open DevTools and switch to the Network tab.
- Reload the page, or open your Library, so requests appear.
- Type
auth.suno.com(orclient) in the filter box. - Click the request to
auth.suno.com/v1/client. - Under Headers › Request Headers, find the Cookie header and copy the whole value.
rs-suno keeps only __client from a full Cookie: header, so pasting the
entire header is fine.
On a phone, the developer tools are hidden, so route the browser through a
capturing proxy (for example Stream
on iOS), sign in, and copy the Cookie header sent to auth.suno.com.
rs-suno accepts the token in whichever form is convenient: the raw value, a
__client=<value> assignment, or the full Cookie: header string. Treat this
value like a password. Anyone with it can access your library.
Provide the token
You can supply the token four ways, in order of precedence:
- The
--token <TOKEN>flag. - The
SUNO_TOKENenvironment variable (or the per-accountSUNO_<LABEL>_TOKEN). - A
token_command, fromSUNO_TOKEN_COMMAND,SUNO_<LABEL>_TOKEN_COMMAND, or your config file.rs-sunoruns the configured shell command, trims stdout, and uses that as the token. This is the recommended way to keep the token in a secret store (see below). - The
tokenfield in your config file, which is the usual fallback place for it.
The interactive setup writes it to the config for you:
suno config init
See Configuration for the file format and for running multiple accounts.
Store the token securely
The token grants full access to your library, so prefer keeping it out of plain
text. Point token_command at your secret store and rs-suno reads the token
on each run, so nothing sensitive sits on disk.
Linux (GNOME or KDE keyring, via libsecret). Store it once, then read it on demand:
secret-tool store --label="Suno __client" service suno account me
[accounts.me]
token_command = "secret-tool lookup service suno account me"
macOS (Keychain). Add the item once (you are prompted for the value), then read it back:
security add-generic-password -a me -s suno-client -w
[accounts.me]
token_command = "security find-generic-password -a me -s suno-client -w"
Windows and cross-platform managers. Bitwarden, 1Password, and pass all
work as a token_command:
[accounts.me]
token_command = "bws secret get <secret-id>" # Bitwarden Secrets Manager
# token_command = "op read op://Private/Suno/client" # 1Password CLI
# token_command = "pass show suno/client" # pass
If you must store the token in the config file instead, restrict its permissions
yourself (for example chmod 600 on Unix), since rs-suno writes the file in
plaintext with the platform’s default permissions. Note that suno config show
already prints [redacted] in place of every token.
Check and refresh a token
Confirm a stored token still works by re-minting its JWT:
suno auth refresh <account>
Or run the fuller diagnostics command:
suno doctor --account <account>
On success it prints the account and its display name. If the account label is
omitted, it uses your single configured account, or --all to check every one.
doctor also reports token-expiry state and the remaining credits balance.
Running suno auth with no subcommand opens this guide in your browser.
When a token stops working (you logged out, or Suno rotated the session), give
the account a fresh __client token. There is no update command, so edit the
account’s token in your config file directly (run suno version to print the
resolved config path) and set it to the new __client=<your-token> value. If
the account uses token_command instead, a rotated secret is picked up on the
next run, because the command runs every time.
suno config add-account <label> is for adding a new account and refuses a
label that already exists, so it is not the way to update an existing token.
Why not a bookmarklet, userscript, or extension?
Short answer: the browser blocks it. The __client cookie is marked
HttpOnly, so no bookmarklet and no Greasemonkey or Tampermonkey userscript
can read it through document.cookie. It is also scoped to the auth.suno.com
origin, not the suno.com page you browse, so a script running on the app could
not see it even if it were readable.
A browser extension can read HttpOnly cookies, but only per engine: Chrome, Firefox, and Safari would each need a separately built and maintained add-on, which is not worth it when the developer tools already expose the value on every platform. That is why the steps above use them.
(The short-lived __session JWT is readable by scripts, but it expires within
minutes and cannot be refreshed without __client, so it is no use as a stored
credential.)
Keeping the token safe
rs-suno never prints your token or a minted JWT:
suno config showredacts every token, printing[redacted].- The
--tokenvalue is never printed in--helpoutput, logs, or errors. - The
__clientcookie is only ever sent to Clerk; the Suno API only ever receives the short-lived JWT.
If you use token_command, remember that rs-suno executes a user-configured
shell command and trusts its stdout as the credential. Keep that command under
your control, avoid echoing secrets to stderr, and treat the command itself as
sensitive configuration.
Never commit a token to source control or paste it into logs or issues.
Configuration
Most people keep their token and destination in a config file so a run is just
suno sync or suno copy. Flags and environment variables can still override
the file for one-off runs and automation.
Precedence: for normal settings, the first value found wins: command-line flag, environment variable, source table, account table, defaults table, then the built-in default.
Config file location
By default the config lives at:
- Linux and macOS:
$XDG_CONFIG_HOME/suno/config.toml, or~/.config/suno/config.toml. - Windows:
%APPDATA%\suno\config.toml.
Point at a different file with --config <PATH> or the SUNO_CONFIG
environment variable. suno version prints the resolved path.
Create a config
The quickest way is the interactive setup:
suno config init
It prompts for an account label (default default), your __client token, and
an optional library root, then writes the file. It will not overwrite an
existing config unless you pass --yes.
Add another account later:
suno config add-account work
Print the current config with every token redacted:
suno config show
Editor validation and autocompletion
rs-suno publishes a JSON Schema for the config file, so an editor can
autocomplete keys, complete enum values (like flac or mirror), show each
setting’s documentation on hover, and flag type errors and unknown keys as you
type. The schema is generated from the same types the parser uses, so it never
drifts from the real format.
In Visual Studio Code, install the
Even Better TOML
extension. Configs written by suno config init already carry a schema
directive on their first line:
#:schema https://teh-hippo.github.io/rs-suno/config.schema.json
For a hand-written or older config, add that line yourself as the first line of
the file. The directive is a TOML comment, so it is ignored by rs-suno and by
any tool that does not understand it. The schema is served from
https://teh-hippo.github.io/rs-suno/config.schema.json, and its source lives in
the repository at docs/src/config.schema.json.
File format
The config is TOML with an optional [defaults] table and one
[accounts.<label>] table per account:
[defaults]
format = "flac"
concurrency = 4
retries = 3
min_newest = 1
animated_covers = false
video_cover_retention = "neither" # neither|webp|mp4|both
animated_cover_quality = 90
animated_cover_max_fps = 24
animated_cover_max_width = 640
animated_cover_compression_level = 4 # 0..4
animated_cover_lossless = false # bit-exact, too large to embed in FLAC
details_sidecar = false
lyrics_sidecar = false
lrc_sidecar = false
lyrics_timing = "line" # line|word
video_mp4 = false
download_stems = false
stem_format = "wav"
naming_template = "{creator}/{album}/{track2} - {creator}-{title} [{id8}]"
character_set = "unicode"
number_singletons = true
[accounts.me]
token = "__client=<your-token>"
root = "/home/alice/music/suno"
account_id = "user_abc123"
lyrics_sidecar = true
lrc_sidecar = true
lyrics_timing = "word"
[accounts.me.sources.liked]
format = "mp3"
[accounts.work]
token_command = "bws secret get <secret-id>"
root = "/home/alice/music/suno-work"
format = "mp3"
[accounts.work.areas]
library = "mirror"
liked = "copy"
playlists = "copy"
[accounts.work.areas.playlist]
"pl_abc123" = "mirror"
[accounts.work.albums]
"1a2b3c4d-0000-0000-0000-000000000000" = "Greatest Hits"
rs-suno writes this config file in plaintext with the platform’s default
permissions; it does not restrict the file further. The config can hold a token,
so prefer keeping secrets out of it with a token_command backed by a secret
manager (see authentication), or restrict the file yourself
(for example chmod 600 on Unix).
Account settings
| Key | Type | Default | Description |
|---|---|---|---|
token | string | The __client session token for the account. | |
token_command | string | A shell command to run for the account token. rs-suno trims stdout and uses it as the token. It is resolved after --token and SUNO_*_TOKEN, but before the stored token. | |
root | path | Default destination directory. Used when a command omits DEST, and required by --all. | |
account_id | string | Optional Suno user id this account must authenticate as. When set, a run refuses (exit 7) before contacting Suno if the token belongs to a different id, a belt-and-braces check alongside the on-disk owner pin. See deletion safety. | |
format | mp3 | flac | alac | wav | flac | Audio format for downloads. flac and alac (Apple Lossless, .m4a) are lossless transcodes of the WAV render; alac is tagged with iTunes atoms, keeping the Suno fields as freeform com.apple.iTunes atoms. Changing an existing library’s format re-encodes the affected files on the next run, and an older rs-suno cannot read a library once a newer format is written. |
concurrency | integer | 4 | Simultaneous downloads. |
retries | integer | 3 | Download retry attempts per clip before it is logged as failed. |
min_newest | integer | 1 | Minimum newest clips kept when a recency filter would otherwise select nothing. |
animated_covers | bool | false | Embed an animated WebP front cover plus the current static JPEG as a managed fallback for clips with a video preview. If the advertised JPEG cannot be fetched, the file is left untouched and retried later. |
video_cover_retention | neither | webp | mp4 | both | neither | Unified control for the animated cover. webp embeds the animated WebP front cover plus the static JPEG fallback, mp4 keeps the raw album cover.mp4 (the video_cover_url byte-for-byte, no transcode), both does both, neither neither. Overrides animated_covers when set. The standalone music video (video_url) is a separate asset with its own video_mp4 toggle. |
animated_cover_quality | integer | 90 | Animated WebP quality (0..100, higher is better and larger). The default 90 scaled to 640 px keeps a typical 5 s cover under the ~16 MiB FLAC picture cap. Ignored when animated_cover_lossless is set. |
animated_cover_max_fps | integer | 24 | Frame-rate cap for animated WebP output. |
animated_cover_max_width | integer | 640 | Width cap in pixels for the animated WebP (no upscaling). The 640 default keeps the embedded cover under the FLAC picture cap; raise it for sharper covers at the risk of a JPEG fallback on FLAC. |
animated_cover_compression_level | integer | 4 | Animated WebP compression effort (0..4, higher is smaller and slower). Capped at 4: effort 6 costs many times the encode time for no size gain. |
animated_cover_lossless | boolean | false | Encode the animated cover losslessly (bit-exact to the source). Far larger than the embedded-cover size cap (a few seconds can be ~145 MB), so a lossless cover always overflows it and the track falls back to the static JPEG; leave it off for embedded covers. |
details_sidecar | bool | false | Also write a plain-text <song>.details.txt beside each audio file, dumping the same metadata that is embedded in the tags plus the song id, duration, and canonical suno.com URL. |
lyrics_sidecar | bool | false | Also write a plain-text <song>.lyrics.txt beside each audio file, holding the same words embedded in the audio. Plain embedded lyrics are automatic; this setting controls only the extra file. A song with no lyrics gets no sidecar. |
lrc_sidecar | bool | false | Also write a <song>.lrc beside each audio file. When Suno has alignment, MP3/WAV also receive an ID3 SYLT frame; otherwise the file falls back to untimed lyrics. Plain USLT/LYRICS/©lyr metadata remains automatic when this is off. |
lyrics_timing | line | word | line | Timed lyric granularity while lrc_sidecar is enabled. line writes one timestamp per line in both LRC and MP3/WAV SYLT. word writes enhanced per-word LRC and word-level SYLT. Changing the value updates existing timed outputs on the next executing run. |
video_mp4 | bool | false | Also download the standalone <song>.mp4 music video beside each audio file, when Suno provides one. A song with no video gets no file. Turning this off leaves existing videos in place; a video is only removed alongside its own audio. |
download_stems | bool | false | Also mirror each song’s already-generated stems into a <song>.stems/ sub-folder beside it. Download-only: it lists and downloads existing stems and never triggers separation or spends credits. A song with no stems gets no folder. Each stem is stored RAW (see stem_format), never transcoded to FLAC. Turning this off leaves existing stems in place; individual stems are only removed when Suno’s authoritative listing no longer contains them, or alongside their own song. |
stem_format | string | wav | Container for downloaded stems: wav (lossless, fetched through the same free WAV render the FLAC pipeline uses) or mp3 (the public CDN file). Stems are stored RAW in whichever container and are never re-encoded to FLAC, even when the song’s own format is FLAC. |
naming_template | string | {creator}/{album}/{track2} - {creator}-{title} [{id8}] | Relative path template. Supported placeholders are {creator}, {handle}, {album}, {title}, {id}, {id8}, {root_id8}, {track} (album track number, e.g. 7), and {track2} (zero-padded to two digits, e.g. 07). An empty placeholder drops the separator run that follows it, and empty path segments are dropped. |
character_set | unicode | ascii | unicode | Character set for filename sanitisation. Unicode preserves valid path characters; ASCII folds names to portable ASCII. |
number_singletons | bool | true | Whether a single-track (lone) lineage album is given a track number. false leaves singletons unnumbered, so the {track2} prefix does not decorate a standalone song. |
sources | table | Optional per-source overrides under [accounts.<label>.sources.<name>]. A source table may set any account key in this table except token, root, account_id, sources, areas, albums, and lead_tracks. | |
areas | table | Optional per-area mirror/copy selection. See Per-area sync/copy modes. | |
albums | table | Optional album-name overrides keyed by lineage root id. See Album name overrides. | |
lead_tracks | array | Optional clip ids (or unique id prefixes) each promoted to track 1 of their lineage album. See Lead tracks. |
Any per-run account key may also be set under [defaults] to apply to every
account. Account-only tables and identity fields (token, root, account_id,
sources, areas, albums, and lead_tracks) cannot be set in [defaults].
Each rendered path component is capped at 80 characters. A longer title is
shortened to fit while the trailing [id8] is preserved, so shortened names stay
unique and never collide; the cut is by character on a character boundary, so a
long title can be trimmed mid-word. Raising this cap is a deferred, opt-in change:
it would rename existing files and needs a byte budget to stay within the
filesystem’s per-component byte limit under UTF-8 (up to four bytes per
character), so the cap is fixed at 80 for now.
token_command and the other per-run settings also work in
[accounts.<label>.sources.<name>], so one source can override an account or
default value when needed.
Security note: token_command runs a user-configured shell command. Keep it
under your control and never rely on untrusted input in the command string.
Per-area sync/copy modes
By default a verb sets the mode for the whole run: sync mirrors, copy adds.
An optional [accounts.<label>.areas] table gives an account a durable per-area
mode instead, so a scheduled suno sync can mirror some areas and only add to
others:
[accounts.me.areas]
library = "mirror" # "mirror", "copy", or "off"
liked = "copy" # "mirror" or "copy"
playlists = "copy" # default mode for every playlist
[accounts.me.areas.playlist]
# Per-playlist overrides, keyed by playlist id from Suno.
pl_abc123 = "mirror"
librarytakesmirror,copy, oroff.offis the only way to let a mirror delete files that exist only in your library and nowhere else, so it drops the implicit copy protector described in deletion safety. It cannot be set by a flag, only here.likedandplayliststakemirrororcopy.playlistssets the default for every playlist;[areas.playlist]overrides individual playlists by id.- An area you do not list is simply not selected by a config-driven run.
A scope flag (--liked or --playlist) always overrides [areas] for that run,
and an unknown key (for example libary instead of library) is a parse error
rather than a silent no-op.
Album name overrides
Album names are derived from lineage: a clip folders under its root ancestor’s
title, or its own title when it is a root (see
lineage and albums). When a derived name is undesirable
(for example the earliest version of a song carried a strange working title
before you settled on a proper one), an optional
[accounts.<label>.albums] table renames an album by its stable lineage root
id:
[accounts.me.albums]
# <root_id> = "Preferred Name"
"1a2b3c4d-...-rootid" = "Greatest Hits"
- The key is the album’s lineage root id, not the derived title. The root id
is stable, whereas the derived title is exactly what you are replacing. Find it
from the
[{root_id8}]suffix in a folder name, theSUNO_LINEAGEtag’sRoot <id>line, or the lineage store. - The override is account-wide, like lineage itself, so it is set on the account and never per-source.
- A blank or whitespace-only value is ignored, so a stray key can never blank an album.
- The preferred name flows consistently into the folder path, the
ALBUMtag, the change hash, and album-art paths, and it also settles name collisions: two distinct roots renamed onto the same album are still kept apart by the[{root_id8}]suffix.
On the next sync, an album rename moves the existing folder and all its
contents (member tracks, folder.jpg, cover.webp / cover.mp4) to the new
path and prunes the emptied old directory. It re-tags each track in place from
the local file; it does not re-download the audio. Deletion safety holds
throughout: the rename is a move, never a delete-then-redownload, and nothing is
deleted on an empty, failed, or partial listing.
Lead tracks
Within an album, tracks are numbered by when each version was made (see
track numbers). To pin a specific version
as track 1 — for example a main version you edited after generating its
remixes, so it was made later — list it under lead_tracks:
[accounts.me]
lead_tracks = [
"b320f4cf", # the 8-char code from a file name
"c6f6a1a5-7c6a-4424-9249-3fa847dc0a3a", # or the full clip id
]
- Each entry is a clip id, or a unique prefix of one such as the
[b320f4cf]code shown in every file name. The album is inferred from the clip’s lineage root, so you never name the album here. - The flagged clip becomes track 1; the remaining tracks keep their creation order and shift down.
- It is account-wide, set on the account and never per-source.
- One lead per album. An entry that matches no downloaded clip, or matches more than one, is reported on the run and ignored.
Set number_singletons = false if you would rather leave lone (single-track)
albums unnumbered.
Multiple accounts
Each account has its own token and its own root. Account roots must not nest
inside one another: a config where one account’s root is a parent of another’s
is rejected, so two libraries can never share or overwrite files. Run one
account with --account <label>, or every account in isolation with --all
(each writes to its own root).
If exactly one account is configured, it is used automatically and you can omit
--account.
Precedence
For every normal setting, the first value found wins, in this order:
- Command-line flag (for example
--format wav). - Environment variable (per-account
SUNO_<LABEL>_*before globalSUNO_*). - Source table (
[accounts.<label>.sources.<name>]). - Account table (
[accounts.<label>]). - Defaults table (
[defaults]). - The built-in default.
Token resolution has one extra step between environment variables and the stored account token:
--tokenSUNO_<LABEL>_TOKENorSUNO_TOKENSUNO_<LABEL>_TOKEN_COMMAND,SUNO_TOKEN_COMMAND, ortoken_commandresolved from source, account, then defaults[accounts.<label>].token
Environment variables
| Variable | Equivalent | Notes |
|---|---|---|
SUNO_TOKEN | --token | Also SUNO_<LABEL>_TOKEN for one account. |
SUNO_TOKEN_COMMAND | token_command | Also SUNO_<LABEL>_TOKEN_COMMAND for one account. |
SUNO_ACCOUNT | --account | |
SUNO_CONFIG | --config | |
SUNO_DRY_RUN | --dry-run | |
SUNO_YES | --yes | |
SUNO_FORMAT | --format | mp3, flac, alac, or wav. |
SUNO_CONCURRENCY | --concurrency | Integer, default 4. |
SUNO_RETRIES | --retries | |
SUNO_MIN_NEWEST | --min-newest | |
SUNO_ANIMATED_COVERS | --animated-covers | true or false. |
SUNO_VIDEO_COVER_RETENTION | --video-cover-retention | neither, webp, mp4, both. |
SUNO_ANIMATED_COVER_QUALITY | --animated-cover-quality | 0..100. |
SUNO_ANIMATED_COVER_MAX_FPS | --animated-cover-max-fps | Positive integer. |
SUNO_ANIMATED_COVER_MAX_WIDTH | --animated-cover-max-width | Integer width cap in pixels. |
SUNO_ANIMATED_COVER_COMPRESSION_LEVEL | --animated-cover-compression-level | 0..4. |
SUNO_ANIMATED_COVER_LOSSLESS | --animated-cover-lossless | true or false. |
SUNO_DETAILS_SIDECAR | --details-sidecar | true or false. |
SUNO_LYRICS_SIDECAR | --lyrics-sidecar | true or false. |
SUNO_LRC_SIDECAR | --lrc-sidecar | true or false. |
SUNO_LYRICS_TIMING | --lyrics-timing | line or word. |
SUNO_VIDEO_MP4 | --video-mp4 | true or false. |
SUNO_DOWNLOAD_STEMS | --download-stems | true or false. |
SUNO_STEM_FORMAT | --stem-format | wav or mp3. |
SUNO_NAMING_TEMPLATE | --naming-template | Supported placeholders: {creator}, {handle}, {album}, {title}, {id}, {id8}, {root_id8}, {track}, {track2}. |
SUNO_CHARACTER_SET | --character-set | unicode or ascii. |
The configured format is strict for clips owned by the authenticated account. If Suno withholds an owned clip’s lossless WAV render, new lossless work fails rather than falling back to MP3. An existing MP3 awaiting an upgrade remains until a verified lossless replacement is written, then it is removed.
Suno does not allow an account to request WAV conversion for a clip whose
recorded user_id belongs to another account, including some remixes and covers
that retain the source account’s ownership. Those non-owned clips use Suno’s
native MP3 as their terminal format. An already-downloaded non-owned lossless
file is preserved and never downgraded.
Per-account variants use the account label upper-cased with hyphens turned into
underscores, so account my-lib reads SUNO_MY_LIB_TOKEN,
SUNO_MY_LIB_FORMAT, and so on. A per-account variable overrides the matching
global one.
Running without a config
You do not need a config file for the read-only and one-off commands. With
--token (or SUNO_TOKEN) set and no config present, rs-suno runs against a
single implicit account, which is handy for ls, lsjson, and fetch.
Commands reference
suno [OPTIONS] <COMMAND>
| Command | Purpose |
|---|---|
sync | Mirror your library to a directory, including deletions. |
copy | Download and update, never delete. |
check | Authoritatively report what sync or copy would change without modifying the library. |
ls | List clips in a readable table. |
lsjson | List clips as newline-delimited JSON. |
fetch | Download one clip by ID or URL. |
config | Manage the configuration file. |
auth | Manage authentication. |
doctor | Diagnose environment, config, auth, and credits. |
version | Print version and environment information. |
completions | Emit a shell completion script. |
Global options
These apply to every command and may appear before or after the subcommand.
| Flag | Short | Env | Description |
|---|---|---|---|
--account <LABEL> | SUNO_ACCOUNT | Run against one configured account. | |
--all | Run every configured account in isolation (sync/copy). Conflicts with --account. | ||
--config <PATH> | SUNO_CONFIG | Path to the config file. | |
--dry-run | -n | SUNO_DRY_RUN | Report changes without writing to disk or deleting. |
--verbose | -v | Increase verbosity. Repeatable (-vv). | |
--quiet | -q | Decrease verbosity. Repeatable (-qq). | |
--yes | -y | SUNO_YES | Skip confirmation prompts (such as a destructive sync). |
--token <TOKEN> | SUNO_TOKEN | The __client token. Never printed. Overrides config and env. |
Verbosity
Verbosity is relative to the default level of 0.
| Level | Flag | Output |
|---|---|---|
| Silent | -qq | Errors only. |
| Quiet | -q | Per-run summary, warnings, and errors. |
| Default | Summary plus a single progress line. | |
| Verbose | -v | A line per clip as it is downloaded, tagged, renamed, skipped, or deleted, and a line per sidecar written or removed. |
Machine-readable output (ls rows and lsjson objects) goes to stdout;
progress and summaries go to stderr, so a piped lsjson stays clean.
sync
Mirror selected clips into a destination: download new clips, update tags and artwork, rename or re-encode changed files, and remove local files whose clips have left your library. Deletion is governed by strict safety rules; see Sync, copy and deletion safety.
suno sync [OPTIONS] [DEST]
DEST is the local directory to mirror into. If omitted, the account’s
configured root is used.
| Flag | Default | Description |
|---|---|---|
--format <mp3|flac|alac|wav> | flac | Audio format for downloads. alac is Apple Lossless (.m4a), tagged with iTunes atoms. WAV carries full ID3v2.4 tags (lyrics, art, and all SUNO fields) embedded in a RIFF id3 chunk. |
--limit <N> | Mirror only the N most recent clips. | |
--since <SPEC> | Mirror clips newer than 7d, 2w, or last-run. | |
--liked | off | Scope the run to your liked songs only (additive unless --mode mirror). |
--playlist <ID_OR_NAME> | Scope the run to a playlist, by id or name (repeatable; additive unless --mode mirror). | |
--mode <mirror|copy> | scoped default: copy | Select the mode for scoped areas: mirror arms deletion, copy stays additive. Only meaningful with --liked, --playlist, or an [areas] config. |
--min-newest <N> | 1 | Newest clips always kept when a recency filter applies. |
--retries <N> | 3 | Download retry attempts per clip. |
--concurrency <N> | 4 | Simultaneous downloads. |
--animated-covers | off | Embed an animated WebP front cover plus the current static JPEG as a managed fallback for clips with a video preview. |
--video-cover-retention <neither|webp|mp4|both> | neither | Unified animated-cover control: webp embeds the animated WebP front cover plus the static JPEG fallback, mp4 keeps the raw cover.mp4 (no transcode), both does both. Overrides --animated-covers; the standalone music video stays on --video-mp4. |
--animated-cover-quality <N> | 90 | Animated WebP quality (0..100). The default fits the ~16 MiB FLAC picture cap; ignored with --animated-cover-lossless. |
--animated-cover-max-fps <N> | 24 | Animated WebP frame-rate cap. |
--animated-cover-max-width <PIXELS> | 640 | Animated WebP width cap (raise for sharper covers at the risk of a JPEG fallback on FLAC). |
--animated-cover-compression-level <N> | 4 | Animated WebP compression effort (0..4). |
--animated-cover-lossless | off | Encode the animated cover losslessly (bit-exact). Far larger than the embedded-cover size cap (a few seconds can be ~145 MB), so a lossless cover always falls back to the static JPEG; leave it off. |
--allow-account-change | off | Re-pin this library to the authenticated account. The run is additive and deletes nothing. |
--details-sidecar | off | Also write a plain-text .details.txt sidecar next to each song. |
--lyrics-sidecar | off | Also write a plain-text .lyrics.txt sidecar next to each song. Plain lyrics inside the audio are automatic. |
--lrc-sidecar | off | Also write a synced .lrc sidecar next to each song. MP3 and WAV also get a timed SYLT frame when Suno has alignment. |
--lyrics-timing <line|word> | line | With --lrc-sidecar (or configured LRC output), select one timestamp per line, or enhanced per-word LRC plus word-level MP3/WAV SYLT. Changing the mode updates existing timed lyrics on the next executing run. |
--video-mp4 | off | Also download the standalone .mp4 music video beside each song, when available. |
--download-stems | off | Also mirror each song’s already-generated stems into a <song>.stems/ sub-folder. Download-only: it lists and downloads existing stems and never triggers separation or spends credits. |
--stem-format <wav|mp3> | wav | Container for downloaded stems. Stems are stored RAW and are never transcoded to FLAC. |
--naming-template <TEMPLATE> | {creator}/{album}/{track2} - {creator}-{title} [{id8}] | Relative path template. Placeholders: {creator}, {handle}, {album}, {title}, {id}, {id8}, {root_id8}, {track} (album track number, e.g. 7), {track2} (zero-padded to two digits, e.g. 07). |
--character-set <unicode|ascii> | unicode | Character set for filename sanitisation. |
When sync would delete files and --yes was not passed, it lists them and
asks for confirmation on an interactive terminal. Without a terminal it refuses
and asks you to pass --yes or use copy.
Scoped runs (--liked and --playlist)
--liked and --playlist narrow a run to a subset of your library. --playlist
takes a playlist id or name, is repeatable, and resolves against your own
non-trashed playlists (shared and trashed playlists are not visible); an unknown
or ambiguous value fails and prints the visible playlists. --playlist liked is
an alias for --liked. Clips that appear in more than one scope are downloaded
once.
A bare scoped run is additive: --liked and --playlist default to copy,
so like --limit and --since they never delete. Adding --mode mirror arms
deletion for the scope, but rs-suno then also lists your whole library as an
invisible copy protector, so a scoped mirror deletes only the orphans of the
scope it was pointed at and never a file that lives elsewhere in your library
(see deletion safety). A scoped mirror
maintains the .m3u8 only for the playlists it enumerated; a full-library sync
maintains every playlist’s .m3u8. For a durable per-area mode, use the
[areas] config (see the configuration guide).
# Mirror only your liked songs:
suno sync /music/suno --liked --mode mirror
# Mirror two playlists by name and id:
suno sync /music/suno --playlist "Neon Nights" --playlist 6f1e...c3
# Mirror everything to the configured root, in FLAC:
suno sync
# Mirror the last two weeks to a specific directory, in MP3:
suno sync /music/suno --format mp3 --since 2w
copy
Additive download and update: same selection and flags as sync, but it never
deletes and never prompts.
suno copy /music/suno-archive
check
Report what sync or copy would do without modifying the library. It accepts
every sync flag.
suno check [OPTIONS] [DEST]
| Flag | Description |
|---|---|
--exit-code | Exit 1 when changes are pending, 0 when up to date (useful in CI). |
suno check /music/suno --exit-code
check reads the managed files and may make the same read-only upstream lyric
or artwork requests that the corresponding run requires. It does not modify the
managed library or persist refreshed state. It uses the run lock while planning
when the destination is writable, refuses while an executing run holds that
lock, and can still inspect a read-only destination. If a managed file or required upstream
value cannot be verified, check reports it as unverified and exits with the
applicable partial or transient code rather than claiming the library is up to
date.
ls
List selected clips as a tab-separated table (ID, DURATION, TITLE,
TAGS). The title is truncated to 48 characters. A header prints only to a
terminal, so piping stays clean.
suno ls [OPTIONS]
| Flag | Default | Description |
|---|---|---|
--liked | off | List only liked clips. |
--limit <N> | Stop after the first N clips. | |
--since <SPEC> | Show clips newer than 7d, 2w, or last-run. | |
--format <text|json> | text | Output format; json matches lsjson. |
suno ls --limit 20
suno ls --liked | column -t -s $'\t'
lsjson
List selected clips as newline-delimited JSON (one object per line). Equivalent
to ls --format json, and it accepts the same flags. The schema is additive for
scripting: fields are not renamed, and new ones are only appended. The
always-null legacy lineage fields album_title, root_ancestor_id, and
lineage_status were removed once confirmed dead (Suno stopped sending them);
no live response ever populated them. Every remaining field is present on every
object; nullable fields are null when Suno supplied no value.
| Field | Type | Description |
|---|---|---|
id | string | Suno clip UUID. |
title | string | Display title; Untitled when blank. |
status | string | For example complete. |
duration | number | Seconds. |
created_at | string | ISO 8601 UTC. |
is_liked | bool | Whether the clip is liked. |
has_vocal | bool | Whether the clip has a vocal track. |
clip_type | string | For example gen or edit. |
tags | string | Comma-separated style tags. |
prompt | string | null | User prompt. |
gpt_description_prompt | string | null | Auto-generated description prompt. |
lyrics | string | null | Lyrics text; null if instrumental. |
model_name | string | For example chirp-v4. |
major_model_version | string | For example v4. |
display_name | string | Account display name. |
handle | string | Account handle. |
edited_clip_id | string | null | Source clip if this is a remix. |
audio_url | string | Audio CDN URL. |
image_url | string | Cover image URL. |
image_large_url | string | Large cover image URL. |
video_url | string | Clip video URL. |
video_cover_url | string | Video cover image URL. |
# Titles of liked clips:
suno lsjson --liked | jq -r '.title'
suno-index.json
A sync or copy that fully enumerates the library writes a single
suno-index.json at the library root: a durable, machine-readable catalogue of
every mirrored clip, for offline scripting. Unlike the streamed lsjson and the
internal .suno-manifest.json engine state, it is a visible file that persists
between runs and reflects the files actually on disk.
The write is best-effort: a failure to write the index never fails an otherwise
successful mirror, because it is regenerable from the manifest, the lineage
store, and the next run. A narrowed run (--limit or --since) does not write
it, so a rich index from a full run is never regressed to a windowed subset.
The document is a pretty-printed object carrying a schema_version and a
clips array in clip-id order. The schema is stable for scripting: fields are
only added, never removed or renamed. Genuinely unknown live-only fields are
null, never an empty string or 0.
| Field | Type | Description |
|---|---|---|
id | string | Suno clip UUID (the manifest key). |
path | string | Forward-slash library-relative path to the audio file. |
format | string | flac, mp3, alac, or wav. |
size | number | File size in bytes. |
title | string | Live title, else the archived title, else Untitled. |
artist | string | null | Live display name (Suno when blank); null when not seen this run. |
handle | string | null | Live account handle; null when not seen this run. |
album | string | Raw logical album title; may differ from the sanitised album folder in path. |
root_id | string | Resolved lineage root id, or the clip’s own id when it is a root. |
created_at | string | null | Archived creation timestamp; null when unknown. |
duration | number | null | Seconds; null when not seen this run. |
tags | string | null | Comma-separated style tags; null when not seen this run. |
# Paths of every FLAC in the mirror:
jq -r '.clips[] | select(.format == "flac") | .path' suno-index.json
fetch
Download one clip by ID or URL to a path outside any mirrored library. The clip
is written directly and is never tracked or reconciled, so fetch never affects
a sync destination.
suno fetch [OPTIONS] <ID_OR_URL> [DEST]
ID_OR_URL is a clip UUID or a Suno URL containing it. DEST defaults to the
current directory; when it is a directory the file is named <id>.<ext>.
FLAC, ALAC, and WAV require Suno’s paid WAV-render entitlement. If the account
cannot currently use that entitlement, an auto-named fetch falls back to native
MP3 and reports the .mp3 path. An explicit file path, including --output,
remains strict and fails rather than writing MP3 bytes under a lossless name.
Every format receives its normal embedded tags, including plain lyrics. When
the clip payload omits lyrics, fetch checks Suno’s aligned-lyrics endpoint and
uses its plain text. A temporary lookup failure warns but does not fail the
audio download.
--lyrics-timing opts this standalone download into timed lyrics. It writes an
adjacent <audio-base>.lrc; MP3 and WAV also receive a matching ID3 SYLT
frame. Line mode is the broadly compatible form. Word mode uses enhanced LRC
word timestamps and karaoke-style SYLT. FLAC and ALAC use the sidecar only.
| Flag | Short | Default | Description |
|---|---|---|---|
--format <mp3|flac|alac|wav> | flac | Audio format. | |
--output <PATH> | -o | Explicit output file path, overriding DEST and auto-naming. | |
--lyrics-timing <line|word> | Opt into timed lyrics at the selected granularity and write an adjacent .lrc. |
suno fetch 3f2a1b4c-aaaa-bbbb-cccc-ddddeeee0001
suno fetch https://suno.com/song/3f2a1b4c-... -o track.flac
suno fetch 3f2a1b4c-aaaa-bbbb-cccc-ddddeeee0001 --lyrics-timing word
config
Manage the config file. See Configuration for the file format.
suno config [OPTIONS] <COMMAND>
| Subcommand | Usage | Purpose |
|---|---|---|
init | suno config init | Interactively create a new config file. |
add-account | suno config add-account [LABEL] | Add a new account entry to an existing config file. |
show | suno config show | Print the current config with tokens redacted. |
There is no config path or config edit command in v0.22.0. Use
suno version to print the resolved config path, then edit the TOML file with
your editor.
auth
suno auth
suno auth refresh [ACCOUNT]
With no subcommand, suno auth opens the online
Authentication guide in your default browser, and prints
the URL so it is available on a headless host.
suno auth refresh re-mints an account’s JWT to confirm its stored token still
works. With no account it uses your single configured account, or --all to
check every one.
refresh is the only auth subcommand. There is no auth status or auth logout command; provide or update the Clerk __client token through
Configuration.
doctor
suno doctor
Report the current environment and config state, then for the selected account
live-check authentication and the remaining credits balance. It prints whether
SUNO_CONFIG, SUNO_TOKEN, and SUNO_<ACCOUNT>_TOKEN are set, whether the
config parses, the resolved per-account settings with tokens redacted, and the
detected ffmpeg.
With --account <label> it checks one configured account; with --all it
checks every configured account in turn. Without a config it can still diagnose
an env-only setup using SUNO_TOKEN or --token.
version
suno version
Print the build version and target, the resolved config path, and the detected
ffmpeg.
completions
suno completions <SHELL>
Emit a shell completion script to stdout. SHELL is one of bash, zsh,
fish, powershell, or elvish. Redirect it to the location your shell reads.
suno completions bash > ~/.local/share/bash-completion/completions/suno
Summaries
A sync or copy run ends with a summary on stderr:
Sync complete: me
downloaded 12
tagged 3
renamed 1
deleted 2
sidecars 8
skipped 129
failed 0
total 155
Duration: 43.2s
The sidecars line counts external artifact files written this run (.lrc,
.lyrics.txt, .details.txt, cover art, .mp4, and playlists); sidecar
removals are counted under deleted with the audio deletes. So enabling a
sidecar on an already-synced library reports the files it writes rather than
hiding them as skipped.
A --dry-run or check run reports the pending counts instead, and makes no
changes:
Dry run: me (no changes made)
to download 12
to tag 3
to rename 1
to delete 2
sidecars 8
up to date 129
unverified 0
total 155
Sync, copy and deletion safety
sync is the reason rs-suno exists: it keeps a local directory as a faithful
mirror of your Suno library, and it does so without ever putting your files at
risk. This chapter explains what a run does and the rules that make deletion
safe.
The mirror model
copyis additive. It downloads new clips and updates existing files, but it never deletes anything.syncis a full mirror. It does everythingcopydoes, and it also removes local files whose clips are no longer in your library.
Both verbs share the same selection and the same incremental engine. The only difference is whether local files may be removed.
Choosing the mode per area
By default the verb sets the mode for the whole run: sync mirrors, copy adds.
Two mechanisms let you choose the mode for a specific area instead:
--mode <mirror|copy>overrides the mode for a single run. It pairs with a scope flag, sosuno sync --playlist "Focus" --mode mirrormirrors just that playlist whilesuno sync --liked --mode copytops the liked feed up additively. With no scope flag,--mode mirrormirrors the whole library and--mode copyis additive, exactly like the verb.- The
[areas]config sets a durable per-area mode for an account: alibrary,liked, and per-playlistmirrororcopy, pluslibrary = "off"(see the configuration guide). Config-driven areas apply whenever you run without a scope flag; a scope flag always wins for that run.
An area set to mirror can delete; an area set to copy only ever adds. The
deletion-safety rules below apply to every area no matter how its mode was
chosen.
Scoped mirrors keep the rest of your library safe
A bare --liked or --playlist X is copy by default, so it deletes nothing.
Arming deletion for a scope needs --mode mirror (or a mirror area in config).
When any armed area is a mirror and the library is not itself a selected
area, rs-suno still lists your whole library as an invisible copy
protector for that run. That protector holds every library-exclusive file, so a
scoped mirror can delete only the orphans of the scope it was pointed at, never a
file that lives elsewhere in your library. The protector lists the full library
unfiltered, so a stray --limit or --since cannot shrink it and silently widen
what a mirror may delete.
The one way to delete library-exclusive files deliberately is library = "off"
in an [areas] config, which drops the protector. It is only expressible in
config, never as a flag, so it can never happen by accident.
What a run does
Each run works in three stages:
- Select. Enumerate the library, liked feed, and playlists, then apply any
--limitor--sincefilter. - Plan. Compare the desired state against a manifest of what is already on disk, and decide a set of actions.
- Execute. Apply the actions: download, re-encode, retag, rename, write
artwork, and (for
sync) delete.
A --dry-run, or the check command, stops after the plan and prints what it
would do, touching nothing.
Incremental by default
rs-suno keeps a manifest beside the destination and only does work that is
needed:
- Skip unchanged. A clip whose metadata hash, artwork hash, and file size all match the manifest is left alone.
- Retag and re-art in place. When only tags or artwork changed, the file is updated in place. The audio is not downloaded again.
- Rename in place. When only the target path changed (for example a retitled clip), the existing file is moved, not re-downloaded.
- Re-encode on format change. Changing
--formatreplaces the file by re-encoding, without pre-deleting the old one. - Re-download missing or empty files. A clip whose local file is absent, or is zero bytes, is treated as missing and downloaded again.
This makes repeat runs fast and cheap, which is what makes frequent scheduled runs practical.
Deletion safety
Deletion is the one irreversible action, so it is hedged with several independent rules. All of them must agree before a single file is removed.
Delete only what has truly left every source
A file is a candidate for deletion only when its clip is absent from every mirror source feeding that destination. A clip that is still present in any source is kept. In addition:
copyalways wins. A clip held by acopysource is never deleted, even if asyncsource no longer lists it.- Private clips are preserved. A clip marked private is never deleted.
- Trashed counts as removed. A clip you have trashed in Suno is treated as
gone and its local file is removed (unless a
copysource or the private rule preserves it).
The fully-enumerated gate
rs-suno will not delete anything unless the listing it is comparing against was
fully enumerated: the feed drained completely, with no transport error and
no truncation, and no narrowing filter was applied. In practice this means:
- A network or listing error disables deletion for that run.
--limitand--sincenarrow the listing, so a run using either never deletes. Use them freely for quick top-ups without any deletion risk.--likedand--playlistare additive by default, so a bare scoped run never deletes. Adding--mode mirrorarms deletion for that scope, but the implicit full-library copy protector (described above) still shields every file outside the scope. A scoped mirror maintains the.m3u8only for the playlists it actually enumerated; a full-librarysyncmaintains every playlist’s.m3u8as before.
An empty mirror area is never treated as authoritative: a legitimately empty feed is indistinguishable from a dropped listing, so it suppresses deletion for the whole run rather than risk deleting everything the area held.
A missing clip in a partial or filtered listing might still exist upstream, so it is never read as a deletion.
The mass-deletion abort
As a final backstop, a run aborts before deleting when the listing looks catastrophically wrong:
- An empty listing that would delete your whole library is refused.
- A delete that would remove at least half of a non-trivial library is refused.
Either abort exits with the safety code (7) and removes nothing. If you really
do intend a mass deletion, confirm it explicitly with --min-newest 0 --yes. A
stored min_newest = 0 or a habitual --yes alone will not disarm the
empty-listing guard.
The account identity guard
The mass-deletion abort still has a blind spot: it is disarmed by --min-newest 0 --yes, and it does not fire on a small library (below the mass-deletion
floor). Both leave a gap where pointing one account’s library at another
account’s token would make every local file look absent from the source and be
deleted.
To close that gap, each library remembers the account it belongs to. On its
first run, suno pins the library to the authenticated account (trust on first
use): a fresh, empty destination is adopted outright, and an existing library is
adopted only when the account’s listing overlaps the clips already on disk.
Once pinned, every later sync, copy, and check compares the authenticated
account against the pin and refuses to run on a mismatch, exiting with the
safety code (7) and touching nothing:
error: this library belongs to Alice (id user_abc) but the token authenticates
as Bob (id user_xyz). Refusing to run to protect the library. Pass
--allow-account-change to re-pin it to the authenticated account, or use a
different destination.
If you genuinely mean to move a library to a different account, pass
--allow-account-change. That run re-pins the library to the authenticated
account and runs additively (it deletes nothing, like copy), so it can
never wipe the previous account’s files in the same step. A subsequent normal
sync, now pinned to the new account, mirrors as usual. The flag applies only
to an executing sync or copy; check and --dry-run reject it (exit 2)
because they never persist a pin. The same flag also adopts an unpinned legacy
library whose listing shares no clips with the files on disk, in case a genuine
account shares nothing with an older download. The pin lives in the lineage
store (.suno-lineage.json); a pin, adoption, or re-pin is recorded in
.suno-audit.log.
For a belt-and-braces check you can also set account_id in an account’s config
(see the configuration guide): the run then refuses before contacting Suno if
the token authenticates as a different id.
The confirmation prompt
When a sync would delete files and you did not pass --yes:
- On an interactive terminal, it lists the files and asks
Proceed? [y/N]. Anything other thanyoryesaborts with no changes. - Without a terminal (a pipe, cron, or CI), it refuses and tells you to pass
--yesor usecopy.
suno sync will delete 3 local file(s) that are no longer in the source:
me/Weather/me-Old Draft [b3c4d5e6].flac
...
Proceed? [y/N]
Tidying up
After removing files, sync prunes any directories left empty, so the tree does
not accumulate stale folders. The destination root itself is always kept.
Per-song sidecars
The optional per-song sidecars follow the same gated deletion path as the audio, but they differ in when an on-disk file is removed after the feature is turned off:
- Static cover (
cover.jpg). A clip’s art URL can be missing for a run (the feed omits it, or a fetch fails), so an absent cover is treated as UNKNOWN and the existing.jpgis kept. It is only removed when its whole song leaves every source and the audio is deleted with it. - Animated cover (
.webp) — retired. Earlier versions wrote a per-song<track>.webp; the animated cover is now embedded in the audio file instead. Any leftover.webpsidecar is cleaned up (deleted) on the next deletion-enabled run, through the same gate as every other delete. - Details (
.details.txt). The details dump is always renderable, so once the feature is off the sidecar can only be intentionally unwanted. Turningdetails_sidecaroff therefore removes the existing.details.txton the nextsync, through the same fully-enumerated and preserve gates as any deletion. - Lyrics (
.lyrics.txt). The lyrics file is only written when a song actually has lyrics, so an absent lyrics sidecar is ambiguous: it could mean the feature is off, or that a single feed read returned empty lyrics. To avoid deleting real lyrics on a transient empty read, lyrics opt out of removal the same way covers do. Turninglyrics_sidecaroff leaves existing.lyrics.txtfiles in place; delete them by hand if you want them gone. - Synced lyrics (
.lrc). The.lrcsidecar is written only when a song has lyrics Suno can align, exactly like.lyrics.txt, so an absent.lrcis ambiguous (the feature is off, the song is an instrumental, or a fetch failed) and it opts out of removal the same way covers do. Turninglrc_sidecaroff leaves existing.lrcfiles and timed frames in place. When alignment is available,lyrics_timingselects line or enhanced word timestamps and MP3/WAV receive a matchingSYLTframe. Changing the mode updates existing timed outputs safely; otherwise the file falls back to untimed lyrics. An instrumental writes no file. - Music video (
.mp4). The standalone video is a large binary and its source URL can be transiently absent, so it opts out of removal the same way covers do. Turningvideo_mp4off leaves existing.mp4videos in place; a video is only removed when its whole song leaves every source and the audio is deleted with it. - Playlist image (
<playlist>.jpg). Suno’simage_urlis mirrored beside the generated.m3u8. A failed or omitted image fetch keeps the prior cover; rename and removal happen only under the fully enumerated playlist delete gate. - Stems (
<song>.stems/). Whendownload_stemsis on, a song’s existing stems are mirrored into a sibling.stemssub-folder, tracked per stem by a stable key so individual stems add, rewrite, and remove independently (never a whole-folder delete). Stems are download-only and read-only: the mirror reads the stem count (GET /api/clip/{id}/stems/pages), pages the listing (GET /api/clip/{id}/stems?page=N), and downloads each stem, and never triggers separation or spends credits. Each stem is stored RAW: with the defaultstem_format = "wav"the lossless WAV is fetched through the same freeconvert_wavrender the FLAC pipeline uses (0 credits), and withstem_format = "mp3"the public CDN MP3 is downloaded directly. A stem is never transcoded to FLAC, even for a FLAC song. Stems are the deliberate exception. A stem is removed only when Suno’s authoritative listing for the song no longer contains it, or alongside its own song when the audio is deleted (which also prunes the emptied.stemsfolder). A listing is authoritative only when its whole page set drains after returning at least one stem; a disabled, failed, partial,400, or empty listing is never read as “no stems”, so existing stems are kept.
Whichever the case, a sidecar is only ever deleted through the shared gate, so an incomplete listing or a preserved (private or copy-held) song never loses one.
Robustness
Beyond deletion, several rules protect an in-progress run:
- One run at a time. A
syncorcopytakes an exclusive lock (.suno.lock) on the destination, so two runs cannot corrupt the same library. - Atomic writes. Files are written to a temporary sibling and renamed into place, so an interrupted write never leaves a half-written file.
- Size verification. A download whose byte count does not match what the server promised is rejected as a truncated transfer and retried.
- Rate-limit backoff. A
429response is retried with exponential backoff that honours the server’sRetry-Afterheader. - Resumable. Progress is recorded as it happens, so an interrupted run simply continues on the next run. This is what makes unattended cron or systemd runs safe.
Failure handling
Failures are classified so one bad clip never derails a whole run:
- Authentication failure stops that account cleanly and re-authenticates on the next run.
- Lossless output unavailable fails the affected action. A new FLAC, ALAC, or WAV target is left absent rather than replaced with MP3. An existing MP3 awaiting an upgrade remains readable until a verified lossless file is committed, then the MP3 is removed atomically. The non-zero run retries on the next schedule and makes stale credentials visible to monitoring.
- Non-owned clip uses Suno’s native MP3 because the WAV conversion endpoint is restricted to the clip’s recorded owner. This is deterministic rather than a temporary fallback. Any existing lossless copy is preserved and never downgraded.
- Transient failure (a timeout, a
5xx, a rate limit) is retried up to--retriestimes, then recorded and skipped. - A single clip’s failure never aborts the run. Other clips still download, and the failure is reported in the summary and log.
What a run leaves behind
Alongside the mirrored audio, a run keeps a few dotfiles at the destination, plus one visible index file:
| File | Purpose |
|---|---|
.suno-manifest.json | The record of what is on disk, used for incremental runs. |
.suno-lineage.json | The durable archive of resolved remix and edit lineage. |
.suno-last-run | Timestamp used by --since last-run. |
.suno-audit.log | Append-only log of every deletion and rename. |
.suno-failures.log | Append-only log of clips that failed after all retries. |
.suno.lock | Present only while a run is active. |
suno-index.json | A visible, machine-readable catalogue of the mirror for scripting; written best-effort on a fully-enumerated run. |
These engine state files are written in plaintext with the platform’s default permissions.
The audit and failure logs are not written during a --dry-run or check, and
neither is suno-index.json.
Recipes
# Full mirror to the configured root, prompting before any deletion:
suno sync
# Full mirror, unattended (approve deletions up front):
suno sync --yes
# Fast top-up of just the last week, with no deletion risk:
suno sync --since 7d
# Mirror a single playlist, deleting only that playlist's orphans while the
# rest of the library stays protected:
suno sync --playlist "Focus" --mode mirror
# See exactly what a mirror would change, changing nothing:
suno check --exit-code
Lineage and albums
Suno lets you build on a clip: remix it, extend it, or edit it. Each new clip
records the one it came from, which forms a lineage that runs back to an original
root clip. rs-suno follows that lineage to group related clips into albums and
to lay out files predictably.
Root resolution
For every clip, rs-suno walks the lineage back to its root ancestor, the
original clip a family of remixes and edits grew from. It fills gaps by looking
up parents directly, and it keeps a durable archive of what it has resolved (see
the lineage store below), so ancestry stays stable across
runs even after Suno purges an intermediate clip.
Albums from lineage
Clips that share a root are grouped into one lineage album. The album title is chosen simply:
- If the root ancestor is a real, distinct clip, the album takes the root clip’s title.
- Otherwise (a clip that is its own root), the album takes the clip’s own title.
So a song and all its remixes and extensions land in one album named after the original, while a standalone clip sits in an album of its own name.
Overriding an album name
When a derived title is undesirable, you can rename an album by its lineage root
id in the [accounts.<label>.albums] config table (see
album name overrides). The preferred
name replaces the derived one everywhere the album appears: the folder path, the
ALBUM tag, the change hash, and album art. On the next sync the existing
folder is moved to the new name and the emptied old directory pruned, with no
re-download and deletion safety intact.
Track numbers
Within an album, tracks are numbered by when each version was made: the earliest
created_at is track 1, the next track 2, and so on. The number is written to
the audio tags (TRACKNUMBER and TRACKTOTAL for FLAC, the equivalent
TRCK/trkn for MP3, WAV, and ALAC), so a player lists the album in creation
order, and it also prefixes the file name (07 - …) via the default template’s
{track2} placeholder.
TRACKTOTAL is the number of that album’s downloaded tracks. A single-track
album is numbered 1 of 1 by default; set number_singletons = false to
leave lone songs unnumbered (and unprefixed).
Because the number is part of the file name, a newly generated sibling can
renumber an album and rename every file in it. That is harmless on disk, and the
.m3u8 sidecars are rewritten to match, but it can confuse a media server that
tracks playlist membership by file. See
media servers for a stable-naming recipe.
Setting a lead track
Sometimes the version you think of as “song 1” was not made first, for example when you edited the main version after generating a batch of remixes. Flag it as the album’s lead and it is promoted to track 1, with the rest shifting down while keeping their relative order:
[accounts.me]
lead_tracks = [
"b320f4cf", # the 8-char code from a file name, or the full clip id
]
Each entry is a clip id or a unique prefix of one (such as the [b320f4cf] code
in a file name); the album is found from that clip’s lineage, so you never name
the album here. There is one lead per album, and an entry that matches no
downloaded clip, or more than one, is reported and ignored.
File and folder layout
Files are named deterministically from the clip and its lineage:
{creator}/{album}/{track2} - {creator}-{title} [{id8}]
{creator}is your display name (falling back to your handle).{album}is the lineage album title described above.{track}is the album track number (for example7);{track2}is the same number zero-padded to two digits (07). An unnumbered track renders neither, and its trailing separator is dropped so no orphan-is left behind.{title}is the clip’s title.{id8}is the first eight characters of the clip id ({id}is the full id,{root_id8}the first eight of the lineage root,{handle}your handle).
For example, a FLAC download might land at:
alice/Neon Horizon/03 - alice-Neon Horizon (Remix) [8d9e0f1a].flac
Names are made safe for the filesystem. Unicode is preserved where it is valid in a path; awkward characters are replaced, and over-long components are shortened.
Collision safety
Two protections make the layout collision-free:
- Same-title clips never clash. The
[{id8}]suffix in every file name keeps two clips with the same title in separate files. - Distinct roots never share a folder. If two different roots happen to have the same album title, the folders are separated by a short root-id suffix, so one album can never absorb another’s tracks.
Lineage tags
The lineage is also written into each file’s metadata, including the parent clip, the root clip, and a compact summary of the chain. See Artwork and animated covers for the full list of tags.
The lineage store
Resolved ancestry is saved beside your library in .suno-lineage.json. It is an
append-durable archive: once an ancestor is known, it is kept, even if the clip
is later trashed or removed upstream. This keeps album grouping stable over time.
Because it cannot be rebuilt once Suno purges old clips, a corrupt store stops
the run rather than being silently discarded.
Artwork and animated covers
Every download is tagged and carries cover art, so your library looks right in any music player. Artwork also lands as sidecar files so folder-based browsers and media servers pick it up.
Metadata tags
rs-suno writes rich metadata into each file. MP3 and WAV use ID3v2.4 frames
and FLAC uses Vorbis comments.
Core tags
- Title
- Artist and album artist (your creator name, falling back to
Suno) - Album (the lineage album title; see Lineage and albums)
- Track number and total, numbering the album by creation order (see
track numbers):
TRACKNUMBER/TRACKTOTALin FLAC,TRCKin MP3 and WAV,trknin ALAC - Date (the clip’s creation date)
Suno tags
- Style (the clip’s style tags) and a style summary
- The generation prompt (as a
SUNO_PROMPTtag) - Model (name and version, for example
chirp-v4) - Creator handle
- Parent clip, root clip, and a compact lineage summary
- The clip’s own id and canonical page URL (
SUNO_IDandSUNO_URL,https://suno.com/song/<id>), so a track can be traced back to Suno
Lyrics
Plain lyrics (without timestamps) are baseline metadata in every format: an
ID3 USLT frame in MP3 and WAV, a LYRICS comment in FLAC, and the iTunes
©lyr atom in ALAC. When the normal clip feed has no inline lyrics, rs-suno
checks Suno’s aligned-lyrics endpoint and embeds its plain text instead. A
tracked song that still has no embedded lyrics is checked again on every
executing sync/copy run, so lyrics added later are back-filled with an in-place
retag.
You can also write the same words beside the audio as an optional
.lyrics.txt sidecar. The sidecar flag controls only that extra file; plain
lyrics inside the audio do not require it.
Synced (timed) lyrics
With lrc_sidecar enabled, rs-suno also writes a synced <song>.lrc beside
each audio file. The default lyrics_timing = "line" uses the standard form
with one [mm:ss.xx] timestamp per line:
[ti:Neon Horizon]
[ar:alice]
[al:Neon Horizon]
[length:2:58]
[re:rs-suno]
[00:12.52]We ride the neon
[00:15.30]Chasing the dawn
Line timing is the broadly compatible form. Set lyrics_timing = "word" or
pass --lyrics-timing word to write enhanced LRC with per-word timestamps:
[00:12.52]<00:12.52>We <00:12.80>ride <00:13.10>the <00:13.32>neon
Enhanced LRC is supported by fewer players, so word timing is explicit rather than the default.
Structural section labels such as [Chorus] and [Verse 1] are omitted from the
timed .lrc and the SYLT frame: nothing is sung at those markers, so a timed
stamp would highlight a non-lyric line. They are kept in the plain lyrics (the
.lyrics.txt sidecar and the embedded USLT/LYRICS/©lyr tags), which
mirror the song’s own lyric text.
The .lrc is the primary synced-lyrics artefact and is written for every
format (MP3, FLAC, ALAC and WAV). For MP3 and WAV, an ID3 SYLT
(synchronised lyrics) frame is also embedded with the selected line or word
granularity. FLAC and ALAC carry no timed embed and use the .lrc sidecar.
Once plain fallback lyrics are embedded, their manifest fingerprint prevents
another lookup on an unchanged run. A song that still has no plain lyrics is
checked again on the next run so later-added words are discovered, unless the
last check found no lyrics at all: that result is trusted for about a fortnight,
so a known instrumental does not cost a lookup on every run. check and
--dry-run resolve lyrics exactly as an executing run does, so their report
matches what a run would write; they write nothing, so they never settle a
marker themselves. Separately, a clip with plain lyrics but no timing is
re-checked occasionally when lrc_sidecar is on, so later alignment can upgrade
the .lrc and SYLT.
A clip Suno cannot align, such as an instrumental, writes no .lrc and
embeds no SYLT. If a lookup fails, existing lyrics and sidecars are left
untouched and the lookup is retried next run; check and --dry-run say so and
report their counts as a lower bound, rather than guessing at the result. Turning lrc_sidecar off writes
no .lrc and adds no new SYLT; it does not disable baseline plain lyrics, and
it leaves existing .lrc files and timed frames in place.
Files written before timing modes used line-level LRC with word-level SYLT.
The first executing run after upgrading resolves those entries once and safely
retags MP3/WAV to the line default. Later changes between line and word mode
likewise update the sidecar and supported embedded frame. A failed fetch or
write keeps the previous state and retries on the next run.
Cover art
Each download carries cover art:
- Embedded front cover inside the audio file, so players that read embedded art show it. By default this is a static JPEG; with animated covers enabled it becomes an animated WebP for clips that have a video preview, with the current static JPEG retained as a secondary managed picture (see below).
- A per-song cover written beside each audio file, sharing the track’s name
with a
.jpgextension. This is always the static JPEG, so folder-based browsers and players without WebP support still show art. - An album cover named
folder.jpgin each album folder, which folder-based players and media servers use as the album thumbnail. It is chosen deterministically from the most-played art-bearing clip in the album.
Animated covers
Suno clips have a short looping video preview. rs-suno can turn that into an
animated WebP and embed it as the audio file’s front cover, so a media server
that animates embedded art (Navidrome, for example) plays it. This is opt-in,
because it costs an extra transcode per clip.
When animation succeeds, rs-suno also embeds the current static JPEG as a
secondary picture. The WebP remains the front cover, so OpenSubsonic servers
still return it as the track image; the JPEG is an archival and compatibility
fallback for software that reads additional embedded pictures. If Suno
advertises a static image but it cannot be fetched, the audio file is not
written or retagged with animation alone. The run reports a retryable partial
failure and leaves any existing file untouched.
Enable it per run with --animated-covers, --video-cover-retention webp, or
set video_cover_retention = "webp" (or animated_covers = true) in your
config. Clips with no video preview keep the static JPEG, as
do ALAC (.m4a) files, whose container cannot hold a WebP picture.
WebP is the right format for the embed: media servers that show animated covers animate WebP, APNG, and GIF but do not accept video (MP4/WebM), and WebP gives the best quality for the size.
The FLAC size cap
A FLAC picture is stored in a metadata block whose length is a 24-bit field, so a
single embedded picture cannot exceed about 16 MiB. The static JPEG occupies its
own picture block and does not reduce that per-block limit. A lossless animated cover is
far larger than that (a 5 s preview is around 145 MB, and even a lossless 384 px
encode is around 34 MB), so the FLAC embed must be a bounded lossy encode.
The default is quality 90 scaled to at most 640 px (about 11 MiB for a typical
5 s cover, comfortably under the cap), tunable with animated_cover_quality,
animated_cover_max_fps, animated_cover_max_width, and
animated_cover_compression_level. If an encode still would not fit (an unusual
cover, or quality and width set very high), rs-suno embeds the static JPEG for
that track instead, so the file is always valid. MP3 and WAV picture limits are
far higher, but the same bounded default is used to keep covers modest, because a
media server serves the embedded image at full size everywhere, including grids.
Client support
Animation renders only where the client both reads embedded art and decodes
animated WebP: the Navidrome web UI in a modern browser does, while many native
and mobile Subsonic clients show the first frame only. A player that cannot read
a WebP embedded cover at all may use the secondary embedded JPEG, the .jpg
per-song cover, or folder.jpg. OpenSubsonic exposes one selected image rather
than negotiating by client capability, so a client that can decode WebP but does
not animate it normally shows the WebP’s first frame. Enabling animation grows
each animated track by the encoded WebP plus one static JPEG.
Lossless covers
For a bit-exact cover, set --animated-cover-lossless (or
animated_cover_lossless = true). Lossless animated video is intrinsically
enormous (a five-second preview is around 145 MB), far larger than the
embedded-cover size cap, so a lossless cover always overflows it and the track
falls back to the static JPEG. Lossless is therefore not useful for embedded
covers; leave it off. Effort is capped at 4 for every mode, because effort 6
produces the same size for many times the encode time.
Keeping the raw source
The embedded WebP is a re-encode. To keep Suno’s original animation untouched,
choose --video-cover-retention mp4 (or video_cover_retention = "mp4"): it
writes the album’s video_cover_url verbatim as cover.mp4, with no transcode
and no ffmpeg. Use both to embed the animated WebP and also keep the raw
cover.mp4; the two come from the same album variant, and the source is fetched
only once.
This is a different asset from --video-mp4, which downloads the standalone
music video (video_url) beside each song.
ffmpeg requirement
Animated covers are transcoded from the clip’s video preview with ffmpeg, so
you need an ffmpeg build with animated-WebP (libwebp_anim) support. See
Installation and ffmpeg. Without it, use
the default static covers. The raw cover.mp4 needs no ffmpeg.
WAV metadata
WAV downloads carry full ID3v2.4 tags in a RIFF id3 chunk, using the same tag
set as MP3: title, artist, album, date, lyrics (USLT), cover art (APIC),
and all SUNO_* extended-text frames. Selected line or word synced lyrics
(SYLT) are also embedded when lrc_sidecar is enabled and alignment is
available. Player support for ID3 metadata inside WAV is less consistent than
for MP3. Choose FLAC (the default) for a lossless archive with Vorbis comments,
MP3 for the smallest files, or WAV when you need uncompressed PCM.
What lands on disk
For an album with animated covers and synced lyrics enabled, the layout looks like:
alice/
Neon Horizon/
folder.jpg
alice-Neon Horizon [a1b2c3d4].flac
alice-Neon Horizon [a1b2c3d4].jpg
alice-Neon Horizon [a1b2c3d4].lrc
alice-Neon Horizon (Remix) [8d9e0f1a].flac
alice-Neon Horizon (Remix) [8d9e0f1a].jpg
alice-Neon Horizon (Remix) [8d9e0f1a].lrc
The animated cover is embedded inside each .flac (for clips with a video
preview), not written as a separate file. With --video-cover-retention mp4 or
both, a raw cover.mp4 also lands in the album folder. Without
--animated-covers, the embedded cover is the static JPEG; without
lrc_sidecar, the .lrc files are not written.
Playlists (M3U8)
rs-suno writes your Suno playlists as .m3u8 files so any player can open them
against your mirrored library.
What gets written
- One playlist per Suno playlist. Each of your playlists is written as an extended M3U8 file, with its members in the order Suno holds them.
- The Suno playlist image. When Suno exposes
image_url, a same-basename.jpgis written beside the.m3u8. - A synthetic “Liked Songs” playlist. Your liked clips are written as a
Liked Songs.m3u8, in order, even though Suno has no explicit playlist for them.
Playlist files are written at the root of the destination directory. Each file
is named after the playlist, made safe for the filesystem, with an .m3u8
extension.
For example, Neon Nights.m3u8 and Neon Nights.jpg form one playlist and
cover pair. Navidrome 0.63.2 discovers this sidecar natively, so no server API
credentials or #EXTALBUMARTURL directive are required. The synthetic
Liked Songs.m3u8 has no image unless Suno later exposes one for that feed.
Format
The files are extended M3U8: a header, the playlist name, and one #EXTINF
entry per track giving its duration and title, followed by the track’s path
relative to the playlist. Relative paths mean the playlist keeps working if you
move the whole library.
#EXTM3U
#PLAYLIST:Neon Nights
#EXTINF:217,Neon Horizon
alice/Neon Horizon/alice-Neon Horizon [a1b2c3d4].flac
#EXTINF:182,Electric Storm
alice/Weather/alice-Electric Storm [3f2a1b4c].flac
Members not in your library
A playlist can reference clips you have not downloaded (for example someone
else’s track, or a clip excluded by a filter). Rather than write a broken path,
rs-suno records the member as a comment noting it is not in the library, using
the member’s own title. The rest of the playlist stays valid and in order.
Ordering and safety
- Order is preserved exactly as Suno reports it.
- A playlist is only written when its members were listed completely. If a playlist’s listing fails, that playlist is skipped for the run rather than written half-empty. The synthetic “Liked Songs” playlist is likewise only written when the liked feed was fully enumerated.
- If any audio download or lossless upgrade fails, playlist files and covers are left untouched so they never point at an uncommitted target path.
Playlists are regular mirror artefacts: their .m3u8 files are rewritten when
their name, order, or any member’s path, title, or duration changes. A playlist
image is refreshed when its Suno URL changes or the local .jpg is missing.
A failed image fetch leaves the previous cover untouched. Removing or renaming
playlist files and covers uses the same fully enumerated deletion gates.
A scoped run (--liked or --playlist) maintains only the selected areas’
.m3u8 files. A liked-only run refreshes Liked Songs.m3u8; a playlist-scoped
run refreshes the playlists it enumerated. Other existing playlist files are
left untouched. Run a full sync or copy to refresh every playlist.
Media servers
The .m3u8 files on disk always describe the current library, because they are
rewritten whenever a member’s path changes. What can drift is the copy a media
server imported into its own database.
Servers such as Navidrome, Plex and Jellyfin store playlist membership as a reference to their own per-file database row. When a file both moves and has an identity-bearing tag rewritten in the same run, a server can fail to recognise the move, create a second row, and mark the original missing. Any playlist pointing at the old row then loses that track, often with no error: Navidrome, for example, keeps serving the original song count while silently returning fewer entries.
The default naming template makes this more likely than you might expect,
because {track2} puts the album track number in the file name. Track numbers
come from creation order within a lineage album, so a
newly generated sibling can renumber the whole album, renaming every file and
rewriting every TRACKNUMBER tag at once.
If you point a media server at the library, either of these avoids the problem.
Keep paths stable. Drop the volatile prefix so a file name depends only on the clip’s own immutable id:
[defaults]
naming_template = "{creator}/{album}/{creator}-{title} [{id8}]"
Track numbers are still written to TRACKNUMBER and TRACKTOTAL, so albums
order correctly in a player. Only the paths stop moving. Changing this on an
existing library causes one mass rename, so let the server rescan afterwards.
Or anchor the server to the clip id. Every file carries its Suno clip id in
the SUNO_ID tag, which never changes for a given clip. Pointing the server’s
file identity at that tag makes renames and retags harmless. In Navidrome this
is the PID.Track setting, and the custom tag may need registering in the
server’s tag mappings first.
Whichever you choose, keep the library root path stable and leave the server’s playlist auto-import enabled, so the sidecars can repair an imported playlist on the next scan. If the root moves, a server may keep looking for the sidecars at the old location and quietly stop refreshing them.
Scheduling and exit codes
rs-suno is built to run unattended. Runs are incremental and resumable, and
every outcome maps to a distinct exit code so a scheduler or CI job can react
correctly.
Exit codes
| Code | Meaning | When |
|---|---|---|
| 0 | ok | All requested work completed. |
| 1 | general error | An unexpected, uncategorised failure. |
| 2 | usage | Unknown command, invalid flag, or missing argument, for example --allow-account-change on check or --dry-run. |
| 3 | config | Missing or invalid config, unknown account, conflicting flags. |
| 4 | auth | The token expired or was rejected and could not be refreshed. |
| 5 | partial | Some work failed, or managed local/upstream state could not be verified authoritatively. |
| 6 | transient-exhausted | Every clip failed with transient errors; nothing progressed. |
| 7 | safety abort | A deletion safety rule triggered, or the token authenticates as a different account than the library is pinned to; no files were changed. |
| 8 | interrupted | The run received an interrupt; partial progress is preserved. |
| 9 | disk full | The destination ran out of space; free space and re-run. The library is unchanged for the failing action. |
If lossless output cannot be fetched, that clip fails and the run exits 5 when
other work progressed or 6 when nothing progressed. An existing MP3 remains
in place until a verified lossless replacement is committed; a new lossless
download does not silently create an MP3.
Non-owned clips are different: Suno restricts WAV conversion to the recorded owner, so they use native MP3 without failing the run. Existing non-owned lossless files are preserved.
check --exit-code uses 1 only for an authoritative plan with pending
changes, and 0 only when the destination is authoritatively up to date. An
incomplete check keeps the domain exit from the table, such as 5 for
unverifiable or unresolved state.
Running unattended
For a scheduled job, avoid interactive prompts:
- Use
copyif you never want deletions. It never prompts. - Use
sync --yesif you do want the full mirror including deletions. Without a terminal, asyncthat would delete files refuses unless--yesis passed. - Provide the token from the environment or the config file, not a flag in a script.
The deletion safety rules still apply under --yes: the fully-enumerated gate
and the mass-deletion abort will still stop a run that looks wrong, and the
account identity guard refuses a run whose token belongs to a different account
than the library is pinned to (also exit 7). See
Sync, copy and deletion safety.
Incremental top-ups
--since last-run mirrors only what changed since the previous successful run,
using a timestamp kept beside the library. It is a cheap way to run often.
Remember that any recency filter (--since or --limit) disables deletion for
that run, so pair frequent top-ups with an occasional full sync if you want
deletions reconciled.
cron
# Full mirror every night at 02:30, additive only.
30 2 * * * SUNO_TOKEN=... /usr/local/bin/suno copy /music/suno >> /var/log/suno.log 2>&1
Prefer keeping the token in the config file (readable only by your user) over putting it in the crontab.
systemd timer
~/.config/systemd/user/suno.service:
[Unit]
Description=Mirror the Suno library
After=network-online.target
[Service]
Type=oneshot
ExecStart=%h/.cargo/bin/suno sync --yes
~/.config/systemd/user/suno.timer:
[Unit]
Description=Run suno sync daily
[Timer]
OnCalendar=daily
Persistent=true
[Install]
WantedBy=timers.target
Enable it with:
systemctl --user enable --now suno.timer
Persistent=true catches up a run missed while the machine was off, which pairs
well with rs-suno being resumable.
Containers
Keep the image one-shot and let cron or a systemd timer invoke
podman run --rm. This preserves the suno process exit code for the host
scheduler and avoids running a second init system inside the image.
The container guide includes Podman, Docker, systemd, cron, and native Proxmox VE examples.
After a run
- The per-run summary reports counts and duration on stderr.
- Clips that failed after all retries are listed in
.suno-failures.log. - Every deletion and rename is recorded in
.suno-audit.log.
Because runs are resumable, a job that exits 5, 6, or 8 can simply be run again; it continues from where it left off. An exit of 4 means the token needs attention (see Authentication); an exit of 7 means a safety rule stopped a suspicious deletion and should be investigated before forcing it.
Troubleshooting and FAQ
Troubleshooting
ffmpeg is not found
suno version ends with ffmpeg: not found on PATH. Install ffmpeg and make
sure it is on your PATH. See
Installation and ffmpeg. rs-suno needs
ffmpeg to produce FLAC (the default format) or ALAC, and animated WebP covers.
FLAC, ALAC, or animated covers fail to encode
Your ffmpeg build is missing an encoder. Check it with:
ffmpeg -hide_banner -encoders | grep -E 'flac|alac|libwebp'
If flac or alac is missing, download in MP3 or WAV, or install a fuller
ffmpeg build. If libwebp/libwebp_anim is missing, drop --animated-covers
or install an ffmpeg with animated-WebP support.
Authentication failed (exit 4)
The stored token has expired or was rejected. Diagnose it first:
suno doctor --account <account>
Then confirm and re-mint it:
suno auth refresh <account>
If that still fails, the session was rotated (you logged out, or Suno reset it).
Get a fresh __client token and set the account’s token in your config file
to the new value (run suno version to print the config path). If the account
uses token_command, the refreshed secret is picked up automatically on the
next run. See Authentication.
“multiple accounts configured; pass –account”
You have more than one account and ran a single-account command without saying
which. Add --account <label>, or use --all for sync/copy to run every
account.
“account has no configured root and no DEST was given”
The account has no root in its config and you did not pass a destination. Give
a DEST on the command line, or set root for the account. --all always
needs each account to have a root.
“another suno run is active”
A run holds an exclusive lock (.suno.lock) on the destination while it works.
If a previous run crashed, the lock file can be left behind. Once you are sure no
run is active, delete the .suno.lock file in the destination directory and try
again.
A sync aborted with a safety warning (exit 7)
A deletion safety rule stopped the run because the deletion looked wrong: the
listing was empty, or it would have removed a large fraction of your library.
Nothing was deleted. This is usually a transient listing problem, so try again
later. If you genuinely intend a mass deletion, confirm it explicitly with
--min-newest 0 --yes. See
deletion safety.
Nothing is being deleted
That is expected when you use --since or --limit. A narrowed or filtered
listing is not authoritative, so deletion is disabled for that run. Run a plain
sync (no recency filter) to reconcile deletions.
A run stopped saying the manifest or lineage store is corrupt
rs-suno refuses to run against a damaged .suno-manifest.json or
.suno-lineage.json rather than risk re-downloading everything or losing
archived lineage. Restore the file from a backup, or move it aside to start
fresh. Starting fresh re-downloads every file: without the manifest there is no
recorded digest to verify existing files against, so the safe choice is to
re-fetch rather than trust unverified local copies.
A song I moved or renamed by hand came back, and the moved copy is still there
rs-suno tracks each file at the exact path it wrote. If you move or rename a
downloaded file by hand, the next sync/copy sees nothing at the recorded
path and downloads the clip again, leaving your moved copy in place as an
untracked file. It is not re-identified and adopted: the manifest holds no
content fingerprint of the audio and the clip id is not embedded in the tags, so
there is no safe way to match a moved file back to its clip, and guessing could
attach the wrong audio to a clip. check and --dry-run list these untracked
audio files under an “untracked audio file(s)” note so you can see them; move
each back into place (matching the layout check would use) or delete it, then
re-sync. Let the tool own the file layout to avoid this.
A song’s title changed only in letter case or accents, but the file was not renamed
When a clip’s title changes only by letter case (for example Foo to FOO) or
by Unicode normalisation (an accented character written a different but equivalent
way), rs-suno intentionally keeps the existing file name. It treats two paths
that differ only by case or normalisation as the same path, because that is how
the Windows and macOS filesystems treat them, and the same rule underpins
deletion safety so a rename can never clobber a protected clip. The engine does
no disk IO and cannot safely tell whether your filesystem is case-sensitive, so
it does not force a case-only rename that would be a no-op or a self-clobber on
those platforms. On Linux or WSL2 the file keeps its earlier-case name, which is
fully valid and openable.
FAQ
What is the difference between sync and copy?
sync mirrors, including deleting local files whose clips have left your
library. copy only ever adds and updates. Use copy if you want an archive
that never loses files.
I unliked a song (or it left my library) — what happens on the next sync?
Under sync it becomes a deletion candidate: once a clip is absent from every
mirror source, its local file is removed (subject to the deletion-safety gates,
so never on an empty, filtered, or failed listing). Under copy it is kept.
Preview it first with check or --dry-run, which list the pending deletions.
How do I preview what a run would do?
Use check (or add --dry-run to sync/copy). Both report the pending
changes without modifying the library. They scan managed files and may make
read-only upstream requests so the plan matches a real run. check --exit-code
exits 1 when verified changes are pending, 0 when verified up to date, and a
partial or transient code when it cannot produce an authoritative plan.
Can I mirror more than one account?
Yes. Configure each account with its own token and root, then run --all to
mirror every account into its own directory, or --account <label> for one.
Account roots may not nest inside one another.
Does fetch need a config?
No. fetch can run with just --token (or SUNO_TOKEN). It downloads a single
clip to a path you choose and never touches a mirrored library.
Where does my library go?
To the DEST you pass, or the account’s configured root. The config path
itself is shown by suno version.
Which format should I choose?
FLAC (the default) is lossless and carries full metadata and embedded art. ALAC
is lossless too and is the Apple-friendly choice (.m4a, plays natively on Apple
devices and Apple Music), carrying the same tags and cover. MP3 is smaller and
widely compatible. WAV is uncompressed and carries full ID3v2.4 metadata,
including lyrics and embedded art, in a RIFF id3 chunk.
Why did a lossless run leave an MP3 in place?
Suno supplies FLAC and ALAC indirectly: suno downloads Suno’s authenticated
WAV render, then converts it locally. A stale cookie or a paused, inactive,
past-due, or non-entitled plan cannot request that WAV. suno never converts
MP3 into a lossless container. If an MP3 already exists from an older run, it is
kept for playback while the upgrade fails and the run returns non-zero. Once a
verified FLAC or ALAC is committed, the MP3 is removed. A new lossless target
does not fall back to MP3.
Why is a playlist track permanently MP3?
Suno restricts WAV conversion to the account recorded as the clip owner. A
liked, shared, remixed, or covered track can retain another account’s user_id
even when its display name looks familiar. rs-suno uses native MP3 for those
non-owned clips and reports a note instead of repeatedly calling an endpoint
that will always return 403. If a non-owned lossless file already exists, it
is kept.
Is it safe to run on a schedule?
Yes. Runs are incremental and resumable, an exclusive lock prevents overlap, and the deletion safety rules prevent a bad listing from wiping files. See Scheduling and exit codes.