Shelp

Shelp is a small command-line utility that uses an OpenAI API LLM to generate bash-compatible shell commands from a plain-English (or Portuguese) task description. It can optionally request a simple human-friendly explanation of the generated command(s). The program calls a helper API implemented in chatgpt_c_client and uses libcurl for HTTP.

Features

• Convert natural-language tasks into bash-compatible commands.
• Optionally request a readable, step-by-step explanation of the generated command(s).
• Minimal interactive command-line flow with a clear safety disclaimer.
• Default target: macOS / zsh (configurable via a compile-time macro).

Requirements

• libcurl development headers (for linking).
• An OpenAI API key set in the environment variable: OPENAI_API_KEY.
• C compiler (gcc/clang).

Build

To compile:

gcc -Wall -Werror -Wextra shelp.c chatgpt.c cJSON.c -o shelp -lcurl

If chatgpt.c is compiled separately into an object or library, link accordingly.

Usage

1. Export your OpenAI API key:

export OPENAI_API_KEY="sk-..."

2. Run shelp:

./shelp

3. Follow the prompts:

• Enter a task (English or Portuguese). Example: "List all .log files modified more than 7 days ago and delete them interactively"
• Shelp will output suggested command(s).
• You will be asked if you want an explanation (y/n). If yes, Shelp will ask the model to explain the commands in simple terms.

Example session (illustrative):

Enter your task: remove all .tmp files created more than 30 days ago
=== Suggested Command(s) ====
find . -type f -name '*.tmp' -mtime +30 -print -exec rm -i {} \\;

Do you need explanation? (y/n)
y

=== Explanation ====
- find . -type f -name '*.tmp' -mtime +30:
  Finds regular files ending with .tmp older than 30 days.
- -print:
  Prints the matched filenames.
- -exec rm -i {} \\;
  Prompts before deleting each file.

Adding Shelp as an alias

To run shelp from any directory, you can add an alias to your shell's configuration file (~/.zshrc for Zsh or ~/.bashrc for Bash). This tells your shell where to find the shelp executable.

1. First, make sure the shelp binary is executable:

   chmod +x ./shelp

2. Then, add the alias to your shell's configuration file. Replace /path/to/your/shelp with the actual absolute path to where you compiled shelp. For Zsh (macOS default):

echo 'alias shelp="/path/to/your/shelp"' >> ~/.zshrc

For Bash:

echo 'alias shelp="/path/to/your/shelp"' >> ~/.bashrc

3. Finally, reload your shell's configuration to apply the changes:

source ~/.zshrc   # For Zsh
source ~/.bashrc   # For Bash

How it works (brief)

• The program builds a prompt using a template and the macro SHELSYSTEM (default "zsh/macOs") and calls chatgpt_query(api_key, prompt).
• The model is instructed to output only the shell commands (or a refusal string).
• If the returned string begins with "Sorry", the program stops without an explanation.
• If the user requests an explanation, a second prompt asking for a structured explanation is sent.

Configuration

• Change the target shell/OS hint by editing:

#define SHELSYSTEM "zsh/macOs"

to another value (e.g., "bash/linux") before compiling, if you want the prompt to include a different target.

• Prompt templates and buffer sizes live in the source and can be adjusted (see BUFFER_SIZE).

Security & Disclaimer

• This program uses generative AI and can produce incorrect or harmful commands. Always review commands before running them.
• The program will refuse to generate or explain commands if the model responds that the task is inappropriate; it outputs:
  • Sorry, cannot create commands for this task. for generation refusals, or
  • Sorry, I cannot provide an explanation for this command. for explanation refusals.
• You are responsible for any damage caused by running generated commands.

Troubleshooting

• If you get "Error: The environment variable OPENAI_API_KEY is not set.", make sure you exported the key in the same shell where you run the program.

Development / Contributing

• Fork the repo, fix issues, or improve prompt templates and shell detection.
• Add safer defaults / confirmation prompts for destructive commands.
• Consider adding a dry-run mode or syntax-only validation.
• Test and validate for Linux / Windows

License

This project is licensed under the MIT License. See the LICENSE file for details.