capes

---

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