cmdlog: The "Black Box" Flight Recorder for Your Terminal

Stop losing context. cmdlog is a lightweight Zsh plugin that tracks execution time, git branch, conda/venv environment, and exit codes for every command you run.

Unlike standard shell history, cmdlog answers:

• Where did I run that command?
• Which git branch was active?
• Why did it fail? (Exit code)
• How long did it take?

Features

• 🕒 Duration Tracking: Automatically logs execution time if >3 seconds (e.g., [2m4s])
• 🌿 Git Aware: Captures the active branch for every command
• 🐍 Env Aware: Logs your Conda or Venv environment
• ❌ Exit Codes: Tracks failures so you can filter for what worked vs. what broke
• 🔍 Powerful Querying: Built-in aliases to search, filter, and analyze history
• ⚡ Zero Latency: Uses native Zsh hooks for zero perceptible lag

Installation

Automatic (Recommended)

Run this single command to install cmdlog:

curl -fsSL https://raw.githubusercontent.com/smaxiso/cmdlog/main/install.sh | bash

Manual

1. Clone this repository:

   git clone https://github.com/smaxiso/cmdlog.git ~/.cmdlog

2. Source it in your ~/.zshrc:

   source ~/.cmdlog/cmdlog.zsh

3. Reload your shell:

   source ~/.zshrc

Usage

Once installed, your commands are automatically logged. Use these aliases to query them:

Command	Description
cmdlog [N|all]	View the last N commands (default: 20) or all history
cmd-here [N|all]	Show commands run in the current directory (default: 20)
cmd-git	Show git-related commands only
cmd-errors	Show only failed commands (non-zero exit code)
cmd-stats	Show usage statistics (top commands, failure rate)
cmdsearch <term>	Search for a specific command keyword

📖 Cookbook

"I forgot how I built this project last month"

Go to the project folder and run:

cmd-here all

This shows every command ever run inside that specific folder.

"What was I doing before my computer crashed?"

See the very last commands you ran:

cmd-today

"Why is my script failing?"

Filter for commands that returned a non-zero exit code:

cmd-errors

"Monitor a long running task"

Open a new terminal pane and watch commands being logged live:

cmdlive

Configuration

By default, history is saved to ~/.global_history. You can change this by setting the variable before sourcing the script:

export GLOBAL_HISTORY_FILE="$HOME/.my_custom_history_file"
source ~/.cmdlog/cmdlog.zsh

License

MIT