#command-line #ask #ai #openai #openai-api #assistant #sh

app ask-sh

An AI command line assistant, which is context-aware and multi-turn capable

10 releases

0.4.5 Jun 1, 2024
0.4.4 Feb 13, 2024
0.4.2 Jun 16, 2023
0.3.1 Jun 10, 2023
0.2.2 Jun 6, 2023

#51 in Machine learning

Download history 50/week @ 2024-02-19 16/week @ 2024-02-26 19/week @ 2024-03-11 4/week @ 2024-04-01 171/week @ 2024-05-27 23/week @ 2024-06-03

194 downloads per month

MIT license

527 lines

ask.sh: AI terminal assistant that read from & write to your terminal

  • ask.sh is an AI terminal assistant based on OpenAI APIs such as GPT-3.5/4!
  • What's unique?
    • ask.sh can read from and write to your terminal!
      • No need to copy and paste error texts to a browser window and then bring solutions back to the terminal!
      • It maintains some memory and can handle multi-turn conversations!
  • ask.sh provides ask command to your terminal:


From downloading the Titanic dataset using the curl command to calculate the survival rate for all combinations of sex and room class using the awk command, without leaving the terminal. (Played in 2x. Using gpt-3.5-turbo)


You might be interested in other examples

Quick Start

If you're on Bash:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/hmirin/ask.sh/main/install.sh)"

If you're on Zsh:

zsh -c "$(curl -fsSL https://raw.githubusercontent.com/hmirin/ask.sh/main/install.sh)"

Then, follow the instructions shown by the installer. See Setup for manual installation.

Key Features

Query the AI from Your Terminal

No need to bother with a separate browser. Consult the AI about anything directly from your terminal. Here's an example:

 ask how to unzip tar gz

The AI responds:

❯ ask how to unzip tar gz
To unzip a tar.gz file, you can use the following command in a terminal:

`tar -xzf file.tar.gz`

where "file.tar.gz" is the name of your compressed file. This command will extract the contents of the file into a directory with the same name as the file. If you want to extract the contents into a different directory, you can specify the path with the -C option:

`tar -xzf file.tar.gz -C /path/to/directory`

Once the extraction is complete, you should have access to the uncompressed files in the directory where you extracted them.

Answers are printed incrementally, ensuring you don't have to wait until the complete response is available!

The AI Understands Your Context!

The AI Terminal Assistant can interpret the context of your actions, providing more meaningful suggestions and explanations. Check this out:

You have typed a command and got error.

 rm .git
rm: .git: is a directory

Just ask AI:

❯ ask what does this mean

The AI responds:

❯ ask what does this mean
The message "is a directory" means that you are trying to remove a directory (in this case, the .git directory). In order to remove a directory, you need to use the command "rm -r" instead of just "rm". The "-r" flag tells the "rm" command to remove directories recursively. However, be careful when using this command as it can delete multiple files and directories at once.

Great! Isn't it?

Note: You need to use tmux to use this feature. See Q&A.

Multiturn Conversations with AI in Your Terminal

By understanding the context of your terminal, ask.sh is not just about asking questions and receiving answers; it's about engaging in an insightful dialogue that spans multiple turns. Here's a peek into what that might look like:

❯ git init
Reinitialized existing Git repository in /path/to/ask.sh/.git/

Do you know what exactly happen when you git init again? Let's ask:

❯ ask what does reinitialized mean
"Reinitialized" means that Git has reset the repository's initialization parameters. When you run `git init` in an existing Git repository, Git will re-run the repository's initialization process, but with the existing repository metadata in place. This allows you to reset the repository configuration without losing the existing commit history and other Git metadata.

Hmm, still have question? Ask again:

❯ ask what configuration is reset
When you run init` with the `--reinitialize` or `-o` option, Git will re-run the repository's initialization process, but with the existing repository metadata in place. This allows you to reset the repository configuration without losing the existing commit history and other Git metadata. The specific configuration that is reset depends on what options you passed to `git init`. If you did not pass any options, then Git will reset all initialization parameters to their default values. Is there anything else I can help you with?

Let the AI Write to Your Terminal Directly!

ask command let you type the command AI suggests directly to the shell.

Ask AI to make command like this:

❯ ask allocate 5GB file here

The AI responds with some suggestions of the command:

To allocate a 5GB file here, you can use the `fallocate` command. `fallocate` can be used to allocate space for a file using either the preallocated or the zeroed method.

To allocate space for a 5GB file with the preallocated method, run the following command:

fallocate -l 5G filename

Remember to replace `filename` with the desired name for your file. This will create a file of size 5GB without actually allocating the space until it is actually used.

To allocate space for a 5GB file with the zeroed method, run the following command:

fallocate -l 5G -z filename

This will create a file of size 5GB with all bits set to 0.

If the AI has suggested commands to execute, it will ask if you want to use those commands.

👋 Hey, AI has suggested some commands that can be typed into your terminal.
🔍 Press Enter to view and select the commands, or type any other key to exit:

After you press Enter, an overlay selector (peco) will appear, allowing you to select the most suitable command.

AI suggested commands (Enter to use / Ctrl+C to exit):
fallocate -l 5G filename
fallocate -l 5G -z filename

The selected command is typed into the shell directly. Just hit enter to execute.

❯ fallocate -l 5G filename

You won't struggle text-selection on terminal!

OS / CPU arch / Shell Aware Conversations!

ask command is aware of your shell, OS, and CPU arch. So you can ask shell, OS, and CPU arch specific questions.

❯ ask how to install tmux

The AI responds:

❯ ask how to install tmux
To install tmux on your macOS machine, you can use Homebrew package manager. Here are the steps:

1. Open the terminal.

2. Install Homebrew package manager by running the following command:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

3. Once Homebrew is installed, install tmux:
brew install tmux

4. Wait for the installation to complete.

That's it! Now you can use tmux on your macOS machine.

Perfect! Isn't it? (Some may not like homebrew though...)

Want to see more?

See examples!



  • rust
  • peco: The ask command uses peco to let you select the command to execute from the AI suggested commands.

Optional, but highly recommended if you want ask command to work more nicely:

  • tmux: If you run ask command in tmux, you can send the current terminal to the AI for context-aware input.
  • zsh: If you run ask command in zsh (not Bash), you can let AI write the next command directly to your terminal. No copy-paste is required.


  • If you use Bash or zsh, install script should work.
    • If you find any problem, please file an issue!
  • If you want to install ask.sh manually, follow the steps below:
    1. Install prerequisites
    2. Install ask.sh using cargo: cargo install ask-sh
    3. Set ASK_SH_OPENAI_API_KEY in your shell
      • You can get your API key from OpenAI.
    4. If you don't want to use tmux or send your terminal outputs to the OpenAI server, set ASK_SH_NO_PANE=true
      • If you don't set this variable when you query to ask, ask command will always recommend you to use tmux.
    5. Set up your shell environment
      • Add eval "$(ask-sh --init)" to your rc file (e.g., ~/.bashrc, ~/.zshrc)
      • Do not forget to source your shell config file or restart your shell.
    6. Test the command with ask hey whats up
      • If AI responds with phrases like "As an AI assistant, I can't experience emotions blah blah blah", it means that the setup is done correctly.


  • We will soon release a Chrome Extension that will let you open chat.openai.com with the terminal output.
  • If you want more, please let us know by creating an issue! (But note that I'm a little busy these days.)


This project is licensed under the terms of the MIT license.


  • Use at Your Own Risk: This software is provided "as is" without warranty of any kind, either expressed or implied. The use of this software is at your own discretion and risk, and you will be solely responsible for any damage or loss that results from its use.

  • Data Transmission to OpenAI: By using this software, the text you input, as well as certain terminal information, will be sent to OpenAI as part of the software's operation.

  • Potential for Unintended Data Transmission: Please be aware that due to the possibility of software bugs or unexpected behaviour, unintended data may be sent to OpenAI or whatsoever. While we strive to ensure the security and privacy of your data, these risks can never be completely eliminated.


Why Another Terminal AI Assistant?

Sure, there are plenty of great projects for terminal AI assistants already out there. But, in my experience, none of these tools completely meet the criteria I consider essential:

  • Simple API: Who wants to remember complex commands and options? Isn't that why we need AI in the first place?
  • Multi-turn capability: Most tools cater to single-turn queries because they lack memory, an important feature in my book.
  • Terminal Reading: Copying and pasting from terminal? No, thank you!
  • Direct Command Execution on zsh/bash: Running commands in a wrapped environment or REPLs isn't my cup of tea.

This is why I created ask.sh.

Similar projects:

  • Github Copilot for CLI
    • It's fantastic, but it's primarily focused on a single-turn conversation for command generation.
  • ShellGPT
    • A pioneering work with great features! However, I find the API overly complex and I'm not a fan of the way it runs commands in REPL.

How ask.sh send the current output of terminal?

  • ask.sh use tmux capture-pane -p to get the current terminal status. Therefore, if you run ask in tmux pane, text on the pane will be sent to the OpenAI.
  • This will give AI the context of your request and improve the result.
  • If you don't want to use this feature, set ASK_SH_NO_PANE=true in your shell.

Privacy concerns?

  • As of 5th July 2023, OpenAI states that they will not use data submitted by customers via their API to train or improve their models, unless you explicitly opt-in to do so.
  • And of course, you can use ask.sh without sending the current terminal output to the OpenAI server. Just set ASK_SH_NO_PANE=true in your shell.

Can I use GPT-4?

  • Yes! You can use GPT-4 by setting the environmanet_variable ASK_SH_OPENAI_MODEL=gpt-4.
    • This environment variable is just passed to OpenAI API. So you can use whatever model OpenAI serves.
  • Currently, default model is set to gpt-3.5-turbo.

Why Rust?

  • It's just because shell tools should have less dependencies!
    • To my knowledge, there's no standard way in Python to make a command available to everywhere.


  • Of course, we welcome contributions! Please feel free to open an issue or submit a pull request.


A special thanks to @xarsh for their effort in debugging, testing, and providing valuable feedback, contributing significantly to the refinement of this project. Our sincere gratitude to @matsurih for their outstanding contribution to our work, marking the project's first-ever PR.


~381K SLoC