{"id":13740152,"url":"https://github.com/imegeek/terminal-widgets","last_synced_at":"2025-05-08T19:35:43.964Z","repository":{"id":182757991,"uuid":"385307598","full_name":"imegeek/terminal-widgets","owner":"imegeek","description":"A fully functional program for Terminal to show information about system, display, shell, package and many more.","archived":false,"fork":false,"pushed_at":"2024-02-20T17:04:38.000Z","size":60,"stargazers_count":20,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-04-25T23:02:59.162Z","etag":null,"topics":["colorful","colorful-interface","performance","terminal"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/imegeek.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-07-12T16:10:58.000Z","updated_at":"2024-04-24T14:20:33.000Z","dependencies_parsed_at":"2024-02-03T06:31:49.167Z","dependency_job_id":"40d23280-0962-440f-bb8e-512e2bfbc23f","html_url":"https://github.com/imegeek/terminal-widgets","commit_stats":null,"previous_names":["imegeek/termux-dotfiles","imegeek/terminal-widgets"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imegeek%2Fterminal-widgets","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imegeek%2Fterminal-widgets/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imegeek%2Fterminal-widgets/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imegeek%2Fterminal-widgets/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/imegeek","download_url":"https://codeload.github.com/imegeek/terminal-widgets/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253135673,"owners_count":21859680,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["colorful","colorful-interface","performance","terminal"],"created_at":"2024-08-03T04:00:43.491Z","updated_at":"2025-05-08T19:35:43.908Z","avatar_url":"https://github.com/imegeek.png","language":"Python","funding_links":[],"categories":["Operation System"],"sub_categories":["Cross Platform"],"readme":"\u003cdiv align=\"center\"\u003e\r\n\u003ckbd\u003e\r\n  \u003cimg src=\"https://github.com/user-attachments/assets/d0094956-31b6-4969-b64a-ae51fd4e36bc\" alt=\"Preview\" /\u003e\r\n\u003c/kbd\u003e\r\n\u003c/div\u003e\u003cbr\u003e\r\n\r\nTerminal 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:\r\n\r\n\u003cdiv align=\"center\"\u003e\r\n\u003cimg src=\"https://img.shields.io/static/v1?label=build with\u0026message=♡\u0026color=ff7751\u0026labelColor=1e2528\u0026style=for-the-badge\"\u003e\r\n\u003cbr\u003e\r\n\u003cimg src=\"https://img.shields.io/github/stars/imegeek/terminal-widgets?color=F2CD80\u0026labelColor=1e2528\u0026style=for-the-badge\"\u003e\r\n\u003cimg src=\"https://img.shields.io/static/v1?label=license\u0026message=MIT\u0026color=8ccf7e\u0026labelColor=1e2528\u0026style=for-the-badge\"\u003e\r\n\u003cimg src=\"https://img.shields.io/github/forks/imegeek/terminal-widgets?color=8EC8D8\u0026labelColor=1e2528\u0026style=for-the-badge\"\u003e\r\n\u003c/div\u003e\r\n\r\n## Features:\r\n\r\n- **System Information Widgets:**\r\n\r\n  - Displays system-related information such as battery status, weather, shell, storage details, hostname, date, RAM usage and many more.\r\n- **Customizable build-in Widgets:**\r\n\r\n  - Users can customize widgets according to their preferences, including text, color, icon, index and state.\r\n- **Addons Widgets:**\r\n\r\n  - Supports addon widgets with customizable text, color, script execution, icon display, and position settings.\r\n- **Dynamic Content Configuration:**\r\n\r\n  - Offers a dynamic way to set content inside text, script, or program files without explicitly defining color or icon keys.\r\n- **Configuration Options:**\r\n\r\n  - Provides a configuration file (`~/.twidgets.json`) for users to modify settings like custom color codes, addon widgets, and built-in widget configurations.\r\n- **Orientation Support:**\r\n\r\n  - Enables users to customize widget layout orientation, allowing display in either horizontal (row) or vertical (column) configurations for improved flexibility across different terminal setups.\r\n- **Custom Logo Support:**\r\n\r\n  - Provides the option to add a personalized logo through the configuration file (`~/.twidgets.json`).\r\n- **Easy Installation:**\r\n\r\n  - Available for installation via pip or as a local install for convenient setup.\r\n- **Color Formatting Support:**\r\n\r\n  - Supports color formatting using both named colors (e.g., `[red]`) and hexadecimal color codes.\r\n- **Icon Integration:**\r\n\r\n  - Allows integration of icons into text content using Unicode characters, enhancing visual representation within widgets.\r\n- **Supports Command Line Arguments**\r\n\r\n  - Terminal-Widgets offers support for command line arguments, providing users with flexibility in configuring and managing the program directly from the terminal.\r\n  - Refer to the [Argument Options](#argument) for more detailed information.\r\n\r\n## Screenshots\r\n\r\n\u003ckbd\u003e\r\n\u003cp align=\"center\"\u003eWindows\r\n\u003cimg src=\"https://github.com/imegeek/terminal-widgets/assets/63346676/0915b7ad-671d-4e37-b68d-cd3e292cb2ed\"\u003e\r\n\u003c/p\u003e\r\n\u003c/kbd\u003e\r\n\r\n\u003ckbd\u003e\r\n\u003cp align=\"center\"\u003eLinux\r\n\u003cimg src=\"https://github.com/imegeek/terminal-widgets/assets/63346676/64132f65-748e-4ee3-966b-7be73d5ce8b7\"\u003e\r\n\u003c/p\u003e\r\n\u003c/kbd\u003e\r\n\r\n\u003ckbd\u003e\r\n\u003cp align=\"center\"\u003emacOS\r\n\u003cimg src=\"https://github.com/imegeek/terminal-widgets/assets/63346676/5697d372-9855-4929-9935-641291ffe8cb\"\u003e\r\n\u003c/p\u003e\r\n\u003c/kbd\u003e\r\n\r\n\u003ckbd\u003e\r\n\u003cp align=\"center\"\u003eAndroid\r\n\u003cimg src=\"https://github.com/imegeek/terminal-widgets/assets/63346676/386088c8-5229-4899-bc1b-45f74aaeaa8d\"\u003e\r\n\u003c/p\u003e\r\n\u003c/kbd\u003e\r\n\r\n- Upload your custom edits for terminal-widgets [here](https://github.com/imegeek/terminal-widgets/issues/1)\r\n\r\n## Supported platforms\r\n\r\n- Linux\r\n- Windows\r\n- Darwin (macOS)\r\n- Android (Termux)\r\n- WSL (Windows Subsystem for Linux)\r\n\r\n## Getting Started\r\n\r\nTo start using Terminal Widgets, follow these steps:\r\n\r\n1. Install the program via pip or perform a local install.\r\n2. Ensure you have Nerd Font installed for optimal display.\r\n3. Customize your widgets and addons using the configuration file (`~/.twidgets.json`).\r\n4. Refer to the [Configuration](#configuration) for more detailed information on configuration options and usage.\r\n\r\n## Prerequisites\r\n\r\nBefore using Terminal Widgets, please ensure that you have the following prerequisites installed:\r\n\r\n1. **Python 3.x**: Terminal Widgets is written in Python and requires Python 3.x to be installed on your system.\r\n2. **Nerd Font**: Terminal Widgets requires Nerd Font for display glyphs. If not installed, download one from [here](https://www.nerdfonts.com/).\r\n3. **For Android users using Termux**:\r\n\r\n   - **Termux**: Terminal Widgets can be used on Android devices via Termux. Ensure that you have [Termux](https://f-droid.org/en/packages/com.termux/) installed on your Android device from the Google Play Store or F-Droid.\r\n   - **Termux-API**: Terminal Widgets requires the Termux-API app for certain functionalities. Install the [Termux-API](https://f-droid.org/en/packages/com.termux.api/) app from the Google Play Store or F-Droid.\r\n   - **termux-api**: Terminal Widgets requires the termux-api package for certain functionalities. Install termux-api by running the following command in your Termux terminal:\r\n\r\n     ```\r\n     pkg install termux-api\r\n     ```\r\n\r\n## Installation\r\n\r\nYou can install Terminal Widgets using pip, or you can clone the repository and install it locally.\r\n\r\n### Install via pip\r\n\r\nTo install Terminal Widgets via pip, simply run the following command:\r\n\r\n```\r\npip install terminal-widgets\r\n```\r\n\r\nor\r\n\r\n```\r\npip3 install terminal-widgets\r\n```\r\n\r\nThis will download and install the latest version of Terminal Widgets from the Python Package Index (PyPI) along with its dependencies.\r\n\r\n### Manual Installation\r\n\r\nTo install Terminal Widgets locally, follow these steps:\r\n\r\n1. Clone this repository to your local machine.\r\n   `git clone https://github.com/imegeek/terminal-widgets`\r\n2. Navigate to the cloned directory.\r\n   `cd terminal-widgets`\r\n3. Install the package using pip:\r\n   `pip install .`\r\n   or\r\n   `pip3 install .`\r\n\r\nThis will install Terminal Widgets along with its dependencies from the local source files.\r\n\r\n## Usage\r\n\r\nSimply run the **`twidgets`** in your terminal to get an overview of your system status.\r\ntry these command if not working:\r\n\r\n```shell\r\npython -m twidgets\r\n```\r\n\r\nor\r\n\r\n```shell\r\npython3 -m twidgets\r\n```\r\n\r\n\u003ca name=\"argument\"\u003e\u003c/a\u003e\r\n\r\n## Argument Options:\r\n\r\nTerminal-Widgets supports the following command line options for customization and control:\r\n\r\n| Argument                          | Description                                                                                                   |\r\n|-----------------------------------|---------------------------------------------------------------------------------------------------------------|\r\n| `-h`, `--help`                    | Show this help message and exit.                                                                              |\r\n| `-v`, `--version`                 | Show the program version.                                                                                     |\r\n| `-u`, `--update`                  | Update the program to the latest version.                                                                     |\r\n| `-c`, `--config file`             | Specify the JSON configuration file to load.                                                                  |\r\n| `--json`                          | Shows widgets output as JSON object.                                                                          |\r\n| `--stdout`                        | Turn off all colors and disable any ASCII, printing only text.                                                |\r\n| `--configs`                       | Show the configuration file.                                                                                  |\r\n| `--no-badge`                      | Show widgets without badge style.                                                                             |\r\n| `--color-bars`                    | Show color bars in terminal widgets.                                                                          |\r\n| `--logo ['pacman', 'linux', 'windows', 'macos', 'android', 'generic']` | Choose a logo art to appear before widgets (default: system default logo).                                   |\r\n| `--show ['logo', 'widgets']`      | Specify what to show: `logo` or `widgets`.                                                                    |\r\n| `--text {'detailed': 'includes extended information', 'compact': 'short, less detailed'}` | Choose text mode for terminal widgets (default: compact).                           |\r\n| `--color ['normal', 'vivid', 'random', 'custom']` | Choose color mode for terminal widgets (default: normal).                                               |\r\n| `--align ['left', 'center']`      | Choose alignment mode for terminal widgets (default: center).                                                 |\r\n| `--direction ['row', 'column']`   | Choose direction mode for terminal widgets (default: row).                                                    |\r\n| `--weather location`              | Set weather location to show in widgets.                                                                      |\r\n| `--weather-api API_KEY`           | Set Open Weather API key.                                                                                     |\r\n| `--bypass-system-api`             | Turn off API checking for the required system.                                                                |\r\n| `--column length`                 | Specify the number of widgets to display per row.                                                             |\r\n| `--column-gap length`             | Specify the gap between widgets displayed in each column.                                                     |\r\n| `--row-gap length`                | Specify the gap between widgets displayed in each row.                                                        |\r\n| `--margin length`                 | Specify the number of whitespace lines displayed before and after execution.                                  |\r\n\r\nThese options allow users to customize the behavior and appearance of Terminal-Widgets according to their preferences.\r\n\r\n\u003ca name=\"configuration\"\u003e\u003c/a\u003e\r\n\r\n## Configuration\r\n\r\nTerminal Widgets supports configuration options, allowing users to customize their widgets or add new ones.\r\n\r\nTo configure Terminal Widgets:\r\n\r\n1. Open the configuration file located at `~/.twidgets.json`.\r\n2. Modify the following key-value pairs according to your preferences:\r\n\r\n- **args**: Specifies the command-line arguments for widget configuration. (e.g., `'--direction row --column 1 --column-gap 1 --no-badge --text detailed'`).\r\n\r\n- **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.\r\n\r\n- **logo**: Customize the logo displayed before the widgets by defining an ASCII art logo as an array of strings under the \"logo\" key. Provide a name (e.g., `\"windows7\", \"macos\"`) and the corresponding art. The logo will appear in the terminal before other widgets, access the added logo using `--logo \u003clogo_name\u003e`.\r\n\r\n- **weather_api**: Provide your OpenWeatherMap API key for weather data.\r\n  - API_KEY: Provide your OpenWeatherMap API key here (e.g., \"weather_api\": \"xxxxxxxxxxxxxxxx\").\r\n\r\n\u003cbr\u003e\r\n\r\n- **addons**: Customize addon widgets. Use properties like `text`, `color`, `script`, `exec`, `icon`, and `index`.\r\n  - **text**: The text content to display for the addon.\r\n  - **color**: The color code for the addon text or icon.\r\n  - **script**: The Python script file or code to execute for dynamic text content.\r\n  - **exec**: The terminal command to execute for dynamic text content.\r\n  - **icon**: The UTF-8 code of the icon or glyph to display for the addon.\r\n  - **index**: The position of the addon in the widget layout.\r\n- **widgets**: Configure built-in widgets like `username`, `hostname`, `platform`, `shell`, `package`, etc. Use properties like `text`, `color`, `icon`, `index`, and `state`.\r\n  - **text**: The text content to display for the widget.\r\n  - **color**: The color code for the widget icon.\r\n  - **icon**: The UTF-8 code of the icon or glyph to display for the widget.\r\n  - **index**: The position of the widget in the widget layout.\r\n  - **state**: Use \"disabled\" value to hide specific widget.\r\n\r\n3. Dynamic Method for Defining **widget-addon** without Specifying 'color' or 'icon'.\r\n\r\n- **Add Text**:\r\n\r\n  - Simply input the desired text.\r\n- **Add Color**:\r\n\r\n  - \"[color_name or hex_code]\" marks the beginning of the color for the content.\r\n  - \"[/]\" signifies the end of color formatting.\r\n- **Add Icon**:\r\n\r\n  - Incorporate icons into text content using Unicode characters. For instance, utilize \"\\uf255\" to depict a custom Unicode character as an icon within the text.\r\n- Refer to Example 11 for further clarification.\r\n\r\n4. Save the changes and restart Terminal Widgets to apply the new configuration.\r\n\r\n## Configuration Examples\r\n\r\n- **Example 1:**\r\n  - This example defines custom **colors** code for terminal-widgets.\r\n\r\n```json\r\n{\r\n    \"colors\": {\r\n        \"red\": \"#FF0000\",\r\n        \"cyan\": \"#00FFFF\",\r\n        \"purple\": \"#a06efc\",\r\n        \"green\": \"#9ACB73\",\r\n        \"yellow\": \"#f8d255\",\r\n        \"sky\": \"#6AA1DA\"\r\n    }\r\n}\r\n```\r\n\r\n- **Example 2:**\r\n  - This example customize the logo in the Terminal Widgets.\r\n\r\n```json\r\n{\r\n    \"logo\": {\r\n        \"windows7\": [\r\n            \"        ,.=:!!t3Z3z.,               \",\r\n            \"       :tt:::tt333EE3               \",\r\n            \"       Et:::ztt33EEEL @Ee.,      ..,\",\r\n            \"      ;tt:::tt333EE7 ;EEEEEEttttt33#\",\r\n            \"     :Et:::zt333EEQ. $EEEEEttttt33QL\",\r\n            \"     it::::tt333EEF @EEEEEEttttt33F \",\r\n            \"    ;3=*^```\\\"*4EEV :EEEEEEttttt33@.\",\r\n            \"    ,.=::::!t=., ` @EEEEEEtttz33QF  \",\r\n            \"   ;::::::::zt33)   \\\"4EEEtttji3P*  \",\r\n            \"  :t::::::::tt33.:Z3z..  `` ,..g.   \",\r\n            \"  i::::::::zt33F AEEEtttt::::ztF    \",\r\n            \" ;:::::::::t33V ;EEEttttt::::t3     \",\r\n            \" E::::::::zt33L @EEEtttt::::z3F     \",\r\n            \"{3=*^```\\\"*4E3) ;EEEtttt:::::tZ`    \",\r\n            \"             ` :EEEEtttt::::z7      \",\r\n            \"                 \\\"VEzjt:;;z\u003e*`     \",\r\n            \"                                    \"\r\n        ]\r\n    }\r\n}\r\n```\r\n\r\n- **Example 3:**\r\n  - Configures the **build-in** widget `username` to change set custom color of icon.\r\n\r\n```json\r\n{\r\n    \"widgets\": {\r\n        \"username\": {\r\n            \"color\": \"#d0ff1f\"\r\n        }\r\n    }\r\n}\r\n```\r\n\r\n- **Example 4:**\r\n  - Configures the **build-in** widget `hostname` to display the text \"macbook pro\" at index 2 in the layout.\r\n\r\n```json\r\n{\r\n    \"widgets\": {\r\n        \"hostname\": {\r\n            \"text\": \"macbook pro\",\r\n            \"index\": 2\r\n        }\r\n    }\r\n}\r\n```\r\n\r\n- **Example 5:**\r\n  - Configures the **build-in** widget `platform` to display the text \"macos\" with the custom icon.\r\n\r\n```json\r\n{\r\n    \"widgets\": {\r\n        \"platform\": {\r\n          \"text\": \"macos\",\r\n          \"icon\": \"\\uf179\"\r\n        }\r\n    }\r\n}\r\n```\r\n\r\n- **Example 6:**\r\n  - Configures the **build-in** widget `shell` to display the text \"zsh\".\r\n\r\n```json\r\n{\r\n    \"widgets\": {\r\n          \"shell\": {\r\n            \"text\": \"zsh\"\r\n        }\r\n    }\r\n}\r\n```\r\n\r\n- **Example 7:**\r\n  - Disables the **build-in** widget `storage`, preventing it from being displayed.\r\n\r\n```json\r\n{\r\n    \"widgets\": {\r\n        \"storage\": {\r\n            \"state\": \"disabled\"\r\n        }\r\n    }\r\n}\r\n```\r\n\r\n- **Example 8:**\r\n  - Adds a welcome message **addon** with custom text, color, and position in the layout.\r\n\r\n```json\r\n{\r\n    \"addons\": {\r\n        \"welcome\": {\r\n            \"text\": \"Welcome to Terminal Widgets\",\r\n            \"color\": \"#afdaaf\",\r\n            \"index\": 2\r\n        }\r\n    }\r\n}\r\n```\r\n\r\n- **Example 9:**\r\n  - 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.\r\n\r\n```json\r\n{\r\n    \"addons\": {\r\n      \"cputemp\": {\r\n          \"script\": \"import random\\nprint(random.randint(30, 60), '\\u00B0C')\",\r\n          \"color\": \"#ff8522\",\r\n          \"icon\": \"\\udb84\\udcc3\"\r\n      }\r\n    }\r\n}\r\n```\r\n\r\n- **Example 10:**\r\n  - Configures the `process` **addon** to execute a Python script located at \"/path/to/the/file/script.py\".\r\n\r\n```json\r\n{\r\n    \"addons\": {\r\n        \"process\": {\r\n            \"script\": \"/path/to/the/file/script.py\"\r\n        }\r\n    }\r\n}\r\n```\r\n\r\n- **Example 11:**\r\n  - Configures the `pwd` addon to execute the \"pwd\" command in the terminal, displaying the current directory path with custom color and icon.\r\n\r\n```json\r\n{\r\n    \"addons\": {\r\n        \"pwd\": {\r\n          \"exec\": \"pwd\",\r\n          \"color\": \"#ffa0f4\",\r\n          \"icon\": \"\\uf07b\"\r\n        }\r\n    }\r\n}\r\n```\r\n\r\n- **Example 12:**\r\n  - Configures the `hi` addon to display custom formatted text with colors.\r\n    - **text**: Sets the text content to \"[#ff0000]\\uf255[/] [#eeff00]Hi, there[/]\", where:\r\n      - \"[#ff0000]\" specifies the start of red color for the text.\r\n      - \"\\uf255\" represents a custom Unicode character.\r\n      - \"[#eeff00]\" specifies the start of yellow-green color for the text \"Hi, there\".\r\n      - \"[/]\" specifies the end of the color formatting.\r\n      - \"Hi, there\" is the content to be displayed in yellow-green color and icon displayed in red color.\r\n\r\n```json\r\n{\r\n    \"addons\": {\r\n        \"hi\": {\r\n          \"text\": \"[#ff0000]\\uf255[/] [#eeff00]Hi, there[/]\"\r\n        }\r\n    }\r\n}\r\n```\r\n\r\n- **Example 13:**\r\n  - Configures the `color` addon to display custom color palette widget.\r\n    - Uses a Python script to generate colored blocks representing each color in the palette.\r\n    - Each color block is enclosed in color formatting tags, providing a visual representation of the color.\r\n    - The color key specifies the color of the palette widget.\r\n    - The icon key sets an icon for the palette widget.\r\n\r\n```json\r\n{\r\n  \"addons\": {\r\n    \"color\": {\r\n        \"script\": \"print(' '.join([f'[{color}]\\ueabc[/]' for color in ['black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white']]))\",\r\n        \"color\": \"#6aafff\",\r\n        \"icon\": \"\\ue22b\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n## Contributing\r\n\r\nContributions are welcome! If you have any suggestions, bug reports, or feature requests, please open an issue or submit a pull request on GitHub.\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](https://github.com/imegeek/terminal-widgets/blob/master/LICENSE) file for details.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimegeek%2Fterminal-widgets","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimegeek%2Fterminal-widgets","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimegeek%2Fterminal-widgets/lists"}