Skip to main content
Glama

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

Command

What it does

ghcard create <user|owner/repo>

Create a card, or reuse the identical one, and print its links

ghcard list [--all]

List the cards your account generated

ghcard delete <id>... [--yes]

Delete cards; their links stop working

ghcard design init <template> [-o FILE]

Write a template's layout as an editable design (no key, no quota)

ghcard design get <card-id> [-o FILE]

Export one of your cards' design

ghcard open <card-id> [--print]

Open a card in the web editor

ghcard templates [--scope profile|repo] [--free]

Layout ids for --template

ghcard palettes

Background ids for --palette

ghcard components

Widget types a card can contain

ghcard usage

Your plan and today's card quota

ghcard auth login|status|logout

Manage the stored key

ghcard mcp

Run as an MCP server for AI agents

ghcard completion bash|zsh|fish

Print a shell completion script

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 <your-username> --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:

Code

Meaning

0

Success

1

Other error (for example, a Pro-only template on Free)

2

Invalid usage or arguments; fix the command

3

Missing, invalid, or revoked API key

4

Not found (user, repository, or card)

5

Quota exhausted; see error.details.retryAfterSeconds

6

Temporarily unavailable; retrying is safe

ghcard 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_live_.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers