capes

demo of capes running in terminal

a tiny cli tool to view minecraft player heads and capes directly in your terminal.
it fetches data from capes.me and renders images inline using kitty icat or chafa (configurable, more to be added soon).

features

show a player's minecraft head and equipped capes
fetches cape metadata and textures from capes.me
caching system to avoid unnecessary api calls
lightweight image layout with head, username, and capes
renders inline in Kitty terminal (kitty +kitten icat) or using chafa for portable terminals
fully configurable display and layout options

install

clone the repo and build with go:

git clone https://github.com/dorochadev/capes
cd capes
go build -o capes

add to path

move the binary into a folder already in your path, for example:

sudo mv capes /usr/local/bin/

or add the project folder to your path (e.g. in ~/.bashrc or ~/.zshrc):

export PATH=$PATH:$(pwd)

reload your shell:

source ~/.bashrc   # or ~/.zshrc

now you can run:

capes notch

usage

capes notch

outputs the player head, username, and any visible capes in your terminal.

default username

if you set a default_username in the config file, you can run the command without arguments:

capes

configuration

on first run, capes automatically creates a configuration file at ~/.config/capes/config.json (or $XDG_CONFIG_HOME/capes/config.json). you can edit this file to customize the appearance and behavior.

configuration options

default user

{
  "default_username": "notch"
}

default_username: username to use when no argument is provided

display settings

{
  "display": {
    "head_size": 8,
    "layout_height": 48,
    "upscale_factor": 4,
    "show_head_only": true,
    "image_backend": "kitty"
  }
}

head_size: size in terminal cells when displaying head-only (default: 8)
layout_height: size in terminal cells for full layout with capes (default: 48)
upscale_factor: image upscaling multiplier for better quality (default: 4)
show_head_only: whether to show head when no capes are found (default: true)
image_backend: "kitty" (default) or "chafa" for portable terminal rendering

layout settings

{
  "layout": {
    "spacing": 5,
    "cape_spacing": 2,
    "capes_per_row": 0,
    "username_row_height": 14,
    "cape_start_offset": 2,
    "available_cape_width": 200
  }
}

spacing: pixels between major elements (head, username area, cape area) (default: 5)
cape_spacing: pixels between individual capes (default: 2)
capes_per_row: maximum capes per row, 0 for auto-calculation (default: 0)
username_row_height: vertical space allocated for username text (default: 14)
cape_start_offset: additional vertical offset for cape positioning (default: 2)
available_cape_width: available width for cape area when auto-calculating capes per row (default: 200)

cache settings

{
  "cache": {
    "cache_ttl_hours": 24,
    "cache_dir": "cache"
  }
}

cache_ttl_hours: how long to cache downloaded images in hours (default: 24)
cache_dir: directory for cached files relative to current directory (default: "cache")

network settings

{
  "network": {
    "timeout_seconds": 15,
    "user_agent": "Mozilla/5.0 (capes-cli)"
  }
}

timeout_seconds: http request timeout in seconds (default: 15)
user_agent: user agent string for http requests (default: "Mozilla/5.0 (capes-cli)")

example configuration

here's a sample configuration for a more compact layout:

{
  "default_username": "notch",
  "display": {
    "head_size": 6,
    "layout_height": 32,
    "upscale_factor": 3,
    "show_head_only": true,
    "image_backend": "chafa"
  },
  "layout": {
    "spacing": 3,
    "cape_spacing": 1,
    "capes_per_row": 3,
    "username_row_height": 12,
    "cape_start_offset": 1,
    "available_cape_width": 150
  },
  "cache": {
    "cache_ttl_hours": 48,
    "cache_dir": "cache"
  },
  "network": {
    "timeout_seconds": 10,
    "user_agent": "Mozilla/5.0 (capes-cli)"
  }
}

configuration location

the config file is created following the xdg base directory specification:

linux/macos: ~/.config/capes/config.json
with xdg_config_home: $XDG_CONFIG_HOME/capes/config.json

requirements

go (for building)
kitty terminal recommended (for best quality)
chafa optional (portable fallback for other terminals)
imagemagick (used to upscale images before rendering)

notes

works best in kitty with image rendering enabled
caches heads and capes in configurable directory for configurable time
usernames or uuids supported
hidden or removed capes are ignored
configuration is automatically created on first run

license

mit

Capes

Install / Use

README