A lightweight terminal‑based tool for storing and reusing custom shell commands. It lets you build your own command library without unnecessary dependencies, a GUI or complicated configuration.

• Instalation
  • Oh My Zsh
    • Update
  • Manual
    • Manual update
• Description
• What can it do?
• Advantages
• Who is it for?
• .commands.sh file structure
  • Commands
  • Control instructions
    • Setting environment variables
    • Including other files
• Usage
• License

1. Clone this repository into $ZSH_CUSTOM/plugins (by default ~/.oh-my-zsh/custom/plugins)

git clone https://github.com/kamil-cy/zsh-cli-companion ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-cli-companion

2. Add the plugin to the list of plugins for Oh My Zsh to load (inside ~/.zshrc):

plugins=(
    # other plugins...
    zsh-cli-companion
)

Run

cd $ZSH_CUSTOM/plugins/zsh-cli-companion && git pull

1. Clone this repository somewhere on your machine. This guide will assume ~/.zsh/zsh-cli-companion.

git clone https://github.com/kamil-cy/zsh-cli-companion ~/.zsh/zsh-cli-companion

2. Add the following to your .zshrc:

source ~/.zsh/zsh-cli-companion/zsh-cli-companion.zsh

3. Start a new terminal session.

Run

cd ~/.zsh/zsh-cli-companion && git pull

A lightweight FZF‑based tool for storing and reusing your own commands. It provides a simple way to build your personal command library without unnecessary dependencies, GUIs, or complex configuration.

CLI Companion lets you store and quickly run your custom commands. Commands are saved in a file (by default .commands.sh) located in the current working directory (any parent directory) or in your home directory. You manage commands directly by editing the command file, making it easy to add, modify, and organize your personal command library. The tool allows you to browse available entries and execute them directly from the terminal, speeding up your workflow and eliminating the need to remember complex command syntax.

This way, you can create both a global set of commands and project‑specific, local sets tailored to particular environments.

Beginners can learn by exploring ready‑made examples. Advanced users can build their own library of scripts and commands instead of keeping them scattered in notes.

• store and organize commands along with your own descriptions and comments
• manage your library easily by editing a single file
• instantly search and insert commands into the terminal using fuzzy finders (fzf, skim, gum — one of them is required)
• execute commands without remembering their syntax
• optionally highlight syntax using external tools (e.g., batcat, highlight)

• works in a pure ZSH terminal with at least one fuzzy finder
• zero unnecessary dependencies
• simple, transparent structure
• ability to create local per‑project libraries
• quick access to frequently used commands

• anyone who wants to keep a personal command library at hand
• developers working across multiple projects
• users who don’t want to memorize long commands
• anyone who likes order in their terminal

The file contains control instructions and a list of commands.

Each command is written on a single line. You decide how to organize them — the tool simply reads and exposes them.

Example:

[optional categories SEPARATOR] actual command with arguments  # comment

To set an environment variable, prefix its name with !, then assign a value with = wrapped in " or '. Example:

!CLI_COMPANION_WIDGET_FINDER="gum"

The !append instruction includes another file at the end of the current one, without nested processing of control instructions. Example:

!append $HOME/.another_commands.sh

1. Create a .commands.sh file in your home or current directory.
2. Add your commands to it.
3. Launch the tool in the terminal using the CTRL+E shortcut.
4. Select a command from the list to insert it into the terminal.

This repository is licensed under the MIT License