howdoi - Ask pi for shell commands

README.md

howdoi

Ask pi for shell commands without leaving your terminal.

Requirements

• pi - AI coding agent
• jq (optional, for environment caching)

Installation

curl -sL https://gist.github.com/susliko/6111b411e3a46e15e99ed0cf5e657d14/raw/howdoi -o ~/bin/howdoi
chmod +x ~/bin/howdoi

Usage

howdoi "install gh on manjaro"
howdoi "count scala lines"
howdoi "restart docker on ubuntu"

How it works

1. Caches your environment (distro, package managers) on first run
2. Calls pi with your question + environment context
3. Returns a single command with explanation and alternatives

Output format

sudo pacman -S github-cli

Explanation:
- sudo - run with root privileges
- pacman -S - install from repositories
- github-cli - the package name

Alternatives:
- yay -S github-cli - from AUR
- git clone ... - build from source

Notes

• Wrap your query in quotes if it contains special characters: howdoi "install on manjaro?"
• First run is slightly slower (model cold start)
• Subsequent runs are faster (cached environment)

howdoi

#!/bin/bash
# howdoi - Ask pi for shell commands
# Usage: howdoi "how do i count scala lines"
#        howdoi "install gh on manjaro"
#
# Requires: pi (https://github.com/badlogic/pi)
# Optional: jq for better env caching

CACHE_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/howdoi"
ENV_CACHE="$CACHE_DIR/env.json"

# Detect and cache env info (runs once, reused)
if [ ! -f "$ENV_CACHE" ]; then
  mkdir -p "$CACHE_DIR"
  DISTRO=$(cat /etc/os-release 2>/dev/null | grep PRETTY_NAME | cut -d= -f2 | tr -d '"')
  PKGMGR=""
  for pm in pacman apt dnf brew yum apk; do
    if which $pm &>/dev/null; then
      PKGMGR="${PKGMGR}${PKGMGR:+,}$pm"
    fi
  done
  echo "{\"distro\":\"$DISTRO\",\"pkgmgr\":\"$PKGMGR\"}" > "$ENV_CACHE"
fi

# Read cached info
ENV_INFO=$(cat "$ENV_CACHE" | jq -r ' "Environment: \(.distro). Package managers: \(.pkgmgr)."')

pi -p \
  --system-prompt "Shell expert answering: $ENV_INFO. Format: command on line 1 (NO backticks, NO code blocks), blank line, 'Explanation:' with dash list, 'Alternatives:' with alternatives." \
  --no-builtin-tools \
  "howdoi: $*"

SKILL.md

name	howdoi
description	Answer shell/Bash questions with commands. Use when user asks how to do something in bash, wants a shell one-liner, or asks about Linux commands.

How Do I...

You are a shell expert. The user asks a question about bash commands. Your job is to provide commands and explanations.

Rules

1. Output one primary command that solves the problem
2. Follow with a brief explanation of key parts (1-2 lines each)
3. Provide 2-3 alternatives when multiple approaches exist, noting tradeoffs
4. If you cannot confidently answer, say "I don't know" — do not guess
5. Keep the question in mind and address it directly
6. Do not execute commands — only generate them
7. Use the envDetect tool to understand the user's environment when relevant

Output Format

Start with the command on its own line (no backticks).

Then a blank line, then "Explanation:" with dash list of parts.

Then "Alternatives:" with dash list of alternatives and when to use each.

Examples

Q: count scala lines

find . -name "*.scala" | xargs wc -l | tail -1

Explanation:
- find . -name "*.scala": recursively find all scala files
- xargs wc -l: count lines in each file
- tail -1: show only the grand total

Alternatives:
- find . -name "*.scala" -exec wc -l {} + | tail -1: avoids xargs, slightly slower
- cloc --include-lang=Scala .: requires cloc install, gives per-file breakdown