abc (AI bash/zsh/tcsh Command)

Synopsis

abc [OPTION]... DESCRIPTION...

Description

abc (AI Bash Command) lets you type an English description of a task and get an LLM generated command on your next shell prompt, ready to edit and execute. For example:

$ abc list files one per line, sorting lines from short to long
# (next command is generated by abc and placed on the shell prompt)
$ ls -1 | awk '{ print length, $0 }' | sort -n | cut -d" " -f2-

abc can help you quickly generate commands without memorizing syntax, and can assist in learning new command-line operations.

Features

• Translates natural language descriptions into bash, zsh, or tcsh commands
• Interactive mode allows editing of generated commands before execution
• Configurable through a simple INI config file
• Supports multiple configuration profiles
• Provides verbose and debug output options
• Supports bash, zsh, and tcsh shells
• Evaluates and warns about potentially dangerous commands

Installation

For detailed installation instructions, please refer to INSTALL.md.

Usage

After installation and setup, you can use abc in two ways:

1. Interactive mode (recommended):

   Simply type abc followed by your description of the task you want to accomplish. The generated command will be presented in an editable prompt, allowing you to review and modify it before execution.

   Example:

   $ abc edit my last git commit message
   # (next command is generated by abc)
   $ git commit --amend
   

   In this example, you'd see git commit --amend in an editable prompt. You can modify it if needed, then press Enter to execute.

2. Direct output mode:

   If you prefer to just see the generated command without executing it, use abc_generate. This will output the command without running it or presenting an interactive prompt.

   Example:

   $ abc_generate "remove trailing whitespace from myprog.py"
   sed -i 's/[[:space:]]*$//' myprog.py
   

Remember to always review the generated commands before executing them, especially for operations that could potentially modify your system or data.

Options

• -c, --config CONFIGFILE: Path to the primary configuration file. (Defaults to $ABC_CONFIG or "$HOME/.abc.conf")
• --verbose: Provides detailed information about the program's execution.
• --debug: Provides debug information. Only use this when troubleshooting issues.
• --version: Displays the program version and exits.
• -h, --help: Shows help message and exits.
• --shell: Specify the shell to generate commands for (choices: bash, zsh, tcsh; default: bash)

Environment

• ABC_CONFIG: Specifies the path to the configuration file. If not set, the script will look for a file at '~/.abc.conf'.

Configuration

The program will attempt to read the config file from the first of these values provided:

1. --config command line option
2. $ABC_CONFIG environment variable
3. $HOME/.abc.conf

Examples

Tell abc what you want to do:

$ abc list files one per line, sorting lines from short to long
# (next command is generated by abc)
$ ls -1 | awk '{ print length, $0 }' | sort -n | cut -d" " -f2-

Generate a command to figure out the correct date format specifier:

$ abc current date/time to minute in ISO 8601, but with a space
# (next command is generated by abc)
$ date '+%Y-%m-%d %H:%M'

It detects the current shell and generates appropriate commands:

# bash
$ abc create an array of files in the current directory
# (next command is generated by abc)
$ files=($(ls))

# zsh
% abc create an array of files in the current directory
# (next command is generated by abc)
% files=(*)

# tcsh
> abc create an array of files in the current directory
# (next command is generated by abc)
> set files = (`ls`)

The LLM will make lots of assumptions, often correct:

$ abc change the mod time of bashrc to yesterday at noon
# (next command is generated by abc)
$ touch -t $(date -d "yesterday 12:00" +%Y%m%d1200) ~/.bashrc

Quotes can be used to protect special characters:

$ full=/some/path/to/myfile.txt
$ abc 'strip the directory and extension from $full and store in $name'
# (next command is generated by abc)
$ name=$(basename "${full%.*}")
$ echo $name
myfile

It is happy to generate sudo commands, so be careful:

$ abc reboot if needed
# (next command is generated by abc)
$ [ -f /var/run/reboot-required ] && sudo reboot

More complicated examples might take some trial and error to get the wording right:

$ abc find duplicate files. separate groups of file names by blank line
# (next command is generated by abc)
$ find . -type f -print0 | xargs -0 md5sum | sort | uniq -w32 --all-repeated=separate | cut -c 35-

It's very handy for aws-cli commands:

$ abc List my EC2 instances: id, Name, type, start time
# (next command is generated by abc)
$ aws ec2 describe-instances --query 'Reservations[*].Instances[*].[InstanceId,Tags[?Key==`Name`].Value | [0],InstanceType,LaunchTime]' --output table

It is a git expert:

$ abc 'change git user email for most recent commit to $email'
# (next command is generated by abc)
$ git commit --amend --author="$(git config user.name) <$email>" --no-edit

It knows things about things:

$ abc What is my public IP address according to AWS, secure
# (next command is generated by abc)
$ curl -s https://checkip.amazonaws.com

It can hallucinate; this was generated by the Anthropic Claude 3.5 Sonnet LLM, not OpenAI ChatGPT:

$ abc echo the LLM model name and version
# (next command is generated by abc)
$ echo "ChatGPT 3.5"

I keep using abc every time I turn around:

$ abc 'count number of times each element shows in $PATH'
# (next command is generated by abc)
$ echo $PATH | tr ':' '\n' | sort | uniq -c | sort -rn
...

$ abc 'remove duplicate elements from $PATH, keeping the order, then save in PATH'
# (next command is generated by abc)
$ PATH=$(echo $PATH | tr ':' '\n' | awk '!seen[$0]++' | tr '\n' ':' | sed 's/:$//')

Exit Status

• 0: Program executed successfully
• 1: An error occurred during execution

Danger Level Evaluation

abc includes a feature to evaluate the potential danger level of generated commands:

• Level 0: Read-only, informational commands.
• Level 1: Commands that modify the system in common ways or generate standard side effects.
• Level 2: Commands with potential for significant data loss or large side effects.

For commands with a danger level of 2 or higher, abc will:

1. Display a warning message on stderr.
2. Prefix the command with #DANGEROUS#, requiring you to edit the command before execution.

Example:

$ abc delete all files under the current directory
Warning: This command is potentially dangerous. This command deletes all files and directories in the current directory without confirmation, potentially causing irreversible data loss if executed in the wrong location.
$ #DANGEROUS# rm -rf *

Always review these warnings and dangerous commands carefully before execution.

CAVEATS

• LLMs do not always generate correct or expected output. Before running the commands generated by this tool, they should always be reviewed for appropriateness and for dangerous or unintended effects.

• The danger level evaluation is based on the LLM's assessment and may not catch all potentially dangerous situations. Always use your own judgment when executing commands.

• LLMs do not always generate the same output every time. If you run the same command at different times, you may get different results. Always review the output.

• There is a cost to using commercial LLM APIs. Review your spending regularly, and do not use this tool in an environment where it could be run automatically or excessively without human monitoring.

• This tool works in one environment on one Ubuntu release for one person. It may not work for you.

• Though the prompt command editing looks and acts a bit like the normal shell prompt, it is not completely compatible in every way in all shells for all user environments.

• The danger level evaluation is based on the LLM's assessment and may not catch all potentially dangerous situations. Always use your own judgment when executing commands.

BUGS

• The command abc --help does not currently work when using the interactive bash function.

TODO

• Support MacOS
• Support multiple LLM models
• Support multiple LLM providers
• Support custom prompt context
• Use request history and generated commands as context for conversation

Contributing

We want to keep abc tightly focused, but will review feedback in GitHub.

Issue Reports

• Before submitting a new issue, search existing issues to avoid duplicates
• Provide clear, detailed descriptions of the problem
• For bugs, include:
  • Steps to reproduce
  • Expected vs actual behavior
  • Your environment (OS, shell, abc version)
  • Any relevant configuration settings; do not include API keys!
• For feature requests, explain the use case and benefits

Pull Requests

• Before spending time on a PR that might not be accepted, submit an issue for discussion
• Keep changes small and focused - one feature or fix per PR
• Follow the existing code style and conventions
• Update documentation as needed
• Provide a clear description of the changes and their purpose

License

This project is licensed under the Apache 2 License - see the LICENSE file for details.

Credits

Written by Claude 3.5 Sonnet
Prompt crafting by Eric Hammond

Version

Current version: 2024.12.15