Skip to main content

Quirky little python package for generating badges for your cli apps

Project description

Quirky little python library for generating badges for your cli apps.

GitHub file size in bytes PyPI version

Inspired & Python Port of cli-badges - nombrekeff

Getting Started


As usual, you need to install from PIP:

$ pip install cli-badges


This is a simple example, using badges to display test results:

from cli_badges import badge

failedBadge = badge("failed",'2',messagebg='red')
skippedBadge = badge('skipped', '1', messagebg='yellow',messagecolor='black')
successBadge = badge('success','8', messagebg='green',messagecolor='black')

print(failedBadge, successBadge, skippedBadge)

The above would output something similar to the terminal:


You could also create a donate badge with a link (if supported):

from cli_badges import badge

donateBadge = badge('❤️ donate', 'ko-fi', messagelink='');


You can also only show the label:

from cli_badges import badge

onlyLabel = badge('❤️ donate', '')


Example output is a mock, console output will vary slightly from terminal to terminal.

Badge Structure

A badge is conformed of a label and a message <label>:<message>. Each segment can be customized, by changing bg color, text color and style.

Available Options

Option Value Default
label String ''
message String ''
messagebg Color blue
labelbg Color dark_gray
messagecolor Color white
labelcolor Color white
labelwidth Integer label length + 2
messagewidth Integer label length + 2
labelstyles Array of Styles []
messagestyles Array of Styles []
labellink URL ''
messagelink URL ''
swap boolean False
theme Theme None


cli-badges uses colored internally for managing colors, you can check the list of available colors there.


cli-badges uses colored internally for managing styles, you can check the list of available styles there.

Available Styles

  • bold
  • dim
  • underlined
  • reverse
  • hidden


You can output badges with a link attached to it, that can be clicked in some terminals. labellink option will add the link to the label, while messagelink option will add the link to the message.

⚠︎ cli-badges will only output link if its supported by your terminal.

See this for information on supported terminals

badge('with', 'link',  labellink='', messagelink='');




Themes are a way to store badge configuration for repeated use. All the options (except for the theme option, obviously) that are needed by the badge can be stored by making a theme.
The library comes with a set of inbuilt themes, but you can also define your own

Inbuilt Themes

  • red : Red Message Background
  • green : Green Message Background
  • yellow : Black Colored Message on Yellow Background
  • cyan : Black Colored Message on Cyan Background
  • magenta : Black Colored Message on Magenta Background
  • success : 'Success' Message on Green Background
  • failed : 'Failed' Message on Red Background

Using Themes

THEME stores all the available themes, and has to be passed to the badge() functions theme argument. Arguments present in the theme will override the passed arguments. Missing arguments will have default values

from cli_badges import badge,THEME
red_badge = badge('Red','Badge',

Adding New Themes

  1. Directly in Code
    To add a Theme directly, add_theme(name,config) function is used. name is the name of the theme, config is a dict containing the required options

    from cli_badges import badge,add_theme, THEME
        'label': '❤️ donate'
    donate_badge = badge(message='kofi',theme=THEME.donate)
  2. From a JSON File
    You can store the Theme configurations in a json file and load them using load_themes(file) function where file is the Theme json file

    # themes.json
        "redblue": {
            "messagebg": "blue",
            "messagestyles": ["bold"]
    from cli_badges import badge, load_themes, THEME
    redblue_badge = badge('RED','BLUE',theme=THEME.redblue)

Swapping Styles

The swap option is used to apply the message styles to the label and vice-versa

from cli_badges import badge
normal_badge = badge('RED','BLUE',labelbg='red', messagebg='blue')
swapped_badge = badge('RED','BLUE',labelbg='red', messagebg='blue',swap=True)


Other Libraries?

cli-badges is also available in other languages:

Contributions are very welcomed 🥰

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cli_badges-0.0.4.tar.gz (5.5 kB view hashes)

Uploaded Source

Built Distribution

cli_badges-0.0.4-py3-none-any.whl (5.9 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page