cli-icons

Render brand icons (GitHub, GitLab, Discord, npm, Slack, VS Code, X) directly in your terminal — not ASCII art, real SVG → PNG rasterized icons.

Supports four rendering protocols with automatic fallback:

| Priority | Protocol | Terminals | |----------|----------|-----------| | 1 | Sixel | iTerm2, WezTerm, mintty, mlterm, foot, xterm+sixel | | 2 | Kitty graphics | Kitty, WezTerm, Konsole 22.04+ | | 3 | iTerm2 inline image | iTerm2, WezTerm (and compatibles) | | 4 | ANSI block chars | Any terminal with 24-bit color (universal fallback) |

Install

npm install cli-icons
# or locally from the .tgz:
npm install ./cli-icons-1.0.0.tgz

Library API

Named imports (recommended)

import { GitHub, Discord, NPM, VSCode, GitLab, X, Slack } from 'cli-icons';

GitHub();                              // default size 'sm' (24px), auto-detected protocol
GitHub({ size: 'md' });                // 32px
GitHub({ size: 48 });                  // custom pixel size
GitHub({ color: '#FF0000' });          // custom color
GitHub({ protocol: 'ansi' });          // force ANSI block fallback
GitHub({ background: '000000' });      // black background (ANSI only)
GitHub({ noNewline: true });           // suppress trailing newline

Dynamic access

import { icons, renderById, listIcons, getIcon } from 'cli-icons';

icons.github();                        // render via namespace
renderById('discord', { size: 'lg' }); // render by id string

for (const icon of listIcons()) {
  console.log(icon.id, icon.label, icon.color);
}

Get the rendered string instead of writing to stdout

const result = GitHub({ size: 'sm', returnString: true });
// result.output     → string (ANSI/Sixel/iTerm/Kitty bytes)
// result.protocol   → 'sixel' | 'kitty' | 'iterm' | 'ansi'
// result.width      → pixels
// result.height     → pixels

CLI binary

# Install globally (or use npx)
npx cli-icons github

# Available commands
cli-icons --help
cli-icons --list
cli-icons github
cli-icons discord --size=md --color=5865F2
cli-icons npm --size=lg
cli-icons vscode --protocol=ansi --background=1E1E1E
cli-icons --list --json

CLI options

| Flag | Description | |------|-------------| | <icon-id> | Icon to render (github, gitlab, x, discord, slack, npm, vscode) | | --size=<s> | xs (16px), sm (24px, default), md (32px), lg (48px), xl (64px), or a pixel number | | --color=<hex> | Override icon color (FF0000 or #FF0000) | | --background=<hex> | Background color (ANSI mode only). Default: transparent | | --protocol=<p> | Force: sixel | kitty | iterm | ansi. Default: auto-detect | | --list | List all available icons | | --json | Output as JSON (with --list) | | -h, --help | Show help |

How rendering works

1. SVG source — Each icon is stored as an inline SVG path (24×24 viewBox).
2. Rasterization — @resvg/resvg-js renders the SVG to a PNG buffer at the requested pixel size. The PNG is then parsed via pngjs to obtain raw RGBA pixel data.
3. Protocol encoding:
   • Sixel: pure-JS encoder that quantizes colors and emits band-by-band sixel sequences with RLE compression.
   • Kitty: PNG bytes are base64-chunked and wrapped in _G APC sequences.
   • iTerm2: PNG is base64-encoded in an OSC 1337 File= sequence.
   • ANSI: 2 vertical pixels per terminal cell using ▀ ▄ █ ' ' half-block characters with 24-bit truecolor SGR escapes.
4. Output — The encoded string is written to process.stdout.

Available icons

| ID | Label | Default color | |----|-------|---------------| | github | GitHub | #181717 | | gitlab | GitLab | #FC6D26 | | x | X (formerly Twitter) | #000000 | | discord | Discord | #5865F2 | | slack | Slack | #4A154B | | npm | npm | #CB3837 | | vscode | Visual Studio Code | #007ACC |

Adding your own icons

The icon registry lives in src/icons.ts. Each entry is:

{
  id: 'mybrand',
  name: 'MyBrand',
  label: 'My Brand',
  color: 'FF6600',
  svg: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24" fill="currentColor"><path d="..."/></svg>'
}

License

MIT