termfetch

A neofetch-style profile card for your GitHub README — your photo as coloured terminal art on the left, live GitHub stats on the right, rendered to a single self-contained SVG.

Why termfetch?

• Your design, not a preset badge. Render your photo or logo as ASCII, blocks, or high-resolution half-block art.
• No image service at view time. The result is a static SVG committed to a repository you control.
• Live GitHub data at generation time. Repositories, stars, followers, languages, and account age are templatable.
• Live without being fragile. A scheduled GitHub Action refreshes the card without spending API quota on README views.
• Portable and customizable. Six themes, custom colours, flexible sections, and no JavaScript runtime.

Quickstart

Install the published CLI with pipx (recommended for command-line tools):

pipx install termfetch

Or install it into your current Python environment:

python -m pip install termfetch

Create a starter configuration and render your first card:

termfetch init --user YOUR_GITHUB_USERNAME --image path/to/photo.jpg
termfetch

This creates termfetch.json and termfetch.svg. Add the generated card to your profile README:

![My GitHub profile card](termfetch.svg)

Already have a configuration or want different filenames?

termfetch --config config.json --out card.svg

--no-fetch skips the GitHub API entirely when you only want to iterate on the art. Run termfetch --help and termfetch init --help for every option.

Theme gallery

GitHub Dark	Dracula
Nord	GitHub Light

Configuration

termfetch init creates a generic starter config. Everything remains editable in one JSON file:

{
  "github": "saivarun1410",
  "image": "assets/me.jpg",
  "imageCrop": [630, 0, 780, 780],
  "imageCols": 52,
  "charset": "blocks",
  "theme": "github-dark",
  "panelAlign": "middle",
  "sections": [
    {
      "title": "{{username}}@github",
      "fields": [
        ["Name", "{{name}}"],
        ["Member for", "{{uptime}}"],
        ["Editor", "Neovim"]
      ]
    }
  ]
}

Image

Choosing a charset.

• halfblocks — sharpest. Every cell is ▀, with the glyph painting the upper pixel and a background rect the lower one, so vertical resolution is doubled for the same card width. Use this if the art looks blocky; the cost is file size, since a photograph has few neighbouring cells that can merge.
• blocks ( ░▒▓█) — keeps a visible terminal texture while letting colour carry the image. Much smaller output, noticeably coarser.
• ascii ( .:-=+*#%@) — looks the most like real neofetch output, but it maps brightness to character density, so a backlit photo where the subject is darker than the background comes out as a hole. Good for logos and high-key images, risky for portraits.
• solid — every cell █. Clear, but reads as pixel art rather than terminal art.

File size. A halfblocks card is a few hundred KB; blocks is a few tens. Raising colorStep helps only slightly on photographs — the cost is the per-cell geometry, not repeated colours — so reducing imageCols is the effective lever if size matters.

Cropping. The card looks best framed on a face. Find the pixel coordinates however you like — this snippet prints a labelled grid over your image:

from PIL import Image, ImageDraw
im = Image.open("assets/me.jpg"); d = ImageDraw.Draw(im)
for x in range(0, im.width, 200):  d.line([(x,0),(x,im.height)], fill="cyan", width=4); d.text((x+6,6), str(x), fill="cyan")
for y in range(0, im.height, 200): d.line([(0,y),(im.width,y)], fill="magenta", width=4); d.text((6,y+6), str(y), fill="magenta")
im.show()

Layout and theme

Data

Available template variables: {{username}}, {{name}}, {{bio}}, {{location}}, {{company}}, {{blog}}, {{repos}}, {{stars}}, {{forks}}, {{followers}}, {{following}}, {{languages}}, {{created}}, {{uptime}}, {{today}}.

A field is dropped when its value resolves to nothing, or when it still references a variable there was no data for — so an unset bio leaves no dangling label, and --no-fetch renders a clean card rather than one covered in literal {{bio}} text. Fields can also be plain strings for a full-width line with no key column.

Keeping it current

Copy examples/refresh-card.yml into .github/workflows/refresh-card.yml in your profile repository, then adjust the config and output paths if needed. The complete workflow is reproduced below:

name: refresh-card
on:
  schedule: [{ cron: "0 5 * * *" }]
  workflow_dispatch:

permissions:
  contents: write

jobs:
  refresh:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-python@v7
        with: { python-version: "3.12" }
      - run: python -m pip install termfetch
      - run: termfetch --config termfetch.json --out termfetch.svg
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add termfetch.svg
          git diff --cached --quiet || { git commit -m "Refresh profile card"; git push; }

GITHUB_TOKEN is optional but raises the API rate limit from 60 requests/hour per IP to 5,000, which matters if you use languageMode: "bytes".

If the default branch requires pull requests, either configure the workflow to open a PR or write the generated card to a dedicated automation branch. Do not place a long-lived personal access token in the repository to bypass protection rules.

How it works

1. Sample. The image is cropped, resized to the character grid, and each cell becomes a character picked from a luminance ramp plus the cell's average colour.
2. Quantise. Colours are snapped to a coarser grid so runs of neighbouring cells share a value and collapse into one SVG span. This is most of the difference between a 60 KB file and a 300 KB one.
3. Position every glyph explicitly. SVGs embedded in a README render as images, so webfonts never load and the viewer's monospace fallback is whatever their OS provides. Relying on the font's own advance width would let columns drift apart on some machines, so each span carries an absolute x.

Limitations

• Character cells are assumed to be 0.6× as wide as they are tall. That holds for the fonts in the stack; a wildly different fallback would shear the art slightly.
• Colour is per character cell, so effective resolution is imageCols × about 0.6 × imageCols. Portraits work; fine detail and text in the source image do not.
• Stats come from the public REST API, so private repositories and private contributions are not counted.

Development

git clone https://github.com/saivarun1410/termfetch.git
cd termfetch
python -m pip install -e '.[dev]'
python -m pytest -q

See CONTRIBUTING.md before opening a pull request and CHANGELOG.md for release history.

Licence

MIT — see LICENSE. The example photograph is not covered by it; replace it with your own.