Terminal Widgets is a versatile CLI program designed to enhance your terminal experience by providing various widgets and customizable features. Below is a list of features offered by Terminal Widgets:

Features:

• System Information Widgets:

  • Displays system-related information such as battery status, weather, shell, storage details, hostname, date, RAM usage and many more.

• Customizable build-in Widgets:

  • Users can customize widgets according to their preferences, including text, color, icon, index and state.

• Addons Widgets:

  • Supports addon widgets with customizable text, color, script execution, icon display, and position settings.

• Dynamic Content Configuration:

  • Offers a dynamic way to set content inside text, script, or program files without explicitly defining color or icon keys.

• Configuration Options:

  • Provides a configuration file (~/.twidgets.json) for users to modify settings like custom color codes, addon widgets, and built-in widget configurations.

• Orientation Support:

  • Enables users to customize widget layout orientation, allowing display in either horizontal (row) or vertical (column) configurations for improved flexibility across different terminal setups.

• Custom Logo Support:

  • Provides the option to add a personalized logo through the configuration file (~/.twidgets.json).

• Easy Installation:

  • Available for installation via pip or as a local install for convenient setup.

• Color Formatting Support:

  • Supports color formatting using both named colors (e.g., [red]) and hexadecimal color codes.

• Icon Integration:

  • Allows integration of icons into text content using Unicode characters, enhancing visual representation within widgets.

• Supports Command Line Arguments

  • Terminal-Widgets offers support for command line arguments, providing users with flexibility in configuring and managing the program directly from the terminal.
  • Refer to the Argument Options for more detailed information.

Screenshots

Windows

Linux

macOS

Android

Supported platforms

• Linux
• Windows
• Darwin (macOS)
• Android (Termux)
• WSL (Windows Subsystem for Linux)

Getting Started

To start using Terminal Widgets, follow these steps:

1. Install the program via pip or perform a local install.
2. Ensure you have Nerd Font installed for optimal display.
3. Customize your widgets and addons using the configuration file (~/.twidgets.json).
4. Refer to the Configuration for more detailed information on configuration options and usage.

Prerequisites

Before using Terminal Widgets, please ensure that you have the following prerequisites installed:

1. Python 3.x: Terminal Widgets is written in Python and requires Python 3.x to be installed on your system.

2. Nerd Font: Terminal Widgets requires Nerd Font for display glyphs. If not installed, download one from here.

3. For Android users using Termux:

   • Termux: Terminal Widgets can be used on Android devices via Termux. Ensure that you have Termux installed on your Android device from the Google Play Store or F-Droid.

   • Termux-API: Terminal Widgets requires the Termux-API app for certain functionalities. Install the Termux-API app from the Google Play Store or F-Droid.

   • termux-api: Terminal Widgets requires the termux-api package for certain functionalities. Install termux-api by running the following command in your Termux terminal:

     pkg install termux-api
     

Installation

You can install Terminal Widgets using pip, or you can clone the repository and install it locally.

Install via pip

To install Terminal Widgets via pip, simply run the following command:

pip install terminal-widgets

or

pip3 install terminal-widgets

This will download and install the latest version of Terminal Widgets from the Python Package Index (PyPI) along with its dependencies.

Manual Installation

To install Terminal Widgets locally, follow these steps:

1. Clone this repository to your local machine. git clone https://github.com/imegeek/terminal-widgets
2. Navigate to the cloned directory. cd terminal-widgets
3. Install the package using pip: pip install . or pip3 install .

This will install Terminal Widgets along with its dependencies from the local source files.

Usage

Simply run the twidgets in your terminal to get an overview of your system status. try these command if not working:

python -m twidgets

or

python3 -m twidgets

<a name="argument"></a>

Argument Options:

Terminal-Widgets supports the following command line options for customization and control:

• -h, --help Show this help message and exit.
• --configs Display the configuration file.
• --widgets List built-in widgets and their values.
• --stdout Disable colors and ASCII graphics, displaying only plain text.
• --json Output widget data as a JSON object.
• --no-badge Display widgets without badge styling.
• --color-bars Enable color bars in terminal widgets.
• --text {detailed, compact} Set text mode for terminal widgets: - 'detailed' includes extended information - 'compact' shows concise info (default: compact)
• --color [normal, vivid, random, custom] Select color mode for terminal widgets (default: normal).
• --logo [pacman, linux, windows, macos, android] Choose a logo to display before widgets (default: auto, based on system).
• --show [logo, widgets] Specify what to display: 'logo' or 'widgets'.
• --align [left, center] Set alignment mode for terminal widgets (default: center).
• --direction [row, column] Choose layout direction for widgets (default: row).
• --weather location Set the location for the weather widget.
• --weather-api API_KEY Provide OpenWeather API key for weather data.
• --bypass-system-api Bypass system API requirement checks.
• -c, --config file Specify a JSON configuration file to load.
• --column length Set the number of widgets per row.
• --column-gap length Set gap between widgets in each column.
• --row-gap length Set gap between widgets in each row.
• --margin length Set whitespace lines before and after execution.

These options allow users to customize the behavior and appearance of Terminal-Widgets according to their preferences.

<a name="configuration"></a>

Configuration

Terminal Widgets supports configuration options, allowing users to customize their widgets or add new ones.

To configure Terminal Widgets:

1. Open the configuration file located at ~/.twidgets.json.
2. Modify the following key-value pairs according to your preferences:

• colors: Define custom color codes for widgets and addons. This option requires all color names (red, cyan, etc.) to be specified, to show custom colors pass --color custom argument to the program.

• logo: Customize the logo displayed before the widgets. You can define an ASCII art logo by entering it as an array of strings under the "logo" key. This logo will appear in the terminal before other widgets, providing a personalized visual touch.

• weather_api: Provide your OpenWeatherMap API key for weather data.

  • API_KEY: Provide your OpenWeatherMap API key here (e.g., "weather_api": "xxxxxxxxxxxxxxxx").

• addons: Customize addon widgets. Use properties like text, color, script, exec, icon, and index.
  • text: The text content to display for the addon.
  • color: The color code for the addon text or icon.
  • script: The Python script file or code to execute for dynamic text content.
  • exec: The terminal command to execute for dynamic text content.
  • icon: The UTF-8 code of the icon or glyph to display for the addon.
  • index: The position of the addon in the widget layout.
• widgets: Configure built-in widgets like username, hostname, platform, shell, package, etc. Use properties like text, color, icon, index, and state.
  • text: The text content to display for the widget.
  • color: The color code for the widget icon.
  • icon: The UTF-8 code of the icon or glyph to display for the widget.
  • index: The position of the widget in the widget layout.
  • state: Use "disabled" value to hide specific widget.

3. Dynamic Method for Defining widget-addon without Specifying 'color' or 'icon'.

• Add Text:

  • Simply input the desired text.

• Add Color:

  • "[color_name or hex_code]" marks the beginning of the color for the content.
  • "[/]" signifies the end of color formatting.

• Add Icon:

  • Incorporate icons into text content using Unicode characters. For instance, utilize "\uf255" to depict a custom Unicode character as an icon within the text.

• Refer to Example 11 for further clarification.

4. Save the changes and restart Terminal Widgets to apply the new configuration.

Configuration Examples

• Example 1:
  • This example defines custom colors code for terminal-widgets.

{
    "colors": {
        "red": "#FF0000",
        "cyan": "#00FFFF",
        "purple": "#a06efc",
        "green": "#9ACB73",
        "yellow": "#f8d255",
        "sky": "#6AA1DA"
    }
}

• Example 2:
  • This example customize the logo in the Terminal Widgets.

{
  "logo": [
    "        ,.=:!!t3Z3z.,                 ",
    "       :tt:::tt333EE3                 ",
    "       Et:::ztt33EEEL @Ee.,      ..,  ",
    "      ;tt:::tt333EE7 ;EEEEEEttttt33#  ",
    "     :Et:::zt333EEQ. $EEEEEttttt33QL  ",
    "     it::::tt333EEF @EEEEEEttttt33F   ",
    "    ;3=*^```\"*4EEV :EEEEEEttttt33@.   ",
    "    ,.=::::!t=., ` @EEEEEEtttz33QF    ",
    "   ;::::::::zt33)   \"4EEEtttji3P*     ",
    "  :t::::::::tt33.:Z3z..  `` ,..g.     ",
    "  i::::::::zt33F AEEEtttt::::ztF      ",
    " ;:::::::::t33V ;EEEttttt::::t3       ",
    " E::::::::zt33L @EEEtttt::::z3F       ",
    "{3=*^```\"*4E3) ;EEEtttt:::::tZ`       ",
    "             ` :EEEEtttt::::z7        ",
    "                 \"VEzjt:;;z>*`        "
  ]
}

• Example 3:
  • Configures the build-in widget username to change set custom color of icon.

{
    "widgets": {
        "username": {
            "color": "#d0ff1f"
        }
    }
}

• Example 4:
  • Configures the build-in widget hostname to display the text "macbook pro" at index 2 in the layout.

{
    "widgets": {
        "hostname": {
            "text": "macbook pro",
            "index": 2
        }
    }
}

• Example 5:
  • Configures the build-in widget platform to display the text "macos" with the custom icon.

{
    "widgets": {
        "platform": {
          "text": "macos",
          "icon": "\uf179"
        }
    }
}

• Example 6:
  • Configures the build-in widget shell to display the text "zsh".

{
    "widgets": {
          "shell": {
            "text": "zsh"
        }
    }
}

• Example 7:
  • Disables the build-in widget storage, preventing it from being displayed.

{
    "widgets": {
        "storage": {
            "state": "disabled"
        }
    }
}

• Example 8:
  • Adds a welcome message addon with custom text, color, and position in the layout.

{
    "addons": {
        "welcome": {
            "text": "Welcome to Terminal Widgets",
            "color": "#afdaaf",
            "index": 2
        }
    }
}

• Example 9:
  • Configures the cputemp addon to execute a Python script that prints a random temperature between 30°C and 60°C, with custom color and icon.

{
    "addons": {
      "cputemp": {
          "script": "import random\nprint(random.randint(30, 60), '\u00B0C')",
          "color": "#ff8522",
          "icon": "\udb84\udcc3"
      }
    }
}

• Example 10:
  • Configures the process addon to execute a Python script located at "/path/to/the/file/script.py".

{
    "addons": {
        "process": {
            "script": "/path/to/the/file/script.py"
        }
    }
}

• Example 11:
  • Configures the pwd addon to execute the "pwd" command in the terminal, displaying the current directory path with custom color and icon.

{
    "addons": {
        "pwd": {
          "exec": "pwd",
          "color": "#ffa0f4",
          "icon": "\uf07b"
        }
    }
}

• Example 12:
  • Configures the hi addon to display custom formatted text with colors.
    • text: Sets the text content to "[#ff0000]\uf255[/] [#eeff00]Hi, there[/]", where:
      • "[#ff0000]" specifies the start of red color for the text.
      • "\uf255" represents a custom Unicode character.
      • "[#eeff00]" specifies the start of yellow-green color for the text "Hi, there".
      • "[/]" specifies the end of the color formatting.
      • "Hi, there" is the content to be displayed in yellow-green color and icon displayed in red color.

{
    "addons": {
        "hi": {
          "text": "[#ff0000]\uf255[/] [#eeff00]Hi, there[/]"
        }
    }
}

• Example 13:
  • Configures the color addon to display custom color palette widget.
    • Uses a Python script to generate colored blocks representing each color in the palette.
    • Each color block is enclosed in color formatting tags, providing a visual representation of the color.
    • The color key specifies the color of the palette widget.
    • The icon key sets an icon for the palette widget.

{
  "addons": {
    "color": {
        "script": "print(' '.join([f'[{color}]\ueabc[/]' for color in ['black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white']]))",
        "color": "#6aafff",
        "icon": "\ue22b"
    }
  }
}

Contributing

Contributions are welcome! If you have any suggestions, bug reports, or feature requests, please open an issue or submit a pull request on GitHub.

License

This project is licensed under the MIT License - see the LICENSE file for details.