A CLI utility to save, manage, and re-run shell commands with their working directories
A powerful CLI utility to save, manage, and re-run shell commands with their working directories. Never lose track of useful commands again!
As developers, we often spend time crafting complex commands, navigating to specific directories, and repeating the same sequences. AliasMate solves this by:
Whether you're a solo developer or part of a team, AliasMate helps you streamline your terminal workflow and maintain consistency across projects.
Install globally via npm:
npm i -g aliasmate
AliasMate supports auto-completion for bash, zsh, and fish shells. This provides tab completion for commands, saved command names, and flags.
The easiest way to install completion is to use the auto-installer:
aliasmate completion install
This will:
If you prefer manual installation or the auto-installer doesn't work for your setup:
Add to your ~/.bashrc:
source <(aliasmate completion bash)
Then reload:
source ~/.bashrc
Add to your ~/.zshrc:
source <(aliasmate completion zsh)
Then reload:
source ~/.zshrc
Generate the completion file:
aliasmate completion fish > ~/.config/fish/completions/aliasmate.fish
Fish will automatically load it on next shell start.
Example:
aliasmate ru<TAB> # Completes to "run"
aliasmate run bu<TAB> # Completes to your saved "build" command
aliasmate list --fo<TAB> # Completes to "--format"
For aliasmate prev to work reliably and capture commands immediately, configure your shell to write history in real-time:
Add to ~/.zshrc:
setopt INC_APPEND_HISTORY
Then reload:
source ~/.zshrc
Add to ~/.bashrc:
PROMPT_COMMAND="history -a"
Then reload:
source ~/.bashrc
Without this configuration, shells only write commands to the history file when the shell exits. This means:
npm run dev and press ^C to cancel it, then immediately run aliasmate prev, the command won't be in the history file yetclear or previous commands)With this configuration, every command is written to history immediately after execution, making aliasmate prev work perfectly every time.
aliasmate saveIf you prefer not to configure shell history, you can always use the interactive save:
aliasmate save
# Then enter your command manually
aliasmate prev <name>. For example:
npm run build
aliasmate prev build
aliasmate run <name>:
aliasmate run build
aliasmate list to see all saved commands, aliasmate edit <name> to modify them, and more!Automatically capture the last command you ran:
# After running any command, save it
aliasmate prev <name>
Example:
npm run build
aliasmate prev build
# ā Saved command as "build"
# Command: npm run build
# Directory: /path/to/project
Execute a saved command in its original directory:
aliasmate run <name>
Or override the directory:
aliasmate run <name> .
aliasmate run <name> /path/to/another/project
Dry-run mode (preview without executing):
aliasmate run <name> --dry-run
aliasmate run <name> --dry-run --verbose
Run recent commands by index:
aliasmate run @0 # Run most recent command
aliasmate run @1 # Run second most recent
Example:
aliasmate run build
# Running: npm run build
# Directory: /path/to/project
Manually save a command with interactive prompts:
aliasmate save
You'll be prompted for:
AliasMate now supports two path modes for each saved command:
Commands always run in the directory where they were saved. Perfect for project-specific commands.
# Save a build command for a specific project
cd /path/to/my-project
npm run build
aliasmate prev build
# Later, run from anywhere - it executes in /path/to/my-project
cd ~
aliasmate run build # Runs in /path/to/my-project
Commands run in your current working directory. Ideal for general-purpose utilities.
# Save a command with current directory mode
aliasmate save
# Enter name: lint
# Enter command: eslint .
# Enter directory: /any/path (doesn't matter)
# Choose: Current Directory
# Later, runs in whichever directory you're in
cd /path/to/project-a
aliasmate run lint # Lints project-a
cd /path/to/project-b
aliasmate run lint # Lints project-b
You can change the path mode anytime using aliasmate edit <name>.
AliasMate includes a default command that generates comprehensive documentation for AI assistants:
aliasmate run llm
This creates an llm.txt file in your current directory containing:
Share this file with AI assistants like ChatGPT or Claude for better help with AliasMate!
View all your saved commands:
aliasmate list
# or
aliasmate ls
Output:
Saved commands (3):
build
Command: npm run build
Directory: /path/to/project
deploy
Command: ./deploy.sh
Directory: /path/to/scripts
test
Command: pytest tests/
Directory: /path/to/python-project
Modify an existing command:
aliasmate edit <name>
Opens an interactive prompt to edit the command and directory.
Remove a command you no longer need:
aliasmate delete <name>
# or
aliasmate rm <name>
Backup your commands to a JSON file:
aliasmate export commands.json
Restore commands from a JSON file:
aliasmate import commands.json
If there are name conflicts, you'll be prompted to:
See where your commands are stored:
aliasmate config
AliasMate can capture and restore environment variables along with your commands:
When saving commands with prev or save, you'll be prompted to capture environment variables:
NODE_ENV=production npm run build
aliasmate prev build-prod
# Would you like to capture current environment variables? (y/n)
What Gets Captured:
NODE_ENV, API_URL, DEBUG)PATH, HOME, USER)KEY, SECRET, TOKEN, PASSWORD are automatically identifiedAPI_KEY=abc***xy)# Edit a command to update environment variables
aliasmate edit build-prod
# Select which variables to keep or remove
# View commands with their environment variables
aliasmate list
# Shows which commands have env vars saved
Use Cases:
DEBUG=*, VERBOSE=true)Example:
# Development setup
NODE_ENV=development API_URL=http://localhost:3000 npm start
aliasmate prev dev-server
# Run anywhere - environment is restored
aliasmate run dev-server
# Restores NODE_ENV and API_URL automatically
View what's new and see changes between versions:
# View current version changes
aliasmate changelog
# View specific version
aliasmate changelog --ver 1.3.0
# View all changes between versions (upgrade path)
aliasmate changelog --from 1.2.0 --to 1.4.0
# View all changes since a version
aliasmate changelog --from 1.2.0
Automatic Upgrade Notifications: When you upgrade AliasMate, you'll automatically see:
This ensures you never miss important features or fixes when upgrading!
Create short aliases for frequently used saved commands:
# Create an alias
aliasmate alias b build
aliasmate alias d deploy-prod
# List all aliases
aliasmate alias --list
# Remove an alias
aliasmate alias --remove b
Features:
Example:
# Create aliases for common commands
aliasmate alias b build
aliasmate alias t test
aliasmate alias dp deploy-prod
# Use the aliases
aliasmate run b # Runs 'build' command
aliasmate run @0 # Runs most recent command
Track and quickly re-run recently executed commands:
# View recent commands
aliasmate recent
# Limit the list
aliasmate recent --limit 10
# Clear history
aliasmate recent --clear
Quick re-execution with @N syntax:
aliasmate run @0 # Run most recent command
aliasmate run @1 # Run second most recent
aliasmate run @2 # Run third most recent
Features:
Preview what will execute before running a command:
# Basic preview
aliasmate run build --dry-run
# Detailed preview with env vars
aliasmate run build --dry-run --verbose
What you'll see:
Example output:
š DRY RUN MODE - Command will NOT be executed
Command:
npm run build --production
Working Directory:
/path/to/project
Path Mode:
saved
Environment Variables:
3 variable(s) will be loaded
NODE_ENV=production
API_URL=https://api.example.com
API_KEY=abc***xyz (masked)
ā ļø WARNING: This command may be dangerous
To execute, run without --dry-run flag
Validate commands when saving to catch errors early:
# Validate a single command
aliasmate validate build
# Validate all commands
aliasmate validate --all
# Skip validation when saving (bypass checks)
aliasmate save --no-validate
aliasmate edit <name> --no-validate
What gets validated:
Validation types:
Example:
$ aliasmate validate build
Validating command: build
ā No issues found
Command: npm run build
Directory: /path/to/project
Environment Variables: 2
$ aliasmate validate --all
Validating 15 saved commands...
ā 13 commands passed validation
ā 2 commands have warnings
Commands with issues:
deploy: Warning - Command 'deploy.sh' not found in PATH
Export or view commands in multiple formats:
# List in different formats
aliasmate list --format table # Default human-readable
aliasmate list --format json # Machine-readable JSON
aliasmate list --format yaml # YAML format
aliasmate list --format compact # One-line per command
# Export with format
aliasmate export commands.json --format json
aliasmate export commands.yaml --format yaml
Format examples:
JSON:
{
"build": {
"command": "npm run build",
"directory": "/path/to/project",
"pathMode": "saved",
"env": { "NODE_ENV": "production" },
"createdAt": "2026-01-22T10:00:00Z"
}
}
YAML:
build:
command: "npm run build"
directory: "/path/to/project"
pathMode: saved
env:
NODE_ENV: "production"
createdAt: "2026-01-22T10:00:00Z"
Compact:
build: npm run build (/path/to/project)
test: npm test (/path/to/project)
deploy: ./deploy.sh (/path/to/scripts)
Use cases:
Commands are stored in:
~/.config/aliasmate/config.json%USERPROFILE%\.config\aliasmate\config.json| Command | Aliases | Description |
|---|---|---|
aliasmate prev <name> | - | Save the previous command from shell history (with optional env vars) |
aliasmate run <name> [path] | - | Run a saved command (restores env vars, optionally override directory) |
aliasmate run @N | - | Run Nth recent command (e.g., @0 = most recent) |
aliasmate run <name> --dry-run | - | Preview command without executing |
aliasmate save | - | Interactively save a new command (with optional env vars) |
aliasmate save --no-validate | - | Save command without validation |
aliasmate list | ls | List all saved commands (shows env var indicators) |
aliasmate list --format <type> | - | List in different formats (table/json/yaml/compact) |
aliasmate search <query> | find | Search for commands by name, text, or directory |
aliasmate edit <name> | - | Edit a saved command (manage env vars, path mode, etc.) |
aliasmate edit <name> --no-validate | - | Edit command without validation |
aliasmate delete <name> | rm | Delete a saved command |
aliasmate export <file> | - | Export commands to a file (sensitive vars masked) |
aliasmate export <file> --format <type> | - | Export in JSON or YAML format |
aliasmate import <file> | - | Import commands from a file (auto backup) |
aliasmate alias <short> <command> | - | Create alias for a command |
aliasmate alias --list | - | List all aliases |
aliasmate alias --remove <alias> | - | Remove an alias |
aliasmate recent | - | Show recently executed commands |
aliasmate recent --limit <N> | - | Limit recent commands displayed |
aliasmate recent --clear | - | Clear execution history |
aliasmate validate <name> | - | Validate a single command |
aliasmate validate --all | - | Validate all saved commands |
aliasmate completion install | - | Auto-install shell completion for your shell |
aliasmate completion <shell> | - | Generate shell completion script (bash, zsh, fish) |
aliasmate changelog | changes | View version changelog and release notes |
aliasmate config | - | Show config file location and command count |
1. Save and reuse a build command:
cd /my/project
npm run build -- --production
aliasmate prev build-prod
# Later, from anywhere:
aliasmate run build-prod
2. Save a deployment script:
aliasmate save
# Name: deploy
# Command: ./scripts/deploy.sh --env production
# Directory: /path/to/project
3. Run a command in a different directory:
aliasmate run test /path/to/different/project
4. Backup your commands:
aliasmate export ~/backups/aliasmate-$(date +%Y%m%d).json
5. Share commands with your team:
# Person A
aliasmate export team-commands.json
# Person B
aliasmate import team-commands.json
build-prod, test-unit, deploy-staging)prev command is great for saving complex commands you just figured outThis happens when shell history is disabled or the command hasn't been written to the history file yet.
Common scenario: You run a command, press ^C to cancel it, and immediately run aliasmate prev, but it captures an older command (like clear) instead.
Why: Most shells only write to history when the shell exits, not after each command.
Solution: Configure real-time history writing (see Shell Configuration above):
setopt INC_APPEND_HISTORY to ~/.zshrcPROMPT_COMMAND="history -a" to ~/.bashrcQuick fix: Close and reopen your terminal, then try the command again.
Alternative: Use aliasmate save to enter commands manually.
aliasmate listMake sure your shell history is enabled:
~/.zsh_history (zsh) or ~/.bash_history (bash)To work on AliasMate locally:
# Clone the repository
git clone https://github.com/aliasmate/aliasmate.git
cd aliasmate
# Install dependencies
npm install
# Build the project
npm run build
# Run type checking
npm run typecheck
# Lint the code
npm run lint
# Format code
npm run format
# Link for local testing
npm link
# Test the CLI
aliasmate --help
| Script | Description |
|---|---|
npm run build | Compile TypeScript to JavaScript |
npm run dev | Watch mode for development |
npm run typecheck | Run TypeScript type checking |
npm run lint | Check code quality with ESLint |
npm run lint:fix | Auto-fix ESLint issues |
npm run format | Format code with Prettier |
npm run format:check | Check if code is formatted |
AliasMate is built with modern development practices:
For detailed contribution guidelines, see CONTRIBUTING.md.
aliasmate/
āāā src/
ā āāā cli.ts # CLI entry point
ā āāā commands/ # Command implementations
ā ā āāā prev.ts # Save from history
ā ā āāā run.ts # Execute commands
ā ā āāā save.ts # Interactive save
ā ā āāā list.ts # Display all
ā ā āāā edit.ts # Modify commands
ā ā āāā delete.ts # Remove commands
ā ā āāā export.ts # Backup to JSON
ā ā āāā import.ts # Restore from JSON
ā āāā storage/
ā ā āāā index.ts # Config persistence
ā āāā utils/
ā āāā constants.ts # Shared constants
ā āāā errors.ts # Error handling
ā āāā executor.ts # Command execution
ā āāā history.ts # Shell integration
ā āāā paths.ts # Path utilities
āāā dist/ # Compiled output
āāā docs/
āāā CONTRIBUTING.md # Contributor guide
āāā DEV_GUIDE.md # Quick reference
āāā CLEANUP_SUMMARY.md # Code quality report
MIT
Contributions are welcome! We appreciate:
Maintainer: AliasMate Contributors
See CHANGELOG.md for version history and release notes.
ā If you find AliasMate helpful, please consider giving it a star on GitHub!
Before contributing, please:
# Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/aliasmate.git
cd aliasmate
# Install dependencies
npm install
# Make your changes, then:
npm run format # Format code
npm run lint # Check for issues
npm run typecheck # Verify types
npm run build # Build project
# Test locally
npm link
aliasmate --help
See DEV_GUIDE.md for detailed development workflows.
Created with ā¤ļø for developers who love productivity tools.
FAQs
A CLI utility to save, manage, and re-run shell commands with their working directories
The npm package aliasmate receives a total of 1 weekly downloads. As such, aliasmate popularity was classified as not popular.
We found that aliasmate demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago.Ā It has 1 open source maintainer collaborating on the project.
Threat Research
/Security News
Cursor removed a malicious Claude Code 2.1.313 extension from its marketplace. Socket examines registry records and the initial claims about its distribution.
Security News
An OpenCode user faced harassment after reporting a free AI usage loophole, drawing a bitter backlash in a GitHub thread that has since been deleted.
Threat Research
/Security News
319 browser extensions installed by 13.4 million users hijack searches, capture queries, and collect referral payments from Yahoo and Bing.