Quick start
1. Install
Section titled “1. Install”npm install -g shipcard# or run it without installing:npx shipcard <owner/repo>Requires Node.js ≥ 18.
2. Make a card from GitHub
Section titled “2. Make a card from GitHub”Point shipcard at any public repository as owner/repo. It fetches the
metadata and language breakdown from the GitHub REST API and writes a
standalone SVG:
shipcard abdulmunimjemal/shipcard -o card.svgThat’s a complete card — name, description, a colored language bar with a
legend, and the star/fork counts — sized 1200×630 for social previews. With no
-o, the SVG is written to stdout, so you can pipe it:
shipcard facebook/react > react.svgLift the rate limit (optional)
Section titled “Lift the rate limit (optional)”Unauthenticated GitHub requests are rate limited. If you hit a 403, set
GITHUB_TOKEN to authenticate — any token with public-repo read access works:
GITHUB_TOKEN=ghp_xxx shipcard facebook/react -o react.svg3. Or build one offline from a local repo
Section titled “3. Or build one offline from a local repo”Local mode needs no network and no token. It reads package.json for the
name and description, parses the git origin remote for owner/repo, and
computes the language breakdown by scanning file extensions (skipping
node_modules, .git, dist, and similar noise):
shipcard --local . # current directory, SVG to stdoutshipcard --local ../my-project -o my-project.svgThis is handy in CI for a repo that isn’t on GitHub yet, or when you want a card built from the working tree rather than the published metadata.
4. Pick a theme and size
Section titled “4. Pick a theme and size”The default is a dark card at the og social size. Switch either one:
shipcard abdulmunimjemal/shipcard --theme light --size card -o card.svg--theme dark|light— dark is the default.--size og|card—ogis 1200×630 (social);cardis a compact 800×320.
See Customization for the full palette and sizing details.
5. Embed it
Section titled “5. Embed it”The output is a plain SVG, so it drops straight into a README:
…or into a page’s social-preview tags:
<meta property="og:image" content="https://example.com/card.svg" />Optional: a one-line AI summary
Section titled “Optional: a one-line AI summary”To replace the description with a punchy generated line, add --summary and
supply your own OPENAI_API_KEY. Without the flag, no AI calls are made:
OPENAI_API_KEY=sk-xxx shipcard abdulmunimjemal/shipcard --summary -o card.svgSee Customization → AI summary for pointing it at any OpenAI-compatible gateway.