Create embeddable GitHub profile and repository card images with the ghcard CLI, design custom card layouts, and add them to README files. Use when the user wants a GitHub stats card, a profile card, a repo card or banner, a social preview image for a repository, or to put such a card in a README or profile README (github.com//). Also covers listing, deleting, and checking quota for GitHubCard cards.
GitHubCard cards with ghcard
ghcard turns a GitHub username or owner/repo into a published card image
with stable SVG/PNG links and ready-made Markdown/HTML embeds. Card images
show live GitHub data, so a card never needs regenerating to stay current.
Before you start
- Check the CLI is installed:
ghcard --version(this skill is written for 0.1.0 or later). If it is missing and Node.js 20+ is available, run it through npx without installing: replaceghcardwithnpx -y @ghcardhq/ghcardin every command below. Suggestnpm install -g @ghcardhq/ghcardto the user if they will use it again; do not install global packages without asking. - Check auth:
ghcard auth status --json.- Exit code 3 /
NO_API_KEYorUNAUTHORIZED: the user needs a key from https://githubcard.com/dashboard. Ask them to runghcard auth loginthemselves, or to setGHCARD_API_KEY. Never ask the user to paste the key into the chat, and never echo, log, or write a key into a file in the repository. - Listing templates/palettes works without a key.
- Exit code 3 /
Always pass --json and read stdout as one JSON document:
{"ok": true, "data": ...} or
{"ok": false, "error": {"code", "message", "retryable", "hint"}}.
Main flows
Card for a profile or repo (the common case):
ghcard create octocat --json
ghcard create octocat/hello-world --json
Use data.urls.svg / data.urls.png for links and data.embed.markdown
for a README. data.created is false when the identical card already
existed, which is expected and fine.
Add it to a README (inserts after the first heading, or replaces the
existing <!-- ghcard:<subject> --> block on later runs):
ghcard create octocat --readme README.md --json
For a GitHub profile README the file lives in the repo named after the
user (<user>/<user>/README.md). Show the user the diff before
committing; do not commit or push unless they ask.
Choose a look only if the user cares about style:
ghcard templates --scope profile --free --json # or --scope repo
ghcard templates --scope profile --free --widget streak --json # must contain these widgets
ghcard palettes --json
ghcard create octocat --template pro-terminal --palette sage --json
Each template lists its widgets. --palette takes only preset ids; for
any other background colour, font, size, or widget changes, use a custom
layout (below). When several templates qualify, start from the one whose
size and widgets need the fewest edits.
Template scope must match the subject: profile templates for a user,
repo templates for owner/repo (templates with scope all fit both).
Prefer templates with "pro": false unless the user has Pro
(ghcard usage --json → data.tier).
Custom layout when the user wants specific widgets, colours, fonts, or sizes that no template has:
ghcard components --json # widget types
ghcard design init social --subject octocat -o design.json --json # template as JSON (free, no quota)
# edit design.json: artboard (width, height, background.color, style.*) and layers[]
ghcard create octocat --design design.json --dry-run --json # free check: ids, Pro features, layout
ghcard create octocat --design design.json --json # publish it
Always --dry-run an edited design first: it catches every request error
without creating a card or using quota, and data.warnings lists layers
that reach outside the artboard (they would be clipped). Fix warnings
before publishing. When you darken or lighten the background a lot, also
set artboard.style.textColor / secondaryTextColor so text stays readable.
Prefer a template that already has exactly the widgets the user wants
(--widget to filter, then check each candidate's widgets for ones to
avoid); edit layers only when no template fits.
Editing rules (ghcard design --help has the full list):
- Layers are absolutely positioned (
x,y,width,height). Removing one leaves its space empty; widen or move neighbours to fill it. - Keep each layer's
idunique and itstypefromghcard components.layeris only stacking order; gaps are fine. - The subject inside the file is ignored; the
createargument decides whose data is shown.showWatermarkis decided by the server. artboard.background.coloris a full CSS background: a hex colour, or a gradient/pattern such asradial-gradient(...) 0 0 / 22px 22px #0d1117. Replacing it with a hex removes the template's texture; to keep the texture, change only the trailing base colour.- Any plain solid colour (
"#14213d") is free; gradients and patterns are free only when they are a free preset, aghcard palettespalette, or a free template's own background. On Free, the editor's Pro fonts and background presets fail withPRO_FEATURE; fonts and backgrounds that free templates already use are fine.
To change an existing card: ghcard design get <card-id> -o design.json,
edit, and publish again (this creates a new card; the old link keeps
working until deleted). Keep each layer's id unique and its type from
ghcard components. ghcard open <card-id> --print gives the web editor
link if the user would rather drag things around themselves.
Download the image instead of linking it:
ghcard create octocat --format png --output card.png --json.
Flags combine in one call (one quota unit): --design, --format,
--output, --readme. --format decides which link is printed and which
image --output saves; --readme always embeds the live SVG link. So a
PNG file and a README card is one call:
--format png --output card.png --readme README.md.
Links: share data.urls (live: they re-render with current GitHub data).
data.snapshotUrls are frozen images of the moment the card was created;
use them only when the user asks for an image that never changes.
Manage cards: ghcard list --json, ghcard usage --json.
ghcard delete <id> --yes --json breaks every place the card is
embedded, so confirm with the user first.
Handling errors
Branch on error.code (or the exit code), and use error.hint:
| Code / exit | What to do |
|---|---|
UNKNOWN_TEMPLATE, TEMPLATE_SCOPE_MISMATCH (2) | List templates for the right scope and pick a valid id |
UNKNOWN_PALETTE (2) | List palettes, or drop --palette |
INVALID_REQUEST (2) | Fix the argument named in error.details.field |
PRO_TEMPLATE (1) | Pick a free template, or tell the user it needs Pro |
PRO_FEATURE (1) | The design uses a Pro font/background (error.details.features lists each path); swap them for free ones or tell the user |
INVALID_DESIGN (2) | Fix the design as error.message says; re-start from ghcard design init if unsure |
SUBJECT_NOT_FOUND (4) | Check spelling; private repositories are not supported |
NO_API_KEY, UNAUTHORIZED (3) | See "Before you start" |
QUOTA_EXCEEDED (5) | Stop. Tell the user the daily quota resets at 00:00 UTC (error.details.resetAt) |
GITHUB_DATA_NOT_READY, GITHUB_CAPACITY (6) | Wait error.details.retryAfterSeconds (or ~30s) and repeat the identical command; at most 5 attempts in total |
CARD_GENERATION_IN_PROGRESS, NETWORK_ERROR (6) | A first card can take minutes to render. Wait ~30s and repeat the identical command; it resumes the same card. At most 5 attempts in total |
CARD_GENERATION_FAILED (6) | A server-side rendering failure, not your request (a --dry-run that passes proves the request is fine). Repeat at most 2 more times, then stop and report it |
Failed calls are refunded (ghcard usage shows the same used before and
after), so repeating the identical command never costs extra quota. When
you stop, tell the user which step failed and the last error.message.
error.hint gives the same rule for each code.
Things to avoid
- Calling
ghcard createrepeatedly to "refresh" a card: each call costs quota and the link already shows live data. - Hand-building
githubcard.comURLs: use the links the CLI returns. - Passing
--no-watermarkon a Free account: the server keeps the watermark anyway; mention that removing it is a Pro feature.
MCP alternative
If GitHubCard MCP tools are available (create_card, validate_card,
list_templates, list_palettes, list_components, get_template_design,
get_card_design, list_cards, delete_card, get_usage), they do the
same things and return the same error codes; use whichever is available.
This plugin adds the hosted server at https://githubcard.com/mcp. Its tools
cannot edit files, so insert embed.markdown into the README yourself, or
use ghcard create ... --readme.
- Downloads
- 184All time
- Security audit
- Pass
- Last updated
- 3w ago
- Current version
- v1.0.1
- License
- MIT-0
