@jackwener/opencli 1.7.22 → 1.8.1

package/clis/suno/generate.js

@@ -0,0 +1,231 @@
+/**
+ * `opencli suno generate` — submit a Suno music-generation request, wait for
+ * both clips to finish, and download selected formats locally.
+ *
+ * Targets the /api/generate/v2-web/ endpoint (cookie auth). Each generation
+ * returns 2 candidate clips by design — both are downloaded so the caller
+ * can A/B them.
+ *
+ * Modes:
+ *   - Custom (when --lyrics is provided): API receives prompt(lyrics)+tags
+ *     +title+negative_tags. Use this for professional control over lyrics,
+ *     structure metatags, style, and exclusions.
+ *   - Simple (default): API receives a description in `prompt`; Suno picks
+ *     the lyrics, tags, and title.
+ *
+ * Creative knobs (--weirdness / --style-weight) map directly to the
+ * `metadata.control_sliders` the web UI exposes.
+ */
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError } from '@jackwener/opencli/errors';
+import {
+    DEFAULT_SUNO_MODEL,
+    SUNO_DOMAIN,
+    SUNO_MODELS,
+    SUNO_URL,
+    checkSunoCaptcha,
+    clampSlider,
+    downloadSunoClip,
+    ensureSunoSession,
+    normalizeBooleanFlag,
+    parseFormats,
+    pollSunoClips,
+    requirePositiveInt,
+    resolveSunoOutputDir,
+    submitSunoGeneration,
+} from './utils.js';
+
+import * as crypto from 'node:crypto';
+import * as os from 'node:os';
+
+function displayPath(filePath) {
+    if (!filePath) return '-';
+    const home = os.homedir();
+    return filePath.startsWith(home) ? `~${filePath.slice(home.length)}` : filePath;
+}
+
+export const generateCommand = cli({
+    site: 'suno',
+    name: 'generate',
+    access: 'write',
+    description: 'Generate music with Suno (V5.5 chirp-fenix by default) and download clips locally',
+    domain: SUNO_DOMAIN,
+    strategy: Strategy.COOKIE,
+    browser: true,
+    siteSession: 'persistent',
+    navigateBefore: false,
+    defaultFormat: 'plain',
+    args: [
+        { name: 'prompt', positional: true, required: false, help: 'Simple-mode description (ignored when --lyrics is provided)' },
+        { name: 'lyrics', help: 'Custom-mode lyrics (with [Verse]/[Chorus] metatags). Triggers Custom mode.' },
+        { name: 'tags', help: 'Custom-mode style tags (genre, BPM, instruments...). Used with --lyrics.' },
+        { name: 'negative-tags', help: 'Custom-mode style exclusions (e.g. "no vocals, no autotune"). Used with --lyrics.' },
+        { name: 'title', help: 'Song title (default: auto-derived from prompt)' },
+        { name: 'instrumental', type: 'boolean', default: false, help: 'No vocals' },
+        { name: 'model', help: `Model id: ${SUNO_MODELS.join(', ')}. Default: ${DEFAULT_SUNO_MODEL}` },
+        { name: 'weirdness', help: 'Creative weirdness slider (0..1). Default: 0.5' },
+        { name: 'style-weight', help: 'Style adherence slider (0..1). Default: 0.5' },
+        { name: 'formats', help: 'Comma-separated download formats: mp3, m4a, wav, video, cover, metadata. Default: mp3,metadata' },
+        { name: 'op', help: 'Output directory (default: ~/Music/suno)' },
+        { name: 'timeout', type: 'int', default: 300, help: 'Max seconds to wait for clips to finish (default: 300)' },
+        { name: 'sd', type: 'boolean', default: false, help: 'Skip download; only print clip ids and Suno URLs' },
+        { name: 'confirm-paid', type: 'boolean', default: false, help: 'Required to allow paid downloads (wav). Without it, paid formats are skipped with a warning.' },
+    ],
+    columns: ['status', 'clip', 'title', 'files', 'link'],
+    func: async (page, kwargs) => {
+        const lyrics = kwargs.lyrics ? String(kwargs.lyrics) : '';
+        const tags = kwargs.tags ? String(kwargs.tags) : '';
+        const negativeTags = kwargs['negative-tags'] ? String(kwargs['negative-tags']) : '';
+        const description = kwargs.prompt ? String(kwargs.prompt) : '';
+        const titleArg = kwargs.title ? String(kwargs.title) : '';
+        const model = kwargs.model ? String(kwargs.model).trim() : DEFAULT_SUNO_MODEL;
+        if (!SUNO_MODELS.includes(model)) {
+            throw new ArgumentError(`Unsupported --model "${model}"`, `Choices: ${SUNO_MODELS.join(', ')}`);
+        }
+
+        const isCustom = lyrics.trim() !== '';
+        if (!isCustom && !description.trim()) {
+            throw new ArgumentError(
+                'Either provide a Simple-mode prompt as the positional argument, or pass --lyrics for Custom mode.',
+                'Examples:\n  opencli suno generate "lo-fi study beat, 80 bpm"\n  opencli suno generate --lyrics "[Verse]\\n..." --tags "synthwave, 120 bpm"',
+            );
+        }
+        if (!isCustom && (tags || negativeTags)) {
+            throw new ArgumentError('--tags and --negative-tags only apply in Custom mode (alongside --lyrics).');
+        }
+
+        const requestedFormats = parseFormats(kwargs.formats);
+        const confirmPaid = normalizeBooleanFlag(kwargs['confirm-paid']);
+        const skipDownload = normalizeBooleanFlag(kwargs.sd);
+        const PAID_FORMATS = new Set(['wav']);
+        const skippedPaid = [];
+        const formats = requestedFormats.filter(f => {
+            if (PAID_FORMATS.has(f) && !confirmPaid) {
+                skippedPaid.push(f);
+                return false;
+            }
+            return true;
+        });
+        if (!skipDownload && !formats.length) {
+            throw new ArgumentError('All requested formats require --confirm-paid true', 'Add --confirm-paid true or include a free format such as mp3 or metadata.');
+        }
+        const outputDir = resolveSunoOutputDir(kwargs.op);
+        const timeout = requirePositiveInt(kwargs.timeout, '--timeout');
+        const makeInstrumental = normalizeBooleanFlag(kwargs.instrumental);
+        const weirdness = clampSlider(kwargs.weirdness, '--weirdness', 0.5);
+        const styleWeight = clampSlider(kwargs['style-weight'], '--style-weight', 0.5);
+
+        // Title: required by API. Auto-derive from first 60 chars of source prompt if not provided.
+        const titleSource = titleArg || (isCustom ? (tags || lyrics.split('\n')[0]) : description);
+        const title = titleSource.replace(/\s+/g, ' ').trim().slice(0, 60) || 'Untitled';
+
+        const session = await ensureSunoSession(page);
+        if (!session.planId) {
+            throw new CommandExecutionError(
+                `Suno generation needs a resolved plan id for the user_tier field, but billing/info did not surface one for this account (subscription_type=${session.planKey}). Verify the account is active at ${SUNO_URL}/account, then retry.`,
+            );
+        }
+        const deviceId = session.deviceId;
+        const captcha = await checkSunoCaptcha(page, deviceId);
+        if (!captcha?.ok) {
+            throw new CommandExecutionError(
+                `Suno captcha pre-flight failed${captcha?.status ? ` (HTTP ${captcha.status})` : ''}.`,
+                `Open ${SUNO_URL}/create in Chrome and verify the account is ready, then retry.`,
+            );
+        }
+        if (captcha?.required) {
+            throw new CommandExecutionError(
+                'Suno requires a CAPTCHA challenge for this account/IP right now.',
+                `Open ${SUNO_URL}/create in Chrome, solve a Create challenge once, then retry.`,
+            );
+        }
+        if (session.totalCreditsAvailable < 10) {
+            const b = session.breakdown;
+            throw new CommandExecutionError(
+                `Suno generation needs ~10 credits; you have ${session.totalCreditsAvailable} (monthly ${b.monthlyRemaining}/${b.monthlyLimit} + packs ${b.purchasedPacks} + leftover ${b.pack}). Top up at ${SUNO_URL}/account.`,
+            );
+        }
+
+        const transactionUuid = crypto.randomUUID();
+        const createSessionToken = crypto.randomUUID();
+
+        const submission = await submitSunoGeneration(page, {
+            mode: isCustom ? 'custom' : 'simple',
+            model,
+            title,
+            lyrics,
+            tags,
+            negativeTags,
+            description,
+            makeInstrumental,
+            weirdness,
+            styleWeight,
+            userTier: session.planId,
+            createSessionToken,
+            transactionUuid,
+            deviceId,
+        });
+
+        if (!Array.isArray(submission.clips)) {
+            throw new CommandExecutionError('Suno generation returned malformed clips payload.');
+        }
+        const clipIds = submission.clips.map(c => c?.id);
+        if (clipIds.some(id => !id)) {
+            throw new CommandExecutionError('Suno generation returned malformed clip identity.');
+        }
+        if (!clipIds.length) {
+            throw new CommandExecutionError('Suno accepted the request but returned no clip ids.');
+        }
+
+        const clips = await pollSunoClips(page, clipIds, timeout, deviceId);
+        const completed = clips.filter(c => c.status === 'complete');
+        if (!completed.length) {
+            const errors = clips.map(c => `${c.id.slice(0, 8)}:${c.status}`).join(', ');
+            throw new CommandExecutionError(`All Suno clips failed (${errors}). Open ${SUNO_URL}/song/${clipIds[0]} to inspect.`);
+        }
+
+        const rows = [];
+        for (const clip of clips) {
+            const link = `${SUNO_URL}/song/${clip.id}`;
+            if (clip.status !== 'complete') {
+                rows.push({
+                    status: `❌ ${clip.status}`,
+                    clip: clip.id.slice(0, 8),
+                    title: clip.title || '(untitled)',
+                    files: '-',
+                    link: `🔗 ${link}`,
+                });
+                continue;
+            }
+            if (skipDownload) {
+                rows.push({
+                    status: '🎵 generated',
+                    clip: clip.id.slice(0, 8),
+                    title: clip.title || '(untitled)',
+                    files: '📁 -',
+                    link: `🔗 ${link}`,
+                });
+                continue;
+            }
+            const result = await downloadSunoClip(page, clip, outputDir, formats, deviceId);
+            if (!result.written.some(w => w.ok)) {
+                throw new CommandExecutionError(`Suno download wrote no files for clip ${clip.id}`);
+            }
+            const writtenSummary = result.written
+                .map(w => w.ok ? `${w.format}:${displayPath(w.file)}` : `${w.format}:✗(${w.reason})`)
+                .join(' | ');
+            const skippedSummary = skippedPaid.length
+                ? ` | skipped(needs --confirm-paid):${skippedPaid.join(',')}`
+                : '';
+            const anyFailed = result.written.some(w => !w.ok);
+            rows.push({
+                status: anyFailed ? '⚠ partial' : '✅ saved',
+                clip: clip.id.slice(0, 8),
+                title: clip.title || '(untitled)',
+                files: `📁 ${writtenSummary}${skippedSummary}`,
+                link: `🔗 ${link}`,
+            });
+        }
+        return rows;
+    },
+});

package/clis/suno/generate.test.js

@@ -0,0 +1,252 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+    ensureSunoSession: vi.fn(),
+    checkSunoCaptcha: vi.fn(),
+    submitSunoGeneration: vi.fn(),
+    pollSunoClips: vi.fn(),
+    downloadSunoClip: vi.fn(),
+}));
+
+vi.mock('./utils.js', () => ({
+    DEFAULT_SUNO_MODEL: 'chirp-fenix',
+    SUNO_DOMAIN: 'suno.com',
+    SUNO_MODELS: ['chirp-fenix', 'chirp-bluejay', 'chirp-v4', 'chirp-v3-5'],
+    SUNO_URL: 'https://suno.com',
+    ensureSunoSession: mocks.ensureSunoSession,
+    checkSunoCaptcha: mocks.checkSunoCaptcha,
+    submitSunoGeneration: mocks.submitSunoGeneration,
+    pollSunoClips: mocks.pollSunoClips,
+    downloadSunoClip: mocks.downloadSunoClip,
+    clampSlider: (value, _label, def) => (value === undefined || value === '' || value === null ? def : Number(value)),
+    normalizeBooleanFlag: (value, fallback = false) => {
+        if (typeof value === 'boolean') return value;
+        if (value == null || value === '') return fallback;
+        const s = String(value).trim().toLowerCase();
+        return s === 'true' || s === '1' || s === 'yes' || s === 'on';
+    },
+    parseFormats: (value) => {
+        if (!value) return ['mp3', 'metadata'];
+        const raw = Array.isArray(value) ? value.join(',') : String(value);
+        return raw.split(',').map(s => s.trim().toLowerCase()).filter(Boolean);
+    },
+    requirePositiveInt: (value) => {
+        const n = Number(value);
+        if (!Number.isInteger(n) || n < 1) throw new Error('positive int required');
+        return n;
+    },
+    resolveSunoOutputDir: (value) => value || '/tmp/suno-test',
+}));
+
+const { generateCommand } = await import('./generate.js');
+
+function createPage() {
+    return {
+        goto: vi.fn().mockResolvedValue(undefined),
+        wait: vi.fn().mockResolvedValue(undefined),
+        evaluate: vi.fn().mockResolvedValue(undefined),
+    };
+}
+
+const okSession = {
+    ok: true,
+    planId: '3eaebef3-ef46-446a-931c-3d50cd1514f1',
+    planKey: 'pro',
+    totalCreditsAvailable: 2000,
+    breakdown: { pack: 0, purchasedPacks: 0, monthlyRemaining: 2000, monthlyLimit: 2500, monthlyUsed: 500 },
+    deviceId: 'device-uuid',
+};
+const okCaptcha = { ok: true, required: false };
+const okSubmission = { id: 'batch-id', clips: [{ id: 'clip-a-id', status: 'submitted' }, { id: 'clip-b-id', status: 'submitted' }] };
+const okClips = [
+    { id: 'clip-a-id', status: 'complete', title: 'Clip A', audio_url: 'https://cdn1.suno.ai/clip-a-id.mp3' },
+    { id: 'clip-b-id', status: 'complete', title: 'Clip B', audio_url: 'https://cdn1.suno.ai/clip-b-id.mp3' },
+];
+
+beforeEach(() => {
+    vi.restoreAllMocks();
+    mocks.ensureSunoSession.mockReset().mockResolvedValue(okSession);
+    mocks.checkSunoCaptcha.mockReset().mockResolvedValue(okCaptcha);
+    mocks.submitSunoGeneration.mockReset().mockResolvedValue(okSubmission);
+    mocks.pollSunoClips.mockReset().mockResolvedValue(okClips);
+    mocks.downloadSunoClip.mockReset().mockResolvedValue({ slug: 'clip', written: [{ format: 'mp3', file: '/tmp/x.mp3', ok: true }, { format: 'metadata', file: '/tmp/x.json', ok: true }] });
+});
+
+describe('suno generate argument validation', () => {
+    it('rejects calls with neither a Simple prompt nor --lyrics', async () => {
+        await expect(generateCommand.func(createPage(), { sd: true, timeout: 60 })).rejects.toMatchObject({
+            code: 'ARGUMENT',
+            message: expect.stringContaining('Either provide a Simple-mode prompt'),
+        });
+    });
+
+    it('rejects --tags / --negative-tags in Simple mode', async () => {
+        await expect(generateCommand.func(createPage(), { prompt: 'foo', tags: 'lo-fi', sd: true, timeout: 60 })).rejects.toMatchObject({
+            code: 'ARGUMENT',
+            message: expect.stringContaining('only apply in Custom mode'),
+        });
+    });
+
+    it('rejects unsupported --model values', async () => {
+        await expect(generateCommand.func(createPage(), { prompt: 'foo', model: 'chirp-vNEXT', sd: true, timeout: 60 })).rejects.toMatchObject({
+            code: 'ARGUMENT',
+            message: expect.stringContaining('Unsupported --model'),
+        });
+    });
+
+    it('refuses to submit when planId is null (free-tier without resolved user_tier) (#1704)', async () => {
+        mocks.ensureSunoSession.mockResolvedValue({ ...okSession, planId: null, planKey: 'free' });
+        await expect(generateCommand.func(createPage(), { prompt: 'foo', sd: true, timeout: 60 })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: expect.stringContaining('plan id'),
+        });
+        expect(mocks.submitSunoGeneration).not.toHaveBeenCalled();
+    });
+
+    it('refuses to submit when credits are below the per-song minimum', async () => {
+        mocks.ensureSunoSession.mockResolvedValue({ ...okSession, totalCreditsAvailable: 5, breakdown: { ...okSession.breakdown, monthlyRemaining: 5 } });
+        await expect(generateCommand.func(createPage(), { prompt: 'foo', sd: true, timeout: 60 })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: expect.stringContaining('needs ~10 credits'),
+        });
+        expect(mocks.submitSunoGeneration).not.toHaveBeenCalled();
+    });
+
+    it('refuses to submit when captcha is required (out-of-scope for headless flow)', async () => {
+        mocks.checkSunoCaptcha.mockResolvedValue({ ok: true, required: true });
+        await expect(generateCommand.func(createPage(), { prompt: 'foo', sd: true, timeout: 60 })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: expect.stringContaining('CAPTCHA challenge'),
+        });
+        expect(mocks.submitSunoGeneration).not.toHaveBeenCalled();
+    });
+
+    it('refuses to submit when captcha pre-flight fails', async () => {
+        mocks.checkSunoCaptcha.mockResolvedValue({ ok: false, status: 500 });
+        await expect(generateCommand.func(createPage(), { prompt: 'foo', sd: true, timeout: 60 })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: expect.stringContaining('captcha pre-flight failed'),
+        });
+        expect(mocks.submitSunoGeneration).not.toHaveBeenCalled();
+    });
+});
+
+describe('suno generate Simple mode payload', () => {
+    it('routes the positional prompt through `description` (Simple mode)', async () => {
+        await generateCommand.func(createPage(), { prompt: 'lo-fi study beat', sd: true, timeout: 60 });
+        expect(mocks.submitSunoGeneration).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({
+            mode: 'simple',
+            description: 'lo-fi study beat',
+            lyrics: '',
+            tags: '',
+            negativeTags: '',
+            userTier: okSession.planId,
+            deviceId: okSession.deviceId,
+        }));
+    });
+});
+
+describe('suno generate Custom mode payload', () => {
+    it('routes --lyrics through `lyrics` and --tags through `tags`', async () => {
+        await generateCommand.func(createPage(), {
+            lyrics: '[Verse]\\nfoo',
+            tags: 'synthwave, 95 BPM',
+            'negative-tags': 'vocals',
+            title: 'Night Rain',
+            sd: true,
+            timeout: 60,
+        });
+        expect(mocks.submitSunoGeneration).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({
+            mode: 'custom',
+            lyrics: '[Verse]\\nfoo',
+            tags: 'synthwave, 95 BPM',
+            negativeTags: 'vocals',
+            title: 'Night Rain',
+        }));
+    });
+
+    it('threads --weirdness and --style-weight as numeric sliders', async () => {
+        await generateCommand.func(createPage(), {
+            lyrics: '[Verse]\\nfoo',
+            weirdness: '0.74',
+            'style-weight': '0.57',
+            sd: true,
+            timeout: 60,
+        });
+        expect(mocks.submitSunoGeneration).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({
+            weirdness: 0.74,
+            styleWeight: 0.57,
+        }));
+    });
+});
+
+describe('suno generate paid-format guard', () => {
+    it('skips wav by default and surfaces the skip in the result row', async () => {
+        const out = await generateCommand.func(createPage(), {
+            prompt: 'foo',
+            formats: 'mp3,wav,metadata',
+            timeout: 60,
+        });
+        // downloadSunoClip should be called with mp3+metadata, NOT wav
+        expect(mocks.downloadSunoClip).toHaveBeenCalledWith(expect.anything(), expect.anything(), expect.anything(), ['mp3', 'metadata'], okSession.deviceId);
+        expect(out[0].files).toContain('skipped(needs --confirm-paid):wav');
+    });
+
+    it('includes wav when --confirm-paid is true', async () => {
+        await generateCommand.func(createPage(), {
+            prompt: 'foo',
+            formats: 'mp3,wav',
+            'confirm-paid': true,
+            timeout: 60,
+        });
+        expect(mocks.downloadSunoClip).toHaveBeenCalledWith(expect.anything(), expect.anything(), expect.anything(), ['mp3', 'wav'], okSession.deviceId);
+    });
+
+    it('rejects before generation when every requested format is paid and unconfirmed', async () => {
+        await expect(generateCommand.func(createPage(), {
+            prompt: 'foo',
+            formats: 'wav',
+            timeout: 60,
+        })).rejects.toMatchObject({
+            code: 'ARGUMENT',
+            message: expect.stringContaining('All requested formats require'),
+        });
+        expect(mocks.submitSunoGeneration).not.toHaveBeenCalled();
+    });
+});
+
+describe('suno generate failure paths', () => {
+    it('reports all-failed clips with a typed error', async () => {
+        mocks.pollSunoClips.mockResolvedValue([
+            { id: 'clip-a-id', status: 'error' },
+            { id: 'clip-b-id', status: 'error' },
+        ]);
+        await expect(generateCommand.func(createPage(), { prompt: 'foo', sd: true, timeout: 60 })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: expect.stringContaining('All Suno clips failed'),
+        });
+    });
+
+    it('fails typed when generation response clips are malformed', async () => {
+        mocks.submitSunoGeneration.mockResolvedValue({ clips: [{ status: 'submitted' }] });
+        await expect(generateCommand.func(createPage(), { prompt: 'foo', sd: true, timeout: 60 })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: expect.stringContaining('malformed clip identity'),
+        });
+    });
+
+    it('fails typed when download post-condition writes no files', async () => {
+        mocks.downloadSunoClip.mockResolvedValue({ slug: 'clip', written: [{ format: 'mp3', file: null, ok: false, reason: 'HTTP 500' }] });
+        await expect(generateCommand.func(createPage(), { prompt: 'foo', formats: 'mp3', timeout: 60 })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: expect.stringContaining('wrote no files'),
+        });
+    });
+
+    it('skip-download mode returns generated rows without invoking downloadSunoClip', async () => {
+        const out = await generateCommand.func(createPage(), { prompt: 'foo', sd: true, timeout: 60 });
+        expect(out).toHaveLength(2);
+        expect(out[0].status).toBe('🎵 generated');
+        expect(mocks.downloadSunoClip).not.toHaveBeenCalled();
+    });
+});

package/clis/suno/list.js

@@ -0,0 +1,79 @@
+/**
+ * `opencli suno list` — list recent clips in the user's library. Lets agents
+ * discover clip ids without needing to remember them, and feed them to
+ * `opencli suno download`.
+ */
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import {
+    STUDIO_API,
+    SUNO_DOMAIN,
+    SUNO_URL,
+    ensureSunoSession,
+    requireNonNegativeInt,
+    requirePositiveInt,
+    unwrapEvaluateResult,
+} from './utils.js';
+
+export const listCommand = cli({
+    site: 'suno',
+    name: 'list',
+    access: 'read',
+    description: 'List recent Suno clips in your library (id, title, status, created_at, link)',
+    domain: SUNO_DOMAIN,
+    strategy: Strategy.COOKIE,
+    browser: true,
+    siteSession: 'persistent',
+    navigateBefore: false,
+    args: [
+        { name: 'limit', type: 'int', default: 20, help: 'Max clips to list (default: 20)' },
+        { name: 'page', type: 'int', default: 0, help: 'Pagination offset, 0-based (default: 0)' },
+    ],
+    columns: ['rank', 'clip', 'title', 'status', 'created', 'link'],
+    func: async (page, kwargs) => {
+        const limit = requirePositiveInt(kwargs.limit, '--limit');
+        const pageOffset = requireNonNegativeInt(kwargs.page ?? 0, '--page');
+
+        const session = await ensureSunoSession(page);
+        const deviceId = session.deviceId;
+
+        const result = unwrapEvaluateResult(await page.evaluate(`(async () => {
+            const browserToken = JSON.stringify({ token: btoa(JSON.stringify({ timestamp: Date.now() })) });
+            const res = await fetch('${STUDIO_API}/api/feed/v2?page=${pageOffset}', {
+                headers: {
+                    'Authorization': 'Bearer ' + (await window.Clerk.session.getToken()),
+                    'browser-token': browserToken,
+                    'device-id': ${JSON.stringify(deviceId)},
+                },
+            });
+            if (!res.ok) return { ok: false, status: res.status };
+            const data = await res.json().catch(() => null);
+            if (!data || !Array.isArray(data.clips)) return { ok: false, error: 'malformed clips payload' };
+            return { ok: true, clips: data.clips };
+        })()`));
+
+        if (!result?.ok) {
+            throw new CommandExecutionError(result?.error || `Suno feed lookup failed (HTTP ${result?.status || '?'}).`);
+        }
+        if (!Array.isArray(result.clips)) {
+            throw new CommandExecutionError('Suno feed lookup returned malformed clips payload');
+        }
+        if (result.clips.length === 0) {
+            throw new EmptyResultError('suno list', 'No Suno clips found in your library.');
+        }
+
+        return result.clips.slice(0, limit).map((c, i) => {
+            if (!c || typeof c.id !== 'string' || !c.id) {
+                throw new CommandExecutionError('Suno feed lookup returned malformed clip identity');
+            }
+            return {
+                rank: i + 1 + pageOffset * limit,
+                clip: c.id.slice(0, 8),
+                title: c.title || '(untitled)',
+                status: c.status || '?',
+                created: (c.created_at || '').replace('T', ' ').replace(/\..*$/, '').replace(/Z$/, ''),
+                link: `${SUNO_URL}/song/${c.id}`,
+            };
+        });
+    },
+});

package/clis/suno/status.js

@@ -0,0 +1,63 @@
+/**
+ * `opencli suno status` — quick health check: login state, plan, credit
+ * breakdown, captcha readiness. Lets agents pre-flight before spending
+ * generate credits.
+ */
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
+import {
+    SUNO_DOMAIN,
+    checkSunoCaptcha,
+    ensureSunoSession,
+} from './utils.js';
+
+export const statusCommand = cli({
+    site: 'suno',
+    name: 'status',
+    access: 'read',
+    description: 'Check Suno login, plan, credit balance, and captcha readiness',
+    domain: SUNO_DOMAIN,
+    strategy: Strategy.COOKIE,
+    browser: true,
+    siteSession: 'persistent',
+    navigateBefore: false,
+    args: [],
+    columns: ['Status', 'Plan', 'Credits', 'Monthly', 'Captcha'],
+    func: async (page) => {
+        let session;
+        try {
+            session = await ensureSunoSession(page);
+        } catch (err) {
+            if (err instanceof AuthRequiredError) {
+                return [{
+                    Status: 'Not logged in',
+                    Plan: '-',
+                    Credits: '-',
+                    Monthly: '-',
+                    Captcha: '-',
+                }];
+            }
+            throw err;
+        }
+        let captcha;
+        try {
+            captcha = await checkSunoCaptcha(page, session.deviceId);
+        } catch (err) {
+            // Conservative: assume captcha is required when the pre-flight
+            // probe fails, so the displayed status doesn't claim "Not required"
+            // for an unverified state.
+            captcha = { required: true };
+        }
+        const b = session.breakdown;
+        // ensureSunoSession surfaces planKey derived from billing/info's
+        // subscription_type vs plans[] lookup; planId may be null for accounts
+        // whose plan cannot be resolved against plans[] (e.g., new schema fields).
+        return [{
+            Status: 'Connected',
+            Plan: session.planKey,
+            Credits: String(session.totalCreditsAvailable),
+            Monthly: `${b.monthlyRemaining}/${b.monthlyLimit}`,
+            Captcha: captcha?.required === true ? 'Required (solve in UI)' : 'Not required',
+        }];
+    },
+});