Shortcuts TUI

A comprehensive terminal user interface (TUI) application for displaying and managing tools and shortcuts from configuration files.

Features

• 🖥️ Modern TUI Interface - Built with ratatui for a responsive terminal experience
• 📁 Multiple Configuration Formats - Support for both TOML and JSON configuration files
• 🌐 Cross-Platform Config Discovery - Automatic configuration file discovery across Windows, macOS, Linux, and Android/Termux
• 🔧 Environment Variable Support - Use SHORTCUTS_TUI_CONFIG environment variable to specify config file location
• 🔍 Powerful Search - Search across tool names, descriptions, tags, and metadata
• 🏷️ Flexible Organization - Organize tools by categories and tags
• ⌨️ Keyboard Shortcuts - Define and display keyboard shortcuts for quick access
• 🚀 Command Execution - Execute tool commands directly from the interface
• ✅ Configuration Validation - Built-in validation with helpful error messages
• 📊 Multiple Views - Tools, categories, search, and help views
• 🎨 Customizable - Extensible design for easy customization

Quick Start

Installation

Install from crates.io:

cargo install shortcuts-tui

Or build from source:

git clone https://github.com/yourusername/shortcuts-and-tools
cd shortcuts-and-tools
cargo build --release

Basic Usage

1. Create a sample configuration:

   shortcuts-tui init my-tools.toml
   

2. Edit the configuration file to add your tools and shortcuts

3. Run the TUI application:

   # Option 1: Specify config file directly
   shortcuts-tui --config my-tools.toml
   
   # Option 2: Use environment variable
   export SHORTCUTS_TUI_CONFIG="my-tools.toml"
   shortcuts-tui
   
   # Option 3: Place config in a standard location and let it auto-discover
   mkdir -p ~/.config/shortcuts-tui
   mv my-tools.toml ~/.config/shortcuts-tui/shortcuts.toml
   shortcuts-tui
   

Command Line Interface

shortcuts-tui [OPTIONS] [SUBCOMMAND]

OPTIONS:
    -c, --config <FILE>    Configuration file path (TOML or JSON)
    -v, --verbose          Increase logging verbosity
    -h, --help             Print help information
    -V, --version          Print version information

SUBCOMMANDS:
    init        Initialize a new configuration file
    validate    Validate a configuration file
    list        List tools from configuration
    help        Print this message or the help of the given subcommand(s)

Configuration

Configuration File Loading

Shortcuts TUI provides flexible configuration loading with multiple options:

1. Environment Variable

Set the SHORTCUTS_TUI_CONFIG environment variable to specify a configuration file:

export SHORTCUTS_TUI_CONFIG="/path/to/my/config.toml"
shortcuts-tui  # Automatically uses the config from environment variable

2. Command Line Argument

Specify a configuration file using the --config flag (overrides environment variable):

shortcuts-tui --config /path/to/my/config.toml

3. Automatic Discovery

If no configuration is specified, shortcuts-tui searches in these locations (in order):

On All Platforms:

• Current directory (.)
• User config directory (varies by platform)

Linux/Unix/macOS:

• /etc/shortcuts-tui/
• /usr/local/etc/shortcuts-tui/
• $XDG_CONFIG_HOME/shortcuts-tui/ (if XDG_CONFIG_HOME is set)
• $HOME/.config/shortcuts-tui/
• $HOME/.shortcuts-tui/

Windows:

• %PROGRAMDATA%\shortcuts-tui\
• %APPDATA%\shortcuts-tui\
• %LOCALAPPDATA%\shortcuts-tui\

Android/Termux:

• $PREFIX/etc/shortcuts-tui/ (usually /data/data/com.termux/files/usr/etc/shortcuts-tui/)
• $HOME/.config/shortcuts-tui/
• $HOME/.shortcuts-tui/

For each directory, it searches for files named:

• shortcuts.toml, shortcuts.json
• config.toml, config.json
• tools.toml, tools.json

Configuration Format

Shortcuts TUI supports both TOML and JSON configuration formats. The configuration consists of:

• Metadata - Information about your tool collection
• Categories - Optional groupings for your tools
• Tools - The actual tools and shortcuts

TOML Example

[metadata]
title = "My Development Tools"
description = "A collection of useful development tools and shortcuts"
version = "1.0"
author = "Developer"

[[categories]]
id = "dev"
name = "Development"
description = "Software development tools"
icon = "💻"
color = "blue"

[[categories]]
id = "system"
name = "System"
description = "System administration tools"
icon = "⚙️"
color = "red"

[[tools]]
id = "git_status"
name = "Git Status"
description = "Check git repository status"
command = "git status"
shortcut = "Ctrl+G S"
category = "dev"
tags = ["git", "vcs"]
priority = 10
enabled = true

[tools.metadata]
documentation = "https://git-scm.com/docs/git-status"

[[tools]]
id = "disk_usage"
name = "Disk Usage"
description = "Check disk usage"
command = "df -h"
category = "system"
tags = ["disk", "monitoring"]
priority = 5
enabled = true

JSON Example

{
  "metadata": {
    "title": "My Development Tools",
    "description": "A collection of useful development tools and shortcuts",
    "version": "1.0",
    "author": "Developer"
  },
  "categories": [
    {
      "id": "dev",
      "name": "Development",
      "description": "Software development tools",
      "icon": "💻",
      "color": "blue"
    }
  ],
  "tools": [
    {
      "id": "git_status",
      "name": "Git Status",
      "description": "Check git repository status",
      "command": "git status",
      "shortcut": "Ctrl+G S",
      "category": "dev",
      "tags": ["git", "vcs"],
      "priority": 10,
      "enabled": true,
      "metadata": {
        "documentation": "https://git-scm.com/docs/git-status"
      }
    }
  ]
}

TUI Interface

Navigation

• Arrow Keys / j,k - Navigate up/down in lists
• 1-4 - Switch between views (Tools, Categories, Search, Help)
• Tab - Switch between panels
• Enter - Execute selected tool
• Space - Show tool details
• / - Start search
• Esc - Cancel search/close popup
• q / Ctrl+C - Quit application

Views

1. Tools View - Main list of tools with details panel
2. Categories View - Browse tools by category
3. Search View - Search and filter tools
4. Help View - Keyboard shortcuts and help

Configuration Schema

Tool Properties

Category Properties

Library Usage

Shortcuts TUI can also be used as a library in your Rust projects:

use shortcuts_tui::{
    config::{Config, Tool, Category, loader::ConfigLoader},
    ui::TuiApp,
    error::Result,
};

fn main() -> Result<()> {
    // Load configuration
    let loader = ConfigLoader::new();
    let config = loader.load_file("my-config.toml")?;

    // Create and run TUI
    let app = TuiApp::new(config)?;
    app.run()?;

    Ok(())
}

Examples

The examples/ directory contains several examples:

• basic_usage.rs - Creating configuration programmatically
• config_loader.rs - Different ways to load configurations

Run examples with:

cargo run --example basic_usage
cargo run --example config_loader

Development

Building

cargo build

Testing

# Run unit tests
cargo test

# Run integration tests
cargo test --test integration_tests

# Run all tests with logging
RUST_LOG=debug cargo test

# Run expensive tests (large configurations)
cargo test --features expensive_tests

Linting

cargo clippy
cargo fmt

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License

This project is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Changelog

See CHANGELOG.md for a detailed list of changes in each version.

Acknowledgments

• Built with ratatui for the terminal UI
• Uses serde for configuration parsing
• Inspired by various terminal-based tool launchers and shortcuts managers