suno-cli

Command-line Suno helper for creating songs and retrieving finished audio.

Quick Start

1. Install the CLI and its browser. The browser is used once per create to mint a Suno captcha token through your own logged-in session.

npm install -g @usedhonda/suno-cli
npx playwright install chromium

2. Log in once. A browser window opens — sign in to Suno normally.

suno-cli login

3. Create a song.

suno-cli create --live \
  --title "rain window" \
  --style "lo-fi piano, mellow, rain" \
  --lyrics "rain on the window"

A browser window opens briefly to mint the captcha through your logged-in Suno session. If Suno shows a puzzle, solve it once (exactly like you would on suno.com) — after the first solve, later creates usually pass with no puzzle. Nothing is bypassed; you solve your own captcha.

The command prints JSON with Suno clip ids and https://suno.com/song/<clip-id> URLs. Minting the captcha spends no credits; a successful create does.

Want to check captcha works without spending credits? See How Captcha Works.

Retrieve Results

Check a run or clip:

suno-cli status <run-id|clip-id|song-url>

Print song URLs:

suno-cli urls <run-id|clip-id|song-url>

Download ready MP3 files:

suno-cli download <run-id|clip-id|song-url> --out ./downloads

status, urls, and download all print JSON. download waits for real audio readiness and does not treat Suno's silent placeholder file as success.

Requirements

• Node.js 22 or newer
• Your own Suno account
• Enough Suno credits for live create requests

suno-cli login opens a browser window and stores a local session under:

~/.local/share/suno-kit/

Runtime files stay outside the repository. The saved session is written with owner-only permissions where the OS supports them. To clear saved auth and the browser profile:

suno-cli logout

Dry Run

Use --dry-run to inspect the request shape without spending credits:

suno-cli create --dry-run \
  --title "rain window" \
  --style "lo-fi piano, mellow, rain" \
  --lyrics "rain on the window"

Dry-run also reserves a local transaction_uuid for the same --run-id, so retries can reuse the same idempotency key.

Common Create Options

suno-cli create --live \
  --title "track title" \
  --style "genre, mood, instruments" \
  --lyrics "lyrics text"

Use instrumental mode instead of lyrics:

suno-cli create --live \
  --title "night drive" \
  --style "synthwave, instrumental" \
  --instrumental

Useful optional controls:

| Flag | Meaning | |---|---| | --exclude <text> | Styles or sounds to avoid | | --vocal-gender m|f | Vocal gender hint | | --weirdness <0-100> | Suno weirdness slider | | --style-influence <0-100> | Suno style influence slider | | --audio-influence <0-100> | Suno audio influence slider | | --persona-id <id> | Use an existing Suno persona | | --cover-clip-id <id> | Cover an existing Suno clip | | --cover-start-s <sec> / --cover-end-s <sec> | Cover range in seconds; requires --cover-clip-id |

Cover mode uses an existing Suno clip id. Uploading external audio is not implemented.

Headless Login

If you are on SSH, VPS, WSL, or another environment without a browser UI, paste the Suno __session JWT from a machine where you are already logged in:

suno-cli login --jwt-paste '<copied-__session-value>'

The value is not printed back. Do not paste it into chat, issues, screenshots, logs, or commit history.

Advanced Auth

Prefer suno-cli login. Use these only when debugging or running in automation you control.

Pass a direct JWT for one command:

suno-cli status <clip-id> --jwt '<copied-__session-value>'
suno-cli create --live --jwt '<copied-__session-value>' --title "probe" --style "lo-fi piano"

Or via environment:

export SUNO_KIT_JWT='<copied-__session-value>'
suno-cli status <clip-id>

The older cookie flow needs full Clerk browser context. A copied __session cookie string alone may not be enough for Clerk's client endpoint.

Cookie escape hatches:

export SUNO_KIT_COOKIE='<full-cookie-header>'
export SUNO_KIT_COOKIE_FILE=~/.local/share/suno-kit/cookie.txt

SUNO_KIT_COOKIE wins over SUNO_KIT_COOKIE_FILE. The per-command --cookie-file <file> flag is also available.

Advanced Live Metadata

Most users do not need these fields. They are included for parity with observed Suno browser requests:

suno-cli create --live \
  --title "probe" \
  --style "lo-fi piano" \
  --session-token "$SUNO_CREATE_SESSION_TOKEN" \
  --user-tier "$SUNO_USER_TIER"

SUNO_CREATE_SESSION_TOKEN and SUNO_USER_TIER are also read from the environment. If omitted, the metadata keys are not sent.

How Captcha Works

Suno requires a captcha token to create a song. The CLI mints one for you — you do not paste tokens or install a captcha-solving service.

On create --live, the CLI opens a browser using your suno-cli login session, fills the create form, and lets Suno run its own hCaptcha:

• Most of the time it passes automatically (invisible) and you see nothing.
• If Suno shows a puzzle, solve it in the window — you are solving your own captcha in a real browser, exactly as on suno.com. After the first solve, the trusted session usually passes later creates without a puzzle.

Minting never submits a create, so it costs no credits.

Verify captcha for free

Check that minting works without spending any credits (mints the token, then stops — no create is submitted):

suno-cli create --mint-check --title "test" --style "lo-fi piano"

"status": "captcha_mint_ok" means captcha is working end-to-end.

Requirements for the browser mint

• npx playwright install chromium must have been run once (installs the browser).
• You must be logged in (suno-cli login).
• The mint uses a visible browser window, so run it on a machine with a display.

Advanced: supply your own token

Skip the browser entirely by passing a fresh token from a logged-in Suno tab:

suno-cli create --live \
  --title "probe" \
  --style "lo-fi piano" \
  --captcha-token '<fresh-token>' \
  --token-provider <integer>

Captcha tokens are short-lived and may be single-use. Do not log them, paste them into chat, or commit them. If Suno blocks the create, the CLI returns status blocked_captcha and exit code 31.

Exit Codes

| Code | Name | Meaning | |---:|---|---| | 0 | ok | Success | | 2 | usage | Bad arguments, missing target, or unknown id | | 30 | blockedLogin | Missing or unusable login/session | | 31 | blockedCaptcha | Suno requires a captcha token for this create request | | 32 | blockedPaymentOrQuota | Quota, payment, budget, or manual live gate | | 40 | schemaDrift | Corrupt ledger, incompatible local state, or unexpected 4xx | | 50 | retryableUnknown | Network failure, 5xx, or audio not ready | | 70 | internal | Unexpected internal error |

Errors are JSON and are redacted before output.

Safety And Scope

• This is an unofficial community tool, not affiliated with or endorsed by Suno.
• Use your own account and understand that automated access can violate Suno's Terms of Service.
• Live create can spend credits.
• The CLI surfaces login, captcha, payment/quota, and network blocks instead of retrying around them.
• Cookies, JWTs, bearer tokens, Clerk tokens, captcha tokens, and create_session_token are redacted from JSON output.
• Runtime state is stored outside the repository by default.

Manual Live-Fire Checklist

Do not run a paid live-fire test without explicit owner GO.

1. Confirm the owner approved one paid Suno create test in the current conversation.
2. Confirm the current credit balance and expected credit cost.
3. Confirm npm test is green.
4. Confirm create --dry-run emits the expected shape.
5. Confirm suno-cli login succeeds.
6. Submit exactly one request with create --live.
7. If Suno returns blocked_captcha, stop and use the advanced captcha path only with explicit approval.
8. Record returned clips[].id values only. Do not log secrets.
9. Use status, urls, and download to retrieve results.