Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Commands reference

suno [OPTIONS] <COMMAND>
CommandPurpose
syncMirror your library to a directory, including deletions.
copyDownload and update, never delete.
checkAuthoritatively report what sync or copy would change without modifying the library.
lsList clips in a readable table.
lsjsonList clips as newline-delimited JSON.
fetchDownload one clip by ID or URL.
configManage the configuration file.
authManage authentication.
doctorDiagnose environment, config, auth, and credits.
versionPrint version and environment information.
completionsEmit a shell completion script.

Global options

These apply to every command and may appear before or after the subcommand.

FlagShortEnvDescription
--account <LABEL>SUNO_ACCOUNTRun against one configured account.
--allRun every configured account in isolation (sync/copy). Conflicts with --account.
--config <PATH>SUNO_CONFIGPath to the config file.
--dry-run-nSUNO_DRY_RUNReport changes without writing to disk or deleting.
--verbose-vIncrease verbosity. Repeatable (-vv).
--quiet-qDecrease verbosity. Repeatable (-qq).
--yes-ySUNO_YESSkip confirmation prompts (such as a destructive sync).
--token <TOKEN>SUNO_TOKENThe __client token. Never printed. Overrides config and env.

Verbosity

Verbosity is relative to the default level of 0.

LevelFlagOutput
Silent-qqErrors only.
Quiet-qPer-run summary, warnings, and errors.
DefaultSummary plus a single progress line.
Verbose-vA 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.

FlagDefaultDescription
--format <mp3|flac|alac|wav>flacAudio 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.
--likedoffScope 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: copySelect the mode for scoped areas: mirror arms deletion, copy stays additive. Only meaningful with --liked, --playlist, or an [areas] config.
--min-newest <N>1Newest clips always kept when a recency filter applies.
--retries <N>3Download retry attempts per clip.
--concurrency <N>4Simultaneous downloads.
--animated-coversoffEmbed 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>neitherUnified 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>90Animated WebP quality (0..100). The default fits the ~16 MiB FLAC picture cap; ignored with --animated-cover-lossless.
--animated-cover-max-fps <N>24Animated WebP frame-rate cap.
--animated-cover-max-width <PIXELS>640Animated WebP width cap (raise for sharper covers at the risk of a JPEG fallback on FLAC).
--animated-cover-compression-level <N>4Animated WebP compression effort (0..4).
--animated-cover-losslessoffEncode 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-changeoffRe-pin this library to the authenticated account. The run is additive and deletes nothing.
--details-sidecaroffAlso write a plain-text .details.txt sidecar next to each song.
--lyrics-sidecaroffAlso write a plain-text .lyrics.txt sidecar next to each song. Plain lyrics inside the audio are automatic.
--lrc-sidecaroffAlso 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>lineWith --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-mp4offAlso download the standalone .mp4 music video beside each song, when available.
--download-stemsoffAlso 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>wavContainer 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>unicodeCharacter 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]
FlagDescription
--exit-codeExit 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]
FlagDefaultDescription
--likedoffList 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>textOutput 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.

FieldTypeDescription
idstringSuno clip UUID.
titlestringDisplay title; Untitled when blank.
statusstringFor example complete.
durationnumberSeconds.
created_atstringISO 8601 UTC.
is_likedboolWhether the clip is liked.
has_vocalboolWhether the clip has a vocal track.
clip_typestringFor example gen or edit.
tagsstringComma-separated style tags.
promptstring | nullUser prompt.
gpt_description_promptstring | nullAuto-generated description prompt.
lyricsstring | nullLyrics text; null if instrumental.
model_namestringFor example chirp-v4.
major_model_versionstringFor example v4.
display_namestringAccount display name.
handlestringAccount handle.
edited_clip_idstring | nullSource clip if this is a remix.
audio_urlstringAudio CDN URL.
image_urlstringCover image URL.
image_large_urlstringLarge cover image URL.
video_urlstringClip video URL.
video_cover_urlstringVideo 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.

FieldTypeDescription
idstringSuno clip UUID (the manifest key).
pathstringForward-slash library-relative path to the audio file.
formatstringflac, mp3, alac, or wav.
sizenumberFile size in bytes.
titlestringLive title, else the archived title, else Untitled.
artiststring | nullLive display name (Suno when blank); null when not seen this run.
handlestring | nullLive account handle; null when not seen this run.
albumstringRaw logical album title; may differ from the sanitised album folder in path.
root_idstringResolved lineage root id, or the clip’s own id when it is a root.
created_atstring | nullArchived creation timestamp; null when unknown.
durationnumber | nullSeconds; null when not seen this run.
tagsstring | nullComma-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.

FlagShortDefaultDescription
--format <mp3|flac|alac|wav>flacAudio format.
--output <PATH>-oExplicit 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>
SubcommandUsagePurpose
initsuno config initInteractively create a new config file.
add-accountsuno config add-account [LABEL]Add a new account entry to an existing config file.
showsuno config showPrint 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