Bashly

AI-powered cross-environment terminal assistant. Type your request in plain English — Bashly instantly generates the right command for your target environment, lets you securely approve or deny it, and executes it.

Supported Environments

Bashly automatically detects your active operating system, and will even distinguish between PowerShell and CMD when running on Windows!

🚀 Quick Start

1. Installation

The easiest way to install Bashly globally is using uv or pip:

Using uv (Recommended):

uv tool install bashly-cli

Using pip:

pip install bashly-cli

2. Run Bashly

Once installed, you can start Bashly from any directory by simply typing:

bashly

3. First-Time Setup

On your very first run, Bashly will ask you for an OpenRouter API Key.

• Get one for free at openrouter.ai.
• Paste it into the terminal when prompted.
• It will be securely saved to ~/.bashly_config.json automatically.

💡 Usage

Bashly is designed to feel like a continuous chat within your terminal.

Bashly (Linux) > find all log files older than 7 days
Bashly (MicroPy) > blink the onboard LED every 500ms
Bashly (Win/PS) > list all running processes sorted by memory

Built-in Commands

If you type any of these keywords, Bashly performs built-in actions instead of asking the AI:

Interactive Approvals

Bashly will never run a command without your explicit permission.

For local environments (Windows, Linux, macOS):

• y — run the command locally.
• n — skip it.
• c — copy to clipboard without running.
• ? — explain step-by-step what the command actually does.

For cross-compiling/remote targets (MicroPython, Arduino, Termux):

• y / c — copy to clipboard.
• ? — explain.

🛡️ Built-in Security

Bashly parses your generated commands against strict RegEx blocklists to prevent disastrous mistakes:

• 🔴 DANGEROUS — Destructive patterns (rm -rf, format c:, Invoke-Expression, fork bombs). Execution is hard-blocked. You can only copy the command if you deliberately want to run it.
• 🟡 CAUTION — Elevated privilege commands (sudo, chmod, taskkill). Execution is allowed but visually warned.
• 🟢 SAFE — Standard commands without known danger patterns.

🛠️ Developing Locally

If you want to contribute to Bashly or tweak its core prompts:

1. Clone the repository: git clone https://github.com/albinnnnn/bashly && cd bashly
2. Install it in editable mode: uv pip install -e .
3. Tweak the core LLM instructions directly in src/bashly/prompts.py!

bashly/
├── src/bashly/
│   ├── cli.py            Entry point, UI, and approval loop
│   ├── llm.py            OpenRouter API integration
│   ├── executor.py       Subprocess execution and Danger RegEx
│   ├── history.py        Append-only JSON history logging
│   ├── environments.py   System prompt configuration mapping
│   ├── prompts.py        Centralized dashboard for tweaking prompts!
│   └── config.py         Persistent API Key manager
├── pyproject.toml        PyPI package metadata
└── README.md