cmdmark 0.0.6

A CLI tool for managing commands like bookmarks

cmdmark

A CLI tool for managing commands like bookmarks. This Python script provides a simple way to manage and execute frequently used commands via YAML configuration files. Think of it like a bookmark manager, but for your terminal commands.

Features

• Categorized Commands: Organize your commands into categories stored in subfolders.
• YAML Configuration: Define commands and their descriptions in easy-to-read YAML files.
• Interactive Selection: Choose categories, files, and commands interactively from the terminal.
• Direct Execution: Execute selected commands directly within the script.
• Git-Aware: Git metadata files (e.g., .git folders) are ignored when listing categories and YAML files.
• Verbose Mode: Pass -v to show each command's description when listing commands.

Setup

1. Installation:

   The preferred way to install cmdmark is via pipx (recommended) or pip:

   pipx install cmdmark # recommended way.
   # OR
   pip install cmdmark
   

   This will install cmdmark and its dependency, PyYAML. This project requires Python 3.12 or higher.

2. Configuration Directory: The script uses a configuration directory located at ~/.command_bookmarks. Make sure that the directory exists. You may create some sub-directories in ~/.command_bookmarks to categorize your commands, and create yml files to store the relative commands. You can override this location by setting the environment variable CMDMARK_CONFIG_DIR.

   For example, in your shell configuration (e.g. ~/.bashrc or ~/.zshrc):

   export CMDMARK_CONFIG_DIR="$HOME/my_cmdmarks"
   

3. YAML Files: Create YAML files within the configuration directory (or its subdirectories) to define your commands. The structure of the YAML file is as follows:

   commands:
     alias1:
       command: "your_command_here"
       description: "A short description of the command"
     alias2:
       command: "another_command"
       description: "Another description"
   

   • commands: The top-level key.
   • alias1, alias2, etc.: Short, user-friendly aliases for your commands. These are displayed in the selection menu.
   • command: The actual command to be executed.
   • description: (Optional) A brief description of the command.

Usage

1. Run the script:

   cmdmark
   

   Use -v or --verbose to also show each command's description when listing commands.

2. Interactive Navigation:

   • The script will first list the available categories (subfolders) within ~/.command_bookmarks.
   • Select a category by entering its number.
   • The script will then list the YAML files within the selected category.
   • Select a YAML file by entering its number.
   • Finally, the script will list the commands defined in the selected YAML file. When -v is used, each command's description is shown alongside the command itself.
   • Select a command by entering its number.

3. Command Execution: The selected command will be executed in your terminal.

Example

Let's say you have the following structure (see tests/samples). For example, the directory might look like:

~/.command_bookmarks/
├── git/
│   ├── basic.yml
│   └── branch.yml
└── sys/
    └── disk.yml

The files under tests/sample/ provide ready-made examples you can copy into your configuration directory.

tests/sample/git/basic.yml includes common git commands:

commands:
  status:
    command: "git status"
    description: "Show the working tree status"
  add_all:
    command: "git add ."
    description: "Add all changes to staging"
  commit:
    command: "git commit -m"
    description: "Commit changes (requires message)"

tests/sample/sys/disk.yml defines a couple of useful system commands:

commands:
  check_disk:
    command: "df -h"
    description: "Check disk space usage"
  disk_usage:
    command: "du -sh ~"
    description: "Show disk usage of home directory"

Quick demo

cp -r tests/sample/* ~/.command_bookmarks/
cmdmark

Select a category (e.g. git), choose a YAML file such as basic.yml, and then pick a command like status. cmdmark will run git status right away.

Docker

The repository includes a Dockerfile so you can build a containerized environment for running the tests or invoking the CLI.

# Build the image
docker build -t cmdmark .

# Run the test suite
docker run --rm cmdmark

# Or start the CLI (override the default command)
docker run --rm -it cmdmark cmdmark