Shellsia (sia)

Created by Sukhwinder-i0

Convert plain English into shell commands — powered by AI.

Installation

Install the package globally via npm:

npm install -g shellsia

After installing, run the interactive setup to configure your API key:

sia --setup

Quick Start

It's extremely easy to use. Just type sia followed by what you want to do in plain English! Quotes are optional

$ sia find all files larger than 100MB

  ╭─ Command ──────────────────────────────╮
  │  find . -size +100M                    │
  ╰────────────────────────────────────────╯

  Explains  Finds all files larger than 100MB in the current directory

  Alternatives:
    • find . -size +100M -type f
    • du -ah . | sort -rh | head -20

  Run it? › [y] run   [n] cancel   [c] copy

(You can also use quotes if you prefer: sia "find all files larger than 100MB")

Setup

You'll be prompted to:

1. Choose your LLM provider (Groq or OpenAI)
2. Enter your API key
3. Set shell preferences

Getting a Free Groq API Key

1. Go to console.groq.com
2. Sign up for a free account
3. Navigate to API Keys in the sidebar
4. Click Create API Key
5. Copy the key and paste it during sia --setup

Groq provides free access to Llama 3.3 70B — it's fast and works great for command generation.

Switching to OpenAI

If you prefer to use OpenAI:

sia --setup
# Select "OpenAI (gpt-4o-mini)" as your provider
# Enter your OpenAI API key

Usage Examples

# Find large files
sia find all files larger than 100MB

# Kill a process by port
sia kill the process running on port 3000

# Compress a folder
sia compress this folder into a zip

# Disk usage
sia show disk usage sorted by size

# Git operations
sia undo the last commit but keep the changes

How It Works

1. You type a command description in plain English
2. Shellsia detects your OS, shell, and working directory
3. It sends your request to an LLM (Groq or OpenAI) with full context
4. The LLM returns a precise shell command with an explanation
5. You choose to run, cancel, or copy the command

Safety Features

• Dangerous command warnings: Commands that delete or modify files are flagged with a red warning
• Double confirmation for rm -rf: Extra safety for destructive deletions
• Sudo detection: Yellow warning when commands require elevated privileges
• No auto-sudo: Commands never include sudo unless you explicitly ask

Configuration

Config is stored at ~/.shellsia/config.json:

{
  "groqApiKey": "gsk_...",
  "openaiApiKey": "",
  "defaultProvider": "groq",
  "shell": "auto",
  "confirmBeforeRun": true
}

View your current config:

sia --config

Commands

| Command | Description | |---------|-------------| | sia <your request> | Convert English to a shell command | | sia --setup | Configure API keys and preferences | | sia --config | Show current configuration | | sia --help | Show help information | | sia --version | Show version number |

Tech Stack

• TypeScript + Node.js 18+
• Groq API (primary, free) — Llama 3.3 70B
• OpenAI API (fallback) — GPT-4o-mini
• Commander — CLI argument parsing
• Inquirer — Interactive prompts
• Chalk — Colored terminal output
• Ora — Loading spinners
• Execa — Safe command execution
• Clipboardy — Clipboard support

Contributing

We welcome open source contributions! Whether it's reporting a bug, suggesting a new feature, or submitting a pull request, your input is highly valued. Feel free to fork the repository, make your changes, and open a PR. Let's make shellsia even better together!

If you'd like to run it locally for development:

git clone https://github.com/Sukhwinder-i0/shellsia.git
cd shellsia
npm install
npm run build
npm link

License

MIT