shieldcn

https://shieldcn.dev/docs
Admin
shieldcn is a modern, high-performance badge generation engine and CLI that auto-detects project...
Tokens:72,957
Snippets:896
Trust Score:5.2
Update:2 months ago
Show doc for...
Tokens:
Raw
### Usage examples for AI agents

Source: https://shieldcn.dev/docs/skill

Example prompts for requesting badge generation from an agent with the skill installed.

```text
Add npm and GitHub badges to the README.
Use size xs, the ghost variant, and make them work in both light and dark mode.
```

```text
Migrate the existing Shields.io badges in this README to shieldcn.
Undo any split-style/two-tone badges: use single-surface badges and remove split=true, labelColor, and split-label styling unless explicitly needed.
```

```text
Add a shieldcn npm downloads chart for this package below the intro.
Make it transparent, link it to the npm page, and keep it readable in both light and dark mode.
```

```text
Add a CI status badge for this repo
```

```text
Add shieldcn badges to the docs
```

```text
Set up a badge row with stars, license, and version
```

--------------------------------

### Quick Badge Examples

Source: https://shieldcn.dev/docs/badges/gitlab

Common examples for embedding GitLab badges in Markdown.

```markdown
![stars](https://shieldcn.dev/gitlab/inkscape/inkscape/stars.svg)
```

```markdown
![pipeline](https://shieldcn.dev/gitlab/inkscape/inkscape/pipeline.svg?variant=branded)
```

```markdown
![release](https://shieldcn.dev/gitlab/inkscape/inkscape/release.svg)
```

--------------------------------

### GET /skills/installs/{owner}/{repo}/{skill}

Source: https://shieldcn.dev/docs/badges/skills

Retrieves a badge showing the all-time install count for a specific skill.

```APIDOC
## GET /skills/installs/{owner}/{repo}/{skill}

### Description
Returns an SVG badge displaying the all-time install count for the specified skill.

### Method
GET

### Endpoint
/skills/installs/{owner}/{repo}/{skill}

### Parameters
#### Path Parameters
- **owner** (string) - Required - The GitHub repository owner.
- **repo** (string) - Required - The GitHub repository name.
- **skill** (string) - Required - The skill slug.
```

--------------------------------

### GitLab Release Copy-Paste Examples

Source: https://shieldcn.dev/docs/badges/gitlab

Examples for default and branded release badge variants.

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/gitlab/inkscape/inkscape/release.svg?mode=dark"><img alt="release" src="https://shieldcn.dev/gitlab/inkscape/inkscape/release.svg?mode=light"></picture>
```

```markdown
![release](https://shieldcn.dev/gitlab/inkscape/inkscape/release.svg?variant=branded)
```

--------------------------------

### Install BadgePreview component

Source: https://shieldcn.dev/docs/registry

Install the BadgePreview component for visual badge rendering.

```bash
pnpm dlx shadcn@latest add @shieldcn/badge-preview
```

--------------------------------

### GET /homebrew/installs/{formula}/{days}

Source: https://shieldcn.dev/docs/badges/homebrew

Retrieves the install count badge for a formula over a specified period.

```APIDOC
## GET /homebrew/installs/{formula}/{days}

### Description
Returns an install count badge for a formula based on the provided time period.

### Method
GET

### Endpoint
/homebrew/installs/{formula}/{days}

### Parameters
#### Path Parameters
- **formula** (string) - Required - The name of the Homebrew formula.
- **days** (integer) - Optional - The number of days for the install count (30, 90, or 365).
```

--------------------------------

### Tokscale Cost Copy-Paste Examples

Source: https://shieldcn.dev/docs/badges/tokscale

Markdown and HTML examples for embedding the cost badge.

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/tokscale/cost/junhoyeo.svg?mode=dark"><img alt="tokscale cost" src="https://shieldcn.dev/tokscale/cost/junhoyeo.svg?mode=light"></picture>
```

```markdown
![tokscale cost](https://shieldcn.dev/tokscale/cost/junhoyeo.svg?variant=branded)
```

--------------------------------

### Install ReadmeBadge component

Source: https://shieldcn.dev/docs/registry

Install the ReadmeBadge component using your preferred package manager.

```bash
pnpm dlx shadcn@latest add @shieldcn/readme-badge
```

--------------------------------

### Install shieldcn CLI

Source: https://shieldcn.dev/docs/cli

Installation commands for global usage via various package managers.

```bash
# Run without installing (recommended)
npx shieldcn-cli

# Or install globally
npm install -g shieldcn-cli

# Or with your preferred package manager
pnpm add -g shieldcn-cli
yarn global add shieldcn-cli
bun add -g shieldcn-cli
```

--------------------------------

### Copy-paste receiving examples

Source: https://shieldcn.dev/docs/badges/liberapay

Examples for embedding the receiving badge in default and branded styles.

```markdown
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/liberapay/receiving/Changaco.svg?mode=dark"><img alt="receiving" src="https://shieldcn.dev/liberapay/receiving/Changaco.svg?mode=light"></picture>
```

```markdown
![receiving](https://shieldcn.dev/liberapay/receiving/Changaco.svg?variant=branded)
```

--------------------------------

### Copy-paste goal examples

Source: https://shieldcn.dev/docs/badges/liberapay

Examples for embedding the goal badge in default and branded styles.

```markdown
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/liberapay/goal/Changaco.svg?mode=dark"><img alt="goal" src="https://shieldcn.dev/liberapay/goal/Changaco.svg?mode=light"></picture>
```

```markdown
![goal](https://shieldcn.dev/liberapay/goal/Changaco.svg?variant=branded)
```

--------------------------------

### Install skill globally

Source: https://shieldcn.dev/docs/skill

Makes the skill available across all projects.

```bash
npx skills add jal-co/shieldcn -g
```

--------------------------------

### License Badge Examples

Source: https://shieldcn.dev/docs/badges/npm

Examples of license badges for package pages and footers.

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/npm/license/react.svg?mode=dark"><img alt="license" src="https://shieldcn.dev/npm/license/react.svg?mode=light"></picture>
```

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/npm/license/react.svg?variant=ghost&amp;mode=dark"><img alt="license" src="https://shieldcn.dev/npm/license/react.svg?variant=ghost&amp;mode=light"></picture>
```

--------------------------------

### GET /vscode/installs/{publisher}/{extension}

Source: https://shieldcn.dev/docs/badges/vscode

Retrieves an install count badge for a specific VS Code extension.

```APIDOC
## GET /vscode/installs/{publisher}/{extension}

### Description
Returns an SVG badge showing the total install count for the specified VS Code extension.

### Method
GET

### Endpoint
/vscode/installs/{publisher}/{extension}

### Parameters
#### Path Parameters
- **publisher** (string) - Required - The publisher of the extension.
- **extension** (string) - Required - The name of the extension.
```

--------------------------------

### Tokscale Tokens Copy-Paste Examples

Source: https://shieldcn.dev/docs/badges/tokscale

Markdown and HTML examples for embedding the tokens badge.

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/tokscale/tokens/junhoyeo.svg?mode=dark"><img alt="tokscale tokens" src="https://shieldcn.dev/tokscale/tokens/junhoyeo.svg?mode=light"></picture>
```

```markdown
![tokscale tokens](https://shieldcn.dev/tokscale/tokens/junhoyeo.svg?variant=branded)
```

--------------------------------

### Skill Installs URL Formats

Source: https://shieldcn.dev/docs/badges/skills

The endpoint supports two URL patterns for retrieving the install count badge.

```text
/skills/installs/{owner}/{repo}/{skill}.svg
```

```text
/skills/{owner}/{repo}/{skill}.svg
```

--------------------------------

### Install shieldcn skill

Source: https://shieldcn.dev/docs/skill

Installs the shieldcn-badges skill to the coding agent.

```bash
npx skills add jal-co/shieldcn
```

--------------------------------

### Aligned commit history comparison

Source: https://shieldcn.dev/docs/charts

Markdown example using the align parameter to compare user trajectories starting from account creation.

```markdown
![aligned commit history comparison](https://shieldcn.dev/chart/github/commits/gaearon,sindresorhus.svg?align=true&theme=violet)
```

--------------------------------

### Tokscale Active Days Copy-Paste Examples

Source: https://shieldcn.dev/docs/badges/tokscale

Markdown and HTML examples for embedding the active days badge.

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/tokscale/active-days/junhoyeo.svg?mode=dark"><img alt="tokscale active days" src="https://shieldcn.dev/tokscale/active-days/junhoyeo.svg?mode=light"></picture>
```

```markdown
![tokscale active days](https://shieldcn.dev/tokscale/active-days/junhoyeo.svg?variant=branded)
```

--------------------------------

### Copy-paste patrons examples

Source: https://shieldcn.dev/docs/badges/liberapay

Examples for embedding the patrons badge in default and branded styles.

```markdown
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/liberapay/patrons/Changaco.svg?mode=dark"><img alt="patrons" src="https://shieldcn.dev/liberapay/patrons/Changaco.svg?mode=light"></picture>
```

```markdown
![patrons](https://shieldcn.dev/liberapay/patrons/Changaco.svg?variant=branded)
```

--------------------------------

### Tokscale Rank Copy-Paste Examples

Source: https://shieldcn.dev/docs/badges/tokscale

Markdown and HTML examples for embedding the rank badge.

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/tokscale/rank/junhoyeo.svg?mode=dark"><img alt="tokscale rank" src="https://shieldcn.dev/tokscale/rank/junhoyeo.svg?mode=light"></picture>
```

```markdown
![tokscale rank](https://shieldcn.dev/tokscale/rank/junhoyeo.svg?variant=branded)
```

--------------------------------

### Quick Markdown Examples

Source: https://shieldcn.dev/docs/badges/modrinth

Basic Markdown syntax for embedding Modrinth badges.

```markdown
![downloads](https://shieldcn.dev/modrinth/downloads/sodium.svg)
```

```markdown
![version](https://shieldcn.dev/modrinth/v/fabric-api.svg?variant=branded)
```

--------------------------------

### GitLab Stars Copy-Paste Examples

Source: https://shieldcn.dev/docs/badges/gitlab

Examples for default and branded star count badge variants.

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/gitlab/inkscape/inkscape/stars.svg?mode=dark"><img alt="stars" src="https://shieldcn.dev/gitlab/inkscape/inkscape/stars.svg?mode=light"></picture>
```

```markdown
![stars](https://shieldcn.dev/gitlab/inkscape/inkscape/stars.svg?variant=branded)
```

--------------------------------

### GET /skills/installs/:owner/:repo/:skill.svg

Source: https://shieldcn.dev/docs/badges/skills

Retrieves an SVG badge showing the all-time install count for a specific skill.

```APIDOC
## GET /skills/installs/:owner/:repo/:skill.svg

### Description
Show the all-time install count for a skill.

### Method
GET

### Endpoint
/skills/installs/:owner/:repo/:skill.svg

### Parameters
#### Path Parameters
- **owner** (string) - Required - The owner of the repository.
- **repo** (string) - Required - The repository name.
- **skill** (string) - Required - The skill name.
```

--------------------------------

### GitHub Download Badge HTML/Markdown Examples

Source: https://shieldcn.dev/docs/badges/github

Copy-paste examples for embedding download badges using HTML picture elements or Markdown image syntax.

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/github/downloads/atom/atom.svg?mode=dark"><img alt="github downloads" src="https://shieldcn.dev/github/downloads/atom/atom.svg?mode=light"></picture>
```

```markdown
![github downloads latest](https://shieldcn.dev/github/downloads/atom/atom/latest.svg?variant=branded)
```

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/github/downloads-asset/atom/atom/atom-amd64.deb.svg?mode=dark"><img alt="github asset downloads" src="https://shieldcn.dev/github/downloads-asset/atom/atom/atom-amd64.deb.svg?mode=light"></picture>
```

--------------------------------

### Install skill to specific agent

Source: https://shieldcn.dev/docs/skill

Targets a specific coding agent for the skill installation.

```bash
npx skills add jal-co/shieldcn -a claude-code
```

```bash
npx skills add jal-co/shieldcn -a cursor
```

--------------------------------

### Weblate languages copy-paste examples

Source: https://shieldcn.dev/docs/badges/weblate

Examples for default and branded language count badges.

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/weblate/languages/hosted.weblate.org/weblate/application.svg?mode=dark"><img alt="languages" src="https://shieldcn.dev/weblate/languages/hosted.weblate.org/weblate/application.svg?mode=light"></picture>
```

```markdown
![languages](https://shieldcn.dev/weblate/languages/hosted.weblate.org/weblate/application.svg?variant=branded)
```

--------------------------------

### Weblate translation copy-paste examples

Source: https://shieldcn.dev/docs/badges/weblate

Examples for default and branded translation percentage badges.

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/weblate/translation/hosted.weblate.org/weblate/application.svg?mode=dark"><img alt="translation" src="https://shieldcn.dev/weblate/translation/hosted.weblate.org/weblate/application.svg?mode=light"></picture>
```

```markdown
![translation](https://shieldcn.dev/weblate/translation/hosted.weblate.org/weblate/application.svg?variant=branded)
```

--------------------------------

### GitHub Forks Badge HTML/Markdown Examples

Source: https://shieldcn.dev/docs/badges/github

Copy-paste examples for embedding fork count badges.

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/github/forks/vercel/next.js.svg?mode=dark"><img alt="badge" src="https://shieldcn.dev/github/forks/vercel/next.js.svg?mode=light"></picture>
```

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/github/forks/vercel/next.js.svg?mode=dark"><img alt="forks" src="https://shieldcn.dev/github/forks/vercel/next.js.svg?mode=light"></picture>
```

```markdown
![forks](https://shieldcn.dev/github/forks/vercel/next.js.svg?variant=branded)
```

--------------------------------

### Install ReadmeBadgeRow component

Source: https://shieldcn.dev/docs/registry

Install the ReadmeBadgeRow component for horizontal badge layouts.

```bash
pnpm dlx shadcn@latest add @shieldcn/readme-badge-row
```

--------------------------------

### Discord Members Copy-Paste Examples

Source: https://shieldcn.dev/docs/badges/discord

Examples for embedding the members badge in Markdown or HTML.

```markdown
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/discord/members/reactiflux.svg?mode=dark"><img alt="discord members" src="https://shieldcn.dev/discord/members/reactiflux.svg?mode=light"></picture>
```

```markdown
![discord members](https://shieldcn.dev/discord/members/reactiflux.svg?variant=branded)
```

--------------------------------

### Display VS Code extension install count badge

Source: https://shieldcn.dev/docs/badges/vscode

Markdown syntax for embedding the install count badge for a specific extension.

```markdown
![installs](https://shieldcn.dev/vscode/installs/esbenp/prettier-vscode.svg)
```

--------------------------------

### Manual README marker placement

Source: https://shieldcn.dev/docs/cli

Example of manually placing markers in a markdown file.

```markdown
# My Project

<!-- shieldcn-start -->
<!-- shieldcn-end -->

Description goes here...
```

--------------------------------

### GitHub Issues Badge HTML Examples

Source: https://shieldcn.dev/docs/badges/github

Copy-paste examples for embedding issue count badges.

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/github/issues/vercel/next.js.svg?mode=dark"><img alt="badge" src="https://shieldcn.dev/github/issues/vercel/next.js.svg?mode=light"></picture>
```

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/github/open-issues/vercel/next.js.svg?variant=outline&amp;mode=dark"><img alt="open issues" src="https://shieldcn.dev/github/open-issues/vercel/next.js.svg?variant=outline&amp;mode=light"></picture>
```

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/github/closed-issues/vercel/next.js.svg?variant=secondary&amp;mode=dark"><img alt="closed issues" src="https://shieldcn.dev/github/closed-issues/vercel/next.js.svg?variant=secondary&amp;mode=light"></picture>
```

--------------------------------

### Use Self-Hosted Badges

Source: https://shieldcn.dev/docs/self-hosting

Example Markdown syntax for embedding badges from a local instance.

```markdown
![npm](http://localhost:3000/npm/v/react.svg)
![stars](http://localhost:3000/github/stars/facebook/react.svg)
```

--------------------------------

### Display Skill Installs Badge

Source: https://shieldcn.dev/docs/badges/skills

Use the HTML picture element to support automatic dark mode switching for the install count badge.

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/skills/installs/vercel-labs/agent-skills/vercel-react-best-practices.svg?mode=dark"><img alt="badge" src="https://shieldcn.dev/skills/installs/vercel-labs/agent-skills/vercel-react-best-practices.svg?mode=light"></picture>
```

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/skills/installs/vercel-labs/agent-skills/vercel-react-best-practices.svg?mode=dark"><img alt="skill installs" src="https://shieldcn.dev/skills/installs/vercel-labs/agent-skills/vercel-react-best-practices.svg?mode=light"></picture>
```

--------------------------------

### Badge group examples

Source: https://shieldcn.dev/docs/badges/group

Markdown examples of badge groups using different combinations of providers and variants.

```markdown
![group](https://shieldcn.dev/group/npm/react+github/stars/vercel/next.js.svg)
```

```markdown
![group](https://shieldcn.dev/group/npm/react+github/stars/vercel/next.js+github/license/vercel/next.js.svg?variant=branded)
```

```markdown
![group](https://shieldcn.dev/group/github/stars/vercel/next.js+github/forks/vercel/next.js+github/license/vercel/next.js.svg?variant=outline)
```

--------------------------------

### Copy-paste examples for repository badges

Source: https://shieldcn.dev/docs/badges/github

Pre-formatted HTML snippets for embedding contributor and watcher counts.

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/github/contributors/vercel/next.js.svg?mode=dark"><img alt="contributors" src="https://shieldcn.dev/github/contributors/vercel/next.js.svg?mode=light"></picture>
```

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/github/watchers/vercel/next.js.svg?variant=secondary&amp;mode=dark"><img alt="watchers" src="https://shieldcn.dev/github/watchers/vercel/next.js.svg?variant=secondary&amp;mode=light"></picture>
```

--------------------------------

### Copy-paste badge examples

Source: https://shieldcn.dev/docs/badges/homebrew

Ready-to-use HTML and Markdown snippets for specific Homebrew badge configurations.

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/homebrew/dm/node.svg?mode=dark"><img alt="homebrew downloads" src="https://shieldcn.dev/homebrew/dm/node.svg?mode=light"></picture>
```

```markdown
![homebrew cask downloads](https://shieldcn.dev/homebrew/cask-dm/firefox.svg?variant=branded)
```

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/homebrew/dy/node.svg?mode=dark"><img alt="homebrew yearly" src="https://shieldcn.dev/homebrew/dy/node.svg?mode=light"></picture>
```

--------------------------------

### Discord Online Members Copy-Paste Examples

Source: https://shieldcn.dev/docs/badges/discord

Examples for embedding the online members badge in Markdown or HTML.

```markdown
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/discord/online-members/reactiflux.svg?mode=dark"><img alt="discord online members" src="https://shieldcn.dev/discord/online-members/reactiflux.svg?mode=light"></picture>
```

```markdown
![discord online members](https://shieldcn.dev/discord/online-members/reactiflux.svg?variant=branded)
```

--------------------------------

### Glow background preset

Source: https://shieldcn.dev/docs/headers

Example of the glow background preset with a blue theme applied.

```markdown
![glow preset with a blue theme](https://shieldcn.dev/header/glow.svg?title=Lumen&subtitle=Illuminate+your+data&logo=react&theme=blue)
```

--------------------------------

### Discord Online Count Copy-Paste Example

Source: https://shieldcn.dev/docs/badges/discord

Example for embedding the online count badge in Markdown.

```markdown
![discord](https://shieldcn.dev/discord/1316199667142496307.svg?variant=branded)
```

--------------------------------

### GitLab License Badge

Source: https://shieldcn.dev/docs/badges/gitlab

Examples for displaying repository license information with default or outline styles.

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/gitlab/inkscape/inkscape/license.svg?mode=dark"><img alt="badge" src="https://shieldcn.dev/gitlab/inkscape/inkscape/license.svg?mode=light"></picture>
```

```text
/gitlab/{owner}/{repo}/license.svg
```

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/gitlab/inkscape/inkscape/license.svg?mode=dark"><img alt="license" src="https://shieldcn.dev/gitlab/inkscape/inkscape/license.svg?mode=light"></picture>
```

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/gitlab/inkscape/inkscape/license.svg?variant=outline&amp;mode=dark"><img alt="license" src="https://shieldcn.dev/gitlab/inkscape/inkscape/license.svg?variant=outline&amp;mode=light"></picture>
```

--------------------------------

### Run shieldcn CLI

Source: https://shieldcn.dev/docs/cli

Execute the CLI tool directly without installation.

```bash
npx shieldcn-cli
```

--------------------------------

### Skill Installs Branded Markdown

Source: https://shieldcn.dev/docs/badges/skills

Use the branded variant for a specific visual style.

```markdown
![skill installs](https://shieldcn.dev/skills/installs/vercel-labs/agent-skills/vercel-react-best-practices.svg?variant=branded)
```

--------------------------------

### Scoped package badge examples

Source: https://shieldcn.dev/docs/badges/npm

Syntax for displaying badges for scoped npm packages.

```markdown
![version](https://shieldcn.dev/npm/@types/react.svg)
```

```markdown
![version](https://shieldcn.dev/npm/v/@scope/package.svg)
```

--------------------------------

### Social size configuration

Source: https://shieldcn.dev/docs/headers

Example of using the social size parameter for a header image.

```markdown
![Header](https://shieldcn.dev/header/dots.svg?title=Acme&size=social)
```

--------------------------------

### skills.sh Badge Endpoints

Source: https://shieldcn.dev/docs/api-reference

Endpoints for skill installation statistics.

```APIDOC
## GET /skills/{owner}/{repo}/{skill}.svg
## GET /skills/rank/{owner}/{repo}/{skill}.svg

### Description
Retrieve installation counts or leaderboard ranks for specific skills.
```

--------------------------------

### Example badge output

Source: https://shieldcn.dev/docs/skill

The resulting HTML structure generated by the agent for a badge row.

```html
<p align="center">
<a href="https://www.npmjs.com/package/your-package"><img src="https://shieldcn.dev/npm/your-package.svg" alt="npm" /></a>
<a href="https://github.com/you/repo/stargazers"><img src="https://shieldcn.dev/github/stars/you/repo.svg" alt="stars" /></a>
<a href="https://github.com/you/repo"><img src="https://shieldcn.dev/github/license/you/repo.svg" alt="license" /></a>
</p>
```

--------------------------------

### GitLab Repository Copy-Paste Examples

Source: https://shieldcn.dev/docs/badges/gitlab

HTML snippets for contributor count and last activity badges.

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/gitlab/inkscape/inkscape/contributors.svg?mode=dark"><img alt="contributors" src="https://shieldcn.dev/gitlab/inkscape/inkscape/contributors.svg?mode=light"></picture>
```

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/gitlab/inkscape/inkscape/last-commit.svg?variant=secondary&amp;mode=dark"><img alt="last activity" src="https://shieldcn.dev/gitlab/inkscape/inkscape/last-commit.svg?variant=secondary&amp;mode=light"></picture>
```

--------------------------------

### Copy-paste example for sponsors badge

Source: https://shieldcn.dev/docs/badges/github

HTML snippet for embedding an active sponsor count.

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/github/sponsors/jal-co.svg?mode=dark"><img alt="sponsors" src="https://shieldcn.dev/github/sponsors/jal-co.svg?mode=light"></picture>
```

--------------------------------

### Initialize Tokscale CLI

Source: https://shieldcn.dev/docs/badges/tokscale

Commands to install the CLI, authenticate, and submit usage data to appear on the leaderboard.

```bash
bunx tokscale
```

```bash
bunx tokscale login
```

```bash
bunx tokscale submit
```

--------------------------------

### Grid background preset

Source: https://shieldcn.dev/docs/headers

Example of the grid background preset with left alignment.

```markdown
![grid preset, left aligned](https://shieldcn.dev/header/grid.svg?title=Blueprint&subtitle=Design+tokens+for+engineers&logo=figma&align=left)
```

--------------------------------

### Copy-paste examples for stars badge

Source: https://shieldcn.dev/docs/badges/github

HTML and Markdown snippets for displaying star counts.

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/github/stars/vercel/next.js.svg?mode=dark"><img alt="stars" src="https://shieldcn.dev/github/stars/vercel/next.js.svg?mode=light"></picture>
```

```markdown
![stars](https://shieldcn.dev/github/stars/vercel/next.js.svg?variant=branded&logo=github)
```

--------------------------------

### Start and Verify Engine

Source: https://shieldcn.dev/docs/self-hosting

Commands to initialize the container stack and verify the health and badge generation endpoints.

```bash
docker compose up -d

# Verify it's working
curl http://localhost:3000/api/health/
curl http://localhost:3000/badge/self--hosted-green.svg
```

--------------------------------

### GitLab Pipeline Copy-Paste Examples

Source: https://shieldcn.dev/docs/badges/gitlab

HTML snippets for default and secondary pipeline badge variants.

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/gitlab/inkscape/inkscape/pipeline.svg?mode=dark"><img alt="pipeline" src="https://shieldcn.dev/gitlab/inkscape/inkscape/pipeline.svg?mode=light"></picture>
```

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/gitlab/inkscape/inkscape/pipeline.svg?variant=secondary&amp;mode=dark"><img alt="pipeline" src="https://shieldcn.dev/gitlab/inkscape/inkscape/pipeline.svg?variant=secondary&amp;mode=light"></picture>
```

--------------------------------

### GET /pypi/license/{package}

Source: https://shieldcn.dev/docs/badges/pypi

Retrieves the license badge for a specified PyPI package.

```APIDOC
## GET /pypi/license/{package}

### Description
Returns the license badge for the specified package.

### Method
GET

### Endpoint
/pypi/license/{package}

### Parameters
#### Path Parameters
- **package** (string) - Required - The name of the PyPI package.
```

--------------------------------

### GET /chrome/users/{extensionId}

Source: https://shieldcn.dev/docs/badges/chrome

Retrieves a badge displaying the total user install count for a Chrome extension.

```APIDOC
## GET /chrome/users/{extensionId}

### Description
Returns an SVG badge showing the number of users who have installed the specified Chrome extension.

### Method
GET

### Endpoint
/chrome/users/{extensionId}

### Parameters
#### Path Parameters
- **extensionId** (string) - Required - The unique identifier of the extension found in the Chrome Web Store URL.

#### Query Parameters
- **variant** (string) - Optional - The visual style of the badge (e.g., 'branded').
```

--------------------------------

### Copy-Paste Release Badge Examples

Source: https://shieldcn.dev/docs/badges/github

HTML and Markdown snippets for default and branded release badges.

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/github/release/vercel/next.js.svg?mode=dark"><img alt="release" src="https://shieldcn.dev/github/release/vercel/next.js.svg?mode=light"></picture>
```

```markdown
![release](https://shieldcn.dev/github/release/vercel/next.js.svg?variant=branded)
```

--------------------------------

### Transparent background preset

Source: https://shieldcn.dev/docs/headers

Example of the transparent background preset which renders only the border and content.

```markdown
![transparent preset](https://shieldcn.dev/header/transparent.svg?title=Ghost&subtitle=Blends+into+the+README&logo=react)
```

--------------------------------

### Initialize README markers

Source: https://shieldcn.dev/docs/cli

Adds shieldcn-start and shieldcn-end markers to the README file.

```bash
npx shieldcn-cli init
```

--------------------------------

### Reverse Proxy Configuration

Source: https://shieldcn.dev/docs/self-hosting

Configuration examples for Nginx and Caddy to serve badges from a custom domain.

```nginx
server {
    listen 80;
    server_name badges.example.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

```caddy
badges.example.com {
    reverse_proxy localhost:3000
}
```

--------------------------------

### Embed npm download chart

Source: https://shieldcn.dev/docs/charts

Example of embedding an npm download chart for a specific package.

```markdown
![npm downloads](https://shieldcn.dev/chart/npm/zod.svg)
```

--------------------------------

### Copy-Paste Badge Examples

Source: https://shieldcn.dev/docs/badges/https-endpoint

Pre-configured HTML snippets for default and secondary badge variants.

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/https/cal-badge-icd0onfvrxx6.runkit.sh.svg?mode=dark"><img alt="https endpoint" src="https://shieldcn.dev/https/cal-badge-icd0onfvrxx6.runkit.sh.svg?mode=light"></picture>
```

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/https/cal-badge-icd0onfvrxx6.runkit.sh.svg?variant=secondary&amp;mode=dark"><img alt="https endpoint" src="https://shieldcn.dev/https/cal-badge-icd0onfvrxx6.runkit.sh.svg?variant=secondary&amp;mode=light"></picture>
```

--------------------------------

### GET /bundlephobia/min/{package}

Source: https://shieldcn.dev/docs/badges/bundlephobia

Retrieves a badge displaying the minified size of an npm package.

```APIDOC
## GET /bundlephobia/min/{package}

### Description
Returns an SVG badge showing the minified bundle size for the specified npm package.

### Method
GET

### Endpoint
/bundlephobia/min/{package}

### Parameters
#### Path Parameters
- **package** (string) - Required - The name of the npm package.
```

--------------------------------

### GET /pypi/{package}

Source: https://shieldcn.dev/docs/badges/pypi

Retrieves the latest version badge for a specified PyPI package.

```APIDOC
## GET /pypi/{package}

### Description
Returns the latest version badge for the specified package.

### Method
GET

### Endpoint
/pypi/{package}

### Parameters
#### Path Parameters
- **package** (string) - Required - The name of the PyPI package.
```

--------------------------------

### Basic npm badge examples

Source: https://shieldcn.dev/docs/badges/npm

Standard Markdown syntax for displaying various npm package badges.

```markdown
![version](https://shieldcn.dev/npm/react.svg)
```

```markdown
![downloads](https://shieldcn.dev/npm/dm/react.svg)
```

```markdown
![license](https://shieldcn.dev/npm/license/react.svg)
```

```markdown
![types](https://shieldcn.dev/npm/types/react.svg)
```

--------------------------------

### Core badge URL example

Source: https://shieldcn.dev/docs/registry

The standard URL format used for embedding badges in Markdown.

```text
https://shieldcn.dev/npm/react.svg
```

--------------------------------

### GitHub CI Status Copy-Paste Examples

Source: https://shieldcn.dev/docs/badges/github

Pre-configured HTML snippets for default and secondary CI badge styles.

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/github/ci/vercel/next.js.svg?mode=dark"><img alt="ci status" src="https://shieldcn.dev/github/ci/vercel/next.js.svg?mode=light"></picture>
```

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/github/ci/vercel/next.js.svg?variant=secondary&amp;mode=dark"><img alt="ci status" src="https://shieldcn.dev/github/ci/vercel/next.js.svg?variant=secondary&amp;mode=light"></picture>
```

--------------------------------

### GET /tokscale/cost/{username}

Source: https://shieldcn.dev/docs/badges/tokscale

Retrieves a badge showing the estimated total cost for a specific user.

```APIDOC
## GET /tokscale/cost/{username}

### Description
Returns an SVG badge displaying the estimated total cost for the specified GitHub username.

### Method
GET

### Endpoint
/tokscale/cost/{username}

### Parameters
#### Path Parameters
- **username** (string) - Required - The GitHub username of the user.
```

--------------------------------

### Preview Migration Changes

Source: https://shieldcn.dev/docs/cli

Run the migration tool in dry-run mode to see which shields.io URLs will be converted without modifying any files.

```bash
npx shieldcn-cli migrate --dry
```

--------------------------------

### GitHub Badge Markdown Examples

Source: https://shieldcn.dev/docs/badges/github

Common examples of embedding GitHub badges in Markdown using the shieldcn.dev service.

```markdown
![stars](https://shieldcn.dev/github/stars/vercel/next.js.svg)
```

```markdown
![release](https://shieldcn.dev/github/release/vercel/next.js.svg)
```

```markdown
![ci](https://shieldcn.dev/github/ci/vercel/next.js.svg)
```

```markdown
![license](https://shieldcn.dev/github/license/vercel/next.js.svg)
```

--------------------------------

### Copy-Paste Examples for Dynamic JSON Badges

Source: https://shieldcn.dev/docs/badges/dynamic-json

Ready-to-use HTML snippets for default and secondary badge variants.

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/badge/dynamic/json.svg?url=https%3A%2F%2Fapi.github.com%2Frepos%2Fvercel%2Fnext.js&amp;query=%24.stargazers_count&amp;mode=dark"><img alt="dynamic json" src="https://shieldcn.dev/badge/dynamic/json.svg?url=https%3A%2F%2Fapi.github.com%2Frepos%2Fvercel%2Fnext.js&amp;query=%24.stargazers_count&amp;mode=light"></picture>
```

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/badge/dynamic/json.svg?url=https%3A%2F%2Fapi.github.com%2Frepos%2Fvercel%2Fnext.js&amp;query=%24.stargazers_count&amp;variant=secondary&amp;mode=dark"><img alt="dynamic json" src="https://shieldcn.dev/badge/dynamic/json.svg?url=https%3A%2F%2Fapi.github.com%2Frepos%2Fvercel%2Fnext.js&amp;query=%24.stargazers_count&amp;variant=secondary&amp;mode=light"></picture>
```

--------------------------------

### Display skill install count badge

Source: https://shieldcn.dev/docs/badges/skills

Use this markdown snippet to display the all-time install count for a specific skill.

```markdown
![installs](https://shieldcn.dev/skills/installs/vercel-labs/agent-skills/vercel-react-best-practices.svg)
```

--------------------------------

### License badge implementation

Source: https://shieldcn.dev/docs/badges/npm

HTML and URL format for displaying the package license badge.

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/npm/license/react.svg?mode=dark"><img alt="badge" src="https://shieldcn.dev/npm/license/react.svg?mode=light"></picture>
```

```text
/npm/license/{package}.svg
```

--------------------------------

### Copy-Paste License Badge Examples

Source: https://shieldcn.dev/docs/badges/github

Pre-configured HTML snippets for default and ghost variant license badges.

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/github/license/vercel/next.js.svg?mode=dark"><img alt="license" src="https://shieldcn.dev/github/license/vercel/next.js.svg?mode=light"></picture>
```

```html
<picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/github/license/vercel/next.js.svg?variant=ghost&amp;mode=dark"><img alt="license" src="https://shieldcn.dev/github/license/vercel/next.js.svg?variant=ghost&amp;mode=light"></picture>
```

--------------------------------

### Create a clickable chart link

Source: https://shieldcn.dev/docs/charts

Wrap the chart image in a link to navigate to the source package page.

```markdown
[![npm downloads](https://shieldcn.dev/chart/npm/zod.svg)](https://www.npmjs.com/package/zod)
```

--------------------------------

### GET /nba

Source: https://shieldcn.dev/docs/badges/nba

Retrieves the default NBA championship badge.

```APIDOC
## GET /nba

### Description
Returns the default '2026 champs / Knicks' badge using the branded Knicks color.

### Method
GET

### Endpoint
/nba
```

--------------------------------

### GET /contributors

Source: https://shieldcn.dev/docs/contributors

Retrieves a visual representation of contributors for a specified repository.

```APIDOC
## GET /contributors

### Description
Generates a visual display of repository contributors based on GitHub data.

### Method
GET

### Parameters
#### Query Parameters
- **title** (string|false) - Optional - Title of the display, default: "Contributors"
- **limit** (number) - Optional - Number of contributors to show (1-100), default: 60
- **min** (number) - Optional - Minimum contribution threshold, default: 0
- **names** (boolean) - Optional - Show contributor names, default: false
- **bots** (boolean) - Optional - Include bots in the list, default: false
- **titleAlign** (string) - Optional - Alignment of the title (left, center, right), default: left
- **align** (string) - Optional - Alignment of avatars (left, center, right), default: center
- **size** (number) - Optional - Avatar size in pixels (24-140), default: 64
- **width** (number) - Optional - Total width in pixels (320-2000), default: 800
- **preset** (string) - Optional - Visual preset (surface, gradient, dots, grid, graph, glow, transparent), default: surface
- **theme** (string) - Optional - Color theme (zinc, slate, blue, green, rose, orange, violet, purple, cyan, emerald)
- **bg** (string) - Optional - Background hex color without # or 'transparent'
- **gradient** (string) - Optional - Comma-separated hex stops with optional trailing angle
- **pattern** (string) - Optional - Background pattern (dots, grid, graph, none)
- **glow** (string) - Optional - Glow hex color without #
- **image** (string) - Optional - Unsplash URL, image URL, or data URI
- **overlay** (number) - Optional - Overlay opacity (0-1), default: 0.45
- **tint** (string) - Optional - Tint hex color without #, default: 000000
- **radius** (number) - Optional - Border radius in pixels (0-80), default: 12
- **border** (boolean) - Optional - Show border, default: true
- **watermark** (boolean) - Optional - Show watermark, default: false
- **mode** (string) - Optional - Color mode (dark, light), default: dark
```

--------------------------------

### GET /tokscale/stats

Source: https://shieldcn.dev/docs/badges/tokscale

Retrieves a badge showing the global user count.

```APIDOC
## GET /tokscale/stats

### Description
Returns an SVG badge displaying the global user count on the Tokscale leaderboard.

### Method
GET

### Endpoint
/tokscale/stats
```

--------------------------------

### GET /header/surface.svg

Source: https://shieldcn.dev/docs/headers

Generates a header image based on the provided query parameters.

```APIDOC
## GET /header/surface.svg

### Description
Generates a dynamic header image. Parameters control the logo, colors, themes, and layout.

### Method
GET

### Endpoint
https://shieldcn.dev/header/surface.svg

### Parameters
#### Query Parameters
- **title** (string) - Optional - The main title text.
- **logo** (string) - Optional - Logo source: SimpleIcons slug, React Icons name, Lucide name, data URI, or remote URL.
- **logoColor** (string) - Optional - Hex color (without #) or 'brand' to use brand color.
- **theme** (string) - Optional - Color theme: zinc, slate, blue, green, rose, orange, violet, purple, cyan, or emerald.
- **bg** (string) - Optional - Solid background color or 'transparent'.
- **gradient** (string) - Optional - Comma-separated hex stops with optional trailing angle.
- **titleColor** (string) - Optional - Text color for the title.
- **subtitleColor** (string) - Optional - Text color for the subtitle.
- **glow** (string) - Optional - Spotlight color.
- **align** (string) - Optional - Alignment: 'left' or default (centered).
- **border** (boolean) - Optional - Set to 'false' to remove the hairline card border.
- **watermark** (boolean) - Optional - Set to 'true' to add a shieldcn.dev watermark.
```

--------------------------------

### GET /homebrew/{interval}/{formula}

Source: https://shieldcn.dev/docs/badges/homebrew

Retrieves download count badges for formulae based on monthly, quarterly, or yearly intervals.

```APIDOC
## GET /homebrew/{interval}/{formula}

### Description
Returns a download count badge for a formula using specified time intervals.

### Method
GET

### Endpoint
/homebrew/{interval}/{formula}

### Parameters
#### Path Parameters
- **interval** (string) - Required - The time interval: 'dm' (monthly), 'dq' (quarterly), or 'dy' (yearly).
- **formula** (string) - Required - The name of the Homebrew formula.
```

--------------------------------

### GET /views/user/{username}

Source: https://shieldcn.dev/docs/badges/views

Retrieves a view counter badge for a GitHub profile.

```APIDOC
## GET /views/user/{username}

### Description
Returns a view counter badge for a profile README.

### Method
GET

### Endpoint
/views/user/{username}

### Parameters
#### Path Parameters
- **username** (string) - Required - The GitHub username.
```

--------------------------------

### GET /stackexchange/reputation/{userId}

Source: https://shieldcn.dev/docs/badges/stackexchange

Retrieves a badge displaying the user reputation score.

```APIDOC
## GET /stackexchange/reputation/{userId}

### Description
Returns a badge showing the reputation score for a specified user ID.

### Method
GET

### Endpoint
/stackexchange/reputation/{userId}

### Parameters
#### Path Parameters
- **userId** (integer) - Required - The user ID to query.

#### Query Parameters
- **site** (string) - Optional - The Stack Exchange site identifier (defaults to 'stackoverflow').
- **variant** (string) - Optional - The visual variant of the badge (e.g., 'branded').
```

--------------------------------

### Add React Icons and Lucide icons

Source: https://shieldcn.dev/docs/customization/logos

Use the ri: prefix for React Icons or the lu: prefix for Lucide icons.

```markdown
![react icon](https://shieldcn.dev/badge/icon-react.svg?logo=ri:FaReact)
![lucide](https://shieldcn.dev/badge/check-passing.svg?logo=lu:Check)
```

--------------------------------

### GET /rubygems/license/{gem}

Source: https://shieldcn.dev/docs/badges/rubygems

Retrieves the license badge for a specified Ruby gem.

```APIDOC
## GET /rubygems/license/{gem}

### Description
Returns a badge displaying the license type of the specified Ruby gem.

### Method
GET

### Endpoint
/rubygems/license/{gem}

### Parameters
#### Path Parameters
- **gem** (string) - Required - The name of the Ruby gem.
```

--------------------------------

### GET /nba/{team}

Source: https://shieldcn.dev/docs/badges/nba

Retrieves a fan badge for a specific NBA team.

```APIDOC
## GET /nba/{team}

### Description
Generates a fan badge with the specified NBA team name, logo, and team color. The {team} parameter accepts slugs, abbreviations, city names, or nicknames.

### Method
GET

### Endpoint
/nba/{team}

### Parameters
#### Path Parameters
- **team** (string) - Required - Team slug, abbreviation, city, or nickname.

#### Query Parameters
- **variant** (string) - Optional - Badge style variant (e.g., branded, outline).
- **size** (string) - Optional - Badge size (e.g., sm).
- **mode** (string) - Optional - Color mode (e.g., light, dark).
- **label** (string) - Optional - Custom label text for the badge.
```
Tokens:
Raw