| handle | Your Suno handle (auto-discovery mode — fetches all public songs). | no | — |
| manifest_path | Path to a YAML file listing song IDs. Used if `handle` is not set. | no | ./suno-songs.yml |
| song_ids | Comma-separated list of Suno song IDs. Alternative to manifest_path. | no | — |
| sort | Sort order: created_at | play_count | upvote_count | name | no | created_at |
| max | Maximum number of song cards to render (1-20). | no | 6 |
| include_tags | Only include songs with any of these tags (CSV, case-insensitive). | no | — |
| exclude_tags | Exclude songs with any of these tags (CSV, case-insensitive). | no | — |
| min_duration | Minimum song duration in seconds. | no | — |
| max_duration | Maximum song duration in seconds. | no | — |
| min_plays | Minimum play count to include a song. | no | — |
| min_likes | Minimum upvote count to include a song. | no | — |
| pinned_first | Respect the `is_pinned` flag above the sort order. | no | true |
| featured | CSV of song UUIDs to pin above everything else. | no | — |
| allow_explicit | Include songs marked explicit. | no | true |
| show_profile_card | Render a profile summary card above the song cards. | no | true |
| layout | Card layout: `classic` (info-dense) or `player` (Suno-style with progress bar). | no | classic |
| preset | Color preset: `default` (purple) or `suno` (navy + gold). | no | default |
| show_progress | Show progress bar with play button (default: true for player layout). | no | — |
| show_logo | Show SUNO logo in bottom-right. | no | — |
| show_link_icon | Show link icon in top-right. | no | — |
| render_mode | `service` (default, live cards via hosted Vercel URL) or `local` (pre-render SVGs into your repo). | no | service |
| local_cards_dir | Directory relative to README to write SVGs into. Only used in local mode. | no | .suno-cards |
| readme_path | Path to the README file to update. | no | ./README.md |
| comment_tag_name | HTML comment marker name. Allows multiple action instances in one README. | no | SUNO-CARDS |
| output_type | `markdown` or `html`. HTML uses <picture> for dark/light theme. | no | markdown |
| theme | `auto` (default), `dark`, or `light`. | no | auto |
| lang | `en`, `zh`, or `ja`. | no | en |
| width | Card width in pixels (200-1200). | no | — |
| bg_color | Card background color (hex, with or without `#`). | no | — |
| text_color | Card title / primary text color. | no | — |
| accent_color | Accent color (equalizer bars, chips, stats numbers). | no | — |
| base_url | Base URL of the hosted card service. | no | https://github-readme-suno-cards.vercel.app |
| output_only | Skip writing to README — emit results only via action outputs. | no | false |
| commit_message | Commit message for README updates. | no | chore(suno-cards): update README |
| committer_username | Git committer username. | no | github-actions[bot] |
| committer_email | Git committer email. | no | 41898282+github-actions[bot]@users.noreply.github.com |