Akash

Name decomposition: also known as + shell

Tired of rewriting the same aliases every time you switch shells or machines?

Whether you're jumping between Bash on Linux, Zsh on macOS, and PowerShell on Windows, keeping your aliases in sync is a nightmare. Each shell has its own syntax, its own config file, and your carefully crafted shortcuts get scattered across different dotfiles.

Akash solves this by giving you one place to rule them all 💍 A single, portable alias store that automatically translates to the right syntax for whatever shell you're using. Write once, use everywhere.

A cross-platform CLI tool for managing shell aliases, written in Rust.

Table of Contents

• Akash
  • Quick Start
  • Features
  • Supported Shells
  • Installation
    • From Source
    • Install from crates
    • Add to PATH
    • Uninstall
  • Usage
    • Commands
    • Global Flags
    • Examples
  • Interactive Mode
  • How It Works
    • Alias Storage
    • Shell Config Modification
    • Shell Detection
  • Alias Name Rules
  • Development
    • Prerequisites
    • Building
    • Running Tests
    • Project Structure
    • Understand CI/CD pipeline
  • Dependencies
  • Troubleshooting
    • Aliases not working after apply
    • Wrong shell detected
    • Permission denied on config file
    • Aliases not persisting
  • Contributing
  • Releasing (Maintainers only)
    • Using the release script
    • Manual release
    • Using Makefile
    • What happens after the tag is pushed
  • License
  • Author
  • Why Akash?
  • Other similar tools
    • Rust Projects
    • Go Projects
    • Shell Script Projects

Quick Start

# 1. Build the project
cargo build --release

# 2. Add some aliases
aka add gs "git status"
aka add gp "git push"
aka add ll "ls -la"

# 3. Apply to your shell config
aka apply

# 4. Reload your shell
source ~/.bashrc   # or ~/.zshrc, or restart PowerShell

Features

• Centralized alias management across multiple shells
• Cross-platform support (Windows, macOS, Linux)
• Interactive mode with menu-driven interface
• Automatic shell detection
• Persistent storage in JSON format
• Safe config file modification with block markers

Supported Shells

Installation

From Source

# Clone the repository
git clone https://github.com/helene-nguyen/rust-akash.git
cd rust-akash

# Build and install
cargo build --release

# The binary will be at target/release/akash (or akash.exe on Windows)

Install from crates

cargo install akash

Add to PATH

After building, add the binary to your PATH or copy it to a directory in your PATH:

# Linux/macOS
cp target/release/akash ~/.local/bin/

# Windows (PowerShell)
Copy-Item target\release\akash.exe $env:USERPROFILE\.local\bin\

Uninstall

# 1. Remove the binary
rm ~/.local/bin/akash  # or wherever you installed it

# 2. Remove the alias store (optional)
rm -rf ~/.akash

# 3. Remove the alias block from your shell config
# Edit ~/.bashrc, ~/.zshrc, or $PROFILE and delete the block between:
# BEGIN akash aliases ... END akash aliases

Usage

Akash provides two binary names for convenience: akash and aka.

Commands

# Add a new alias
akash add <name> <command>
aka add gs "git status"

# Remove an alias
akash remove <name>
aka remove gs

# List all aliases
akash list
aka list

# Apply aliases to shell config
akash apply
aka apply

# Initialize shell configuration (first-time setup)
akash init
aka init

# Start interactive mode (default when no command)
akash
aka

Global Flags

# Override detected shell
akash --shell <SHELL> <command>
akash -s bash add gs "git status"

# Supported shell values: bash, zsh, powershell, pwsh, git-bash

Examples

# Add common git aliases
aka add gs "git status"
aka add gp "git push"
aka add gl "git log --oneline -10"
aka add gco "git checkout"

# Add system aliases
aka add ll "ls -la"
aka add ..  "cd .."
aka add cls "clear"

# Apply to shell and see them take effect
aka apply

# Reload your shell or source the config
source ~/.bashrc  # Bash
source ~/.zshrc   # Zsh
. $PROFILE        # PowerShell

Interactive Mode

Running akash or aka without arguments starts the interactive mode:

 .--..--..--..--..--..--..--..--..--..--..--..--..--.
/ .. \.. \.. \.. \.. \.. \.. \.. \.. \.. \.. \.. \.. \
\ \/\ `'\ `'\ `'\ `'\ `'\ `'\ `'\ `'\ `'\ `'\ `'\ \/ /
 \/ /`--'`--'`--'`--'`--'`--'`--'`--'`--'`--'`--'\/ /
 / /\                                            / /\
/ /\ \  █████╗ ██╗  ██╗ █████╗ ███████╗██╗  ██╗ / /\ \
\ \/ / ██╔══██╗██║ ██╔╝██╔══██╗██╔════╝██║  ██║ \ \/ /
 \/ /  ███████║█████╔╝ ███████║███████╗███████║  \/ /
 / /\  ██╔══██║██╔═██╗ ██╔══██║╚════██║██╔══██║  / /\
/ /\ \ ██║  ██║██║  ██╗██║  ██║███████║██║  ██║ / /\ \
\ \/ / ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝ \ \/ /
 \/ /                                            \/ /
 / /\.--..--..--..--..--..--..--..--..--..--..--./ /\
/ /\ \.. \.. \.. \.. \.. \.. \.. \.. \.. \.. \.. \/\ \
\ `'\ `'\ `'\ `'\ `'\ `'\ `'\ `'\ `'\ `'\ `'\ `'\ `' /
 `--'`--'`--'`--'`--'`--'`--'`--'`--'`--'`--'`--'`--'
Detected shell: PowerShell

What would you like to do?
  1) Add an alias
  2) Remove an alias
  3) List aliases
  4) Apply aliases to shell config
  5) Init (setup shell config)
  q) Quit

How It Works

Alias Storage

Aliases are stored in ~/.akash/aliases.json:

{
  "aliases": {
    "gs": "git status",
    "gp": "git push",
    "ll": "ls -la"
  }
}

Shell Config Modification

When you run akash apply, the tool:

1. Reads your shell's config file
2. Looks for akash markers (# BEGIN akash aliases / # END akash aliases)
3. Replaces the block between markers (or appends if not found)
4. Preserves all other content in your config

Example block added to .bashrc:

# BEGIN akash aliases
alias gs='git status'
alias gp='git push'
alias ll='ls -la'
# END akash aliases

Shell Detection

Akash automatically detects your current shell using:

1. Parent process name (most accurate)
2. Environment variables ($SHELL, $BASH_VERSION, $ZSH_VERSION)
3. OS fallback (Windows → PowerShell, macOS → Zsh, Linux → Bash)

Override with --shell flag if detection is incorrect.

Alias Name Rules

Valid alias names must:

• Be non-empty
• Contain only alphanumeric characters, underscores (_), or hyphens (-)

# Valid
aka add my-alias "echo hello"
aka add my_alias "echo hello"
aka add alias123 "echo hello"

# Invalid
aka add "my alias" "echo hello"  # Contains space
aka add "alias!" "echo hello"    # Contains special character

Development

Prerequisites

• Rust 1.85+ (Edition 2024)
• Cargo

Building

cargo build          # Debug build
cargo build --release # Release build

Running Tests

cargo test

Tests use Gherkin-style naming (given_X_when_Y_then_Z) for clarity.

Project Structure

src/
├── main.rs           # Entry point and command handlers
├── cli.rs            # CLI argument parsing (clap)
├── store.rs          # Alias storage and persistence
├── interactive.rs    # Interactive mode UI
└── shell/
    ├── mod.rs        # Shell trait and detection
    ├── unix.rs       # Bash and Zsh implementations
    └── windows.rs    # PowerShell implementation

Understand CI/CD pipeline

The CI/CD and release process is documented in Build Release Guide, covering:

• GitHub Actions workflow structure
• Build and release steps
• Caching strategy
• Common issues and troubleshooting tips

Dependencies

Troubleshooting

Aliases not working after apply

Make sure to reload your shell configuration:

source ~/.bashrc   # Bash
source ~/.zshrc    # Zsh
. $PROFILE         # PowerShell

Or simply restart your terminal.

Wrong shell detected

Use the --shell flag to override detection:

aka --shell bash apply
aka -s zsh list

Permission denied on config file

Ensure you have write permissions to your shell's config file:

ls -la ~/.bashrc   # Check permissions
chmod u+w ~/.bashrc # Add write permission if needed

Aliases not persisting

Check that your alias store exists and is valid JSON:

cat ~/.akash/aliases.json

If corrupted, you can reset it:

rm ~/.akash/aliases.json
aka add test "echo hello"  # Creates a fresh store

Contributing

Contribution is welcomed :)

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: cargo test
5. Submit a pull request

Releasing (Maintainers only)

Releases are fully automated via GitHub Actions. Pushing a v* tag triggers the pipeline which builds binaries, publishes to crates.io, pushes Docker images, and creates a GitHub Release.

Using the release script

./scripts/release.sh

The script will:

1. Read the current version from Cargo.toml
2. Prompt you for the new version number
3. Create an annotated git tag (v<version>)
4. Push the tag to origin, which triggers the Auto Release workflow

Manual release

git tag -a v0.2.0 -m ":bookmark: Release v0.2.0"
git push origin v0.2.0

Using Makefile

make release
# This will run the same steps as the release script

#Output
akash on  main [✓] is 📦 v0.1.0 via 🦀 v1.93.0
> make release
Current version: 0.1.0

New version (without v): 0.2.0
Release title will be: :bookmark: Release v0.2.0

  Tag:   v0.2.0
  Title: :bookmark: Release v0.2.0

Confirm? (y/n): y
Enumerating objects: 1, done.
Counting objects: 100% (1/1), done.
Writing objects: 100% (1/1), 347 bytes | 347.00 KiB/s, done.
Total 1 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
To github.com:helene-nguyen/rust-akash.git
 * [new tag]         v0.2.0 -> v0.2.0

✅ Tag v0.2.0 pushed. Release workflow will start shortly.
   Track it at: https://github.com/helene-nguyen/rust-akash/actions

What happens after the tag is pushed

1. CI Gate verifies the CI workflow already passed on this commit
2. Build compiles release binaries for Linux, macOS, and Windows (5 targets)
3. Docker builds and pushes multi-arch images to Docker Hub and GHCR
4. Publish uploads the crate to crates.io
5. GitHub Release is created with auto-generated notes and attached binaries
6. Post-Release PR is opened to bump the version in Cargo.toml and update CHANGELOG.md

[!IMPORTANT] Make sure CI has passed on the commit before tagging. The release pipeline will fail at the CI Gate step otherwise.

After the release, merge the auto-generated post-release PR to keep main in sync.

For full details, see the Build Release Guide.

License

MIT License - see LICENSE for details.

Author

Helene Nguyen aka Yumi

[!NOTE] This project is a personal side project and not affiliated with any company or organization. I've created this for my own usage and learning, but I hope it can be useful to others as well! ☀️

Why Akash?

Compared to existing tools, Akash offers:

Other similar tools