ghcard

Generate GitHubCard profile and repository cards from the command line, from CI, or from an AI agent over MCP.

npx -y @ghcardhq/ghcard create octocat                     # profile card; prints its README snippet
npx -y @ghcardhq/ghcard create octocat/hello-world         # repository card
npx -y @ghcardhq/ghcard create octocat --embed markdown    # just the README snippet
npx -y @ghcardhq/ghcard create octocat --readme README.md  # insert or update it in a README
npx -y @ghcardhq/ghcard create octocat -f png -o card.png  # download the image

Install

Needs Node.js 20 or later.

npm install -g @ghcardhq/ghcard

Either way the command is ghcard. Or run it without installing: npx -y @ghcardhq/ghcard <command>. The examples below assume a global install.

Related MCP server: profilekit-mcp

Authenticate

Creating cards needs an API key. Create one on your dashboard, then:

ghcard auth login                          # paste the key at the prompt
echo "$KEY" | ghcard auth login --with-token
ghcard auth status

The key is saved to <user config dir>/ghcard/config.json with mode 0600. GHCARD_API_KEY (or --api-key) overrides it, which is the way to pass a key in CI. ghcard auth logout removes the saved key; revoke keys on the dashboard.

Listing templates, palettes and components needs no key. On a terminal, a command that needs a key and finds none offers to log in on the spot, then carries on.

Commands

ghcard create flags: --template/-t, --palette/-p, --design/-d FILE|-, --format/-f svg|png, --embed/-e markdown|html|url, --output/-o FILE, --readme FILE, --snapshot, --dry-run (check without creating or using quota), --no-watermark (Pro), --verbose (also print the image links).

On a terminal, create prints the card's Markdown snippet and its editor link; --verbose adds the SVG, PNG and HTML links. Piped output and --json always carry every link.

Shell completion:

echo 'eval "$(ghcard completion zsh)"' >> ~/.zshrc    # or bash: ~/.bashrc

Custom layouts

ghcard design init social -o design.json      # or: ghcard design get <card-id> -o design.json
$EDITOR design.json                           # artboard size/colours/fonts, layers[]
ghcard create octocat --design design.json

The design's own subject is ignored; the create argument decides whose data it shows. Layer types come from ghcard components. On Free, Pro fonts and backgrounds fail with PRO_FEATURE, and error.details.features lists them.

Idempotent by design

The same subject, template, palette and watermark setting always return the same card and link ("created": false on repeats). Running ghcard create me --readme README.md on every CI push keeps one card and one README block. Card images show live GitHub data, so there is no need to regenerate a card to refresh it.

Every ghcard create call counts once against the daily quota (Free 100, Pro 5000, reset 00:00 UTC). Failed calls are not counted.

Scripting and agents

Output is human-readable on a terminal and a single JSON document when stdout is piped, or with --json:

{"ok": true,  "data": { ... }}
{"ok": false, "error": {"code": "UNKNOWN_TEMPLATE", "message": "...", "retryable": false, "hint": "..."}}

Progress messages go to stderr. Exit codes:

cards delete asks for confirmation on a terminal and requires --yes otherwise.

MCP server

The quickest way to use GitHubCard from an AI agent is the hosted server at https://githubcard.com/mcp; setup for each client is in ghcardhq/githubcard-mcp.

ghcard mcp runs the same tools locally over stdio. It adds update_readme when started with --allow-file-writes, so the agent can edit a README on your disk. Tools: create_card (template or custom design), validate_card (free dry run), list_templates, list_palettes, list_components, get_template_design, get_card_design, list_cards, delete_card, get_usage.

Listing tools, templates, palettes and components works without a key. Creating cards needs GHCARD_API_KEY: sign in at githubcard.com/dashboard and create a free key under API keys. It starts with ghc_.

Claude Code:

claude mcp add githubcard --env GHCARD_API_KEY=ghc_live_... -- npx -y @ghcardhq/ghcard mcp

Claude Desktop, Cursor, and other clients (mcpServers config):

{
  "mcpServers": {
    "githubcard": {
      "command": "npx",
      "args": ["-y", "@ghcardhq/ghcard", "mcp"],
      "env": { "GHCARD_API_KEY": "ghc_live_..." }
    }
  }
}

Docker (the image runs ghcard mcp):

docker build -t ghcard https://github.com/ghcardhq/ghcard.git
docker run -i --rm -e GHCARD_API_KEY ghcard

Failed tool calls return isError: true with the same code, retryable flag and a hint the model can act on.

Claude Code skill

The githubcard skill teaches Claude Code when and how to use ghcard. It lives in ghcardhq/skills:

claude plugin marketplace add ghcardhq/skills
claude plugin install githubcard@githubcard

Development

npm install
npm test
npm run typecheck
GHCARD_BASE_URL=http://localhost:5173 npm run dev -- templates

Releases: bump version in package.json, then push a matching v* tag. The release workflow publishes @ghcardhq/ghcard to npm through trusted publishing, so no npm token is stored in the repository and each release carries provenance.

License

MIT