shellChatGPT

Shell wrapper for OpenAI's ChatGPT, STT (Whisper), and TTS. Features LocalAI, Ollama, Gemini, Mistral, and more service providers.

Chat completions with streaming by defaults.

Index

- 17.9.1 [xAI Live Search](#xai-live-search)
- 17.9.2 [xAI Image Generation](#xai-image-generation)

🚀 Features

• Native chat completions, plain text completions, and responses api (text).
• Vision, reasoning and audio models
• Voice-in (Whisper) plus voice out (TTS) chatting mode (options -bcd -zw)
• Text editor interface, Bash readline, and multiline/cat modes
• Markdown rendering support in response
• Easily regenerate responses
• Manage sessions, print out previous sessions
• Set Custom Instruction prompts
• Integration with various service providers and custom BaseUrl.
• Support for awesome-chatgpt-prompts & the Chinese variant
• Stdin and text file input support
• Should™ work on Linux, FreeBSD, MacOS, and Termux
• Fast shell code for a responsive experience! ⚡️

Project Status

Development is ongoing, with an emphasis on improving stability and addressing bugs, rather than new features in 2026. It is considered mostly feature‑complete for my personal use-cases.

Check the Troubleshoot section for information on how to to work with newer models and different API providers.

Refer to the Roadmap section and Limitations section for the original objectives of our project.

This project is now in maintenance mode. It is considered feature‑complete for my routine and personal use-cases.

• Bug Fixes: Only critical bugs affecting core functionality will be addressed.
• No New Features: Development of new features has ceased. This includes (but is not limited to) reasoning modes (--think, --effort), auto‑detection of model capabilities (--vision, --audio).
• Defaults: No updates to default model names for each service provider, new TTS voice name completions or checks.
• Documentation: We plan to leave strong documentation of the software. -->

✨ Getting Started

✔️ Required Packages

• Bash and readline
• cURL and JQ

Optional Packages

Packages required for specific features.

💾 Installation

A. Download the stand-alone chatgpt.sh script and make it executable:

wget https://gitlab.com/fenixdragao/shellchatgpt/-/raw/main/chatgpt.sh
chmod +x ./chatgpt.sh

B. Or clone this repo:

git clone https://gitlab.com/fenixdragao/shellchatgpt.git

C. Optionally, download and set the configuration file ~/.chatgpt.conf:

#save configuration template:
chatgpt.sh -FF  >> ~/.chatgpt.conf
#edit:
chatgpt.sh -F
Or
nano ~/.chatgpt.conf

Script Operating Modes

The chatgpt.sh script can be run in various modes by setting command-line options at invocation. These are summarised below.

🔥 Usage Examples 🔥

💬 Native Chat Completions

With command line option -c, some properties are set automatically to create a chat bot. Start a new session in chat mode, and set a different temperature:

chatgpt.sh -c -t0.7

Change the maximum response length to 4k tokens:

chatgpt.sh -c -4000
chatgpt.sh -c -M 4000

And change model token capacity to 200k tokens:

chatgpt.sh -c -N 200000

Create Marv, the sarcastic bot:

chatgpt.sh -512 -c --frequency-penalty=0.7 --temp=0.8 --top_p=0.4 --restart-seq='\nYou: ' --start-seq='\nMarv:' --stop='You:' --stop='Marv:' -S'Marv is a factual chatbot that reluctantly answers questions with sarcastic responses.'

Tip: Easily set runtime options with chat command !conf!

Load the custom-made unix instruction file ("unix.pr") for a new session. The command line syntaxes below are all aliases:

chatgpt.sh -c .unix
chatgpt.sh -c.unix
chatgpt.sh -c -.unix
chatgpt.sh -c -S .unix

NOTE: In this case, the custom prompt will be loaded, and the history will be recorded in the corresponding "unix.tsv" file at the cache directory.

To change the history file in which the session will be recorded, set the first positional argument in the command line with the operator forward slash "/" and the name of the history file (this executes the /session command).

chatgpt.sh -c /test
chatgpt.sh -c /stest
chatgpt.sh -c "/session test"

There is a shortcut to load an older session from the default (or current) history file. This opens a basic interactive interface.

chatgpt.sh -c .

chatgpt.sh -c /.

chatgpt.sh -c /fork.

chatgpt.sh -c "/fork current"

-->

Technically, this copies an old session from the target history file to the tail of it, so we can resume the session.

In order to grep for sessions with a regex, it is easier to enter chat mode and then type in the chat command /grep [regex].

Print out last session, optionally set the history name:

chatgpt.sh -P
chatgpt.sh -P /test

Reasoning and Thinking Models

For Anthropic's claude-3-7-sonnet hybrid model thinking activation, the user must specify either --think [NUM] (or --effort [NUM]) command line option. To activate thinking during chat, use either !think, /think, or /effort commands.

Some of our server integrations will not make a distinct separation between reasoning and actual answers, which is unfortunate because it becomes hard to know what is thinking and what is the actual answer as they will be printed out without any visible separation!

This is mostly due to a limitation in how we use JQ to process the JSON response from the APIs in the fastest way possible.

Vision and Multimodal Models

To send an image / url to vision models, start the script interactively and then either set the image with the !img.

Alternatively, set the image paths / URLs at the end of the prompt:

chatgpt.sh -c -m gpt-4-vision-preview

[...]
Q: !img  https://i.imgur.com/wpXKyRo.jpeg

Q: What can you see?  https://i.imgur.com/wpXKyRo.jpeg

TIP: Run command !info to check configuration!

DEBUG: Set option -V to see the raw JSON request body.

Text, PDF, Doc, and URL Dumps

To make an easy workflow, the user may add a filepath or text URL at the end of the prompt. The file is then read and the text content appended to the user prompt. This is a basic text feature that works with any model.

chatgpt.sh -c
[...]
Q: What is this page: https://example.com
Q: Help me study this paper. ~/Downloads/Prigogine\ Perspective\ on\ Nature.pdf

In the second example above, the PDF will be dumped as text.

For PDF text dump support, poppler/abiword is required. For doc and odt files, LibreOffice is required. See the Optional Packages section.

Also note that file paths containing white spaces must be backslash-escaped, or the filepath must be preceded by a pipe | character.

My text prompt. | path/to the file.jpg

Multiple images and audio files may be appended the prompt in this way!

File Picker and Shell Dump

The /pick command opens a file picker (command-line or GUI file manager). The selected file's path is then appended to the current prompt.

The /pick and /sh commands may be run when typed at the end of the current prompt, such as ---[PROMPT] /pick,

When the /sh command is run at the end of the prompt, a new shell instance to execute commands interactively is opened. The command dumps are appended to the current prompt.

File paths that contain white spaces need backslash-escaping in some functions.

Voice In and Out + Chat Completions

🗣️ Chat completion with speech in and out (STT plus TTS):

chatgpt.sh -cwz       #native chat completions
chatgpt.sh -cdwz      #text chat completions

Chat in Portuguese with voice-in and set onyx as the TTS voice-out:

chatgpt.sh -cwz -- pt -- onyx

Chat mode provides a conversational experience, prompting the user to confirm each step.

For a more automated execution, set option -v, or -vv for hands-free experience (live chat with silence detection), such as:

chatgpt.sh -c -w -z -v
chatgpt.sh -c -w -z -vv

Audio Models

Audio models, such as gpt-4o-audio, deal with audio input and output directly, thus reducing latency in a conversation turn.

To activate the microphone recording function of the script, set command line option -w.

Otherwise, the audio model accepts any compatible audio file (such as mp3, wav, and opus). These files can be added to be loaded at the very end of the user prompt or added with chat command /audio path/to/file.mp3.

To activate the audio output mode of an audio model, do set command line option -z to make sure the speech synthesis function is enabled!

chatgpt.sh -c -w -z -vv -m "gpt-4o-audio-preview"

Mind that this does not implement the realtime models.

Chat Mode of Text Completions

When text completions is set for chatting with options -cd or --text-chat, some properties are configured automatically to instruct the bot.

chatgpt.sh -cd "Hello there! What is your name?"

📜 Text Completions

This is the pure text completions endpoint. It is typically used to complete input text, such as for completing part of an essay.

To complete text from the command line input prompt, either set option -d or set a text completion model name.

chatgpt.sh -128 -m gpt-3.5-turbo-instruct "Hello there! Your name is"
chatgpt.sh -128 -d "The journalist loo"

The above examples also set maximum response value to 128 tokens.

Enter single-turn interactive mode:

chatgpt.sh -d

NOTE: For multi-turn mode with history support, set option -dd.

A strong Instruction prompt may be needed for the language model to do what is required.

Set an instruction prompt for better results:

chatgpt.sh -d -S 'The following is a newspaper article.' "It all starts when FBI agents arrived at the governor house and"
chatgpt.sh -d -S'You are an AI assistant.'  "The list below contain the 10 biggest cities in the w"

Insert Mode of Text Completions

Set option -q (or -qq for multiturn) to enable insert mode and add the string [insert] where the model should insert text:

chatgpt.sh -q 'It was raining when [insert] tomorrow.'

NOTE: This example works with no instruction prompt! An instruction prompt in this mode may interfere with insert completions.

NOTE: Insert mode works with model instruct models.

Mistral AI has a nice FIM (fill-in-the-middle) endpoint that works with code models and is really good!

Responses API

Responses API is a superset of Chat Completions API. Set command line option -b (with -c), or set options -bb for multiturn.

To activate it during multiturn chat, set /responses [model], where model is the name of a model which works with the Responses API. Aliased to /resp [model] and -b [model]. This can be toggled.

Limited support.

Choose an edit model or set option -e to use this endpoint. Two prompts are accepted, an instruction prompt and an input prompt (optional):

chatgpt.sh -e "Fix spelling mistakes" "This promptr has spilling mistakes."

chatgpt.sh -e "Shell code to move files to trash bin." ""

Edits works great with INSTRUCTION and an empty prompt (e.g. to create some code based on instruction only).

Use gpt-4+ models and the right instructions.

The last working shell script version that works with this endpoint is chatgpt.sh v23.16. -->

Markdown

To enable markdown rendering of responses, set command line option --markdown, or run /md in chat mode. To render last response in markdown once, run //md.

The markdown option uses bat as it has line buffering on by default, however other software is supported. Set the software of choice such as --markdown=glow or /md mdless.

Type in any of the following markdown software as argument to the option: bat, pygmentize, glow, mdcat, or mdless.

⚙️ Prompts

Unless the chat options -c, -cd, or -bc are set, no instruction is given to the language model. On chat mode, if no instruction is set, minimal instruction is given, and some options set, such as increasing temperature and presence penalty, in order to un-lobotomise the bot.

Prompt engineering is an art on itself. Study carefully how to craft the best prompts to get the most out of text, code and chat completions models.

The model steering and capabilities require prompt engineering to even know that it should answer the questions.

Instruction Prompt

When the script is run in chat mode, the instruction is set automatically if none explicitly set by the user on invocation.

The chat instruction will be updated according to the user locale after reading envar $LANG.

Translations are available for the languages: en, pt, es, it, fr, de, ru, ja, zh, zh_TW, and hi.

To run the script with the Hindi prompt, for example, the user may execute:

chatgpt.sh -c .hi
LANG=hi_IN.UTF-8 chatgpt.sh -c

Note: custom prompts with colliding names such as "hi" have precedence over this feature.

⌨️ Custom Prompts

Set a one-shot instruction prompt with option -S:

chatgpt.sh -c -S 'You are a PhD psychologist student.' 
chatgpt.sh -cS'You are a professional software programmer.'

To create or load a prompt template file, set the first positional argument as .prompt_name or ,prompt_name. In the second case, load the prompt and single-shot edit it.

chatgpt.sh -c .psychologist 
chatgpt.sh -c ,software_programmer

Alternatively, set option -S with the operator and the name of the prompt as an argument:

chatgpt.sh -c -S .psychologist 
chatgpt.sh -c -S,software_programmer

This will load the custom prompt or create it if it does not yet exist. In the second example, single-shot editing will be available after loading prompt software_programmer.

Please note and make sure to backup your important custom prompts! They are located at "~/.cache/chatgptsh/" with the extension ".pr".

🔌 Awesome Prompts

Set a prompt from awesome-chatgpt-prompts or awesome-chatgpt-prompts-zh, (use with davinci and gpt-3.5+ models):

chatgpt.sh -c -S /linux_terminal
chatgpt.sh -c -S /Relationship_Coach
chatgpt.sh -c -S '%担任雅思写作考官'

Shell Completion

This project includes shell completions to enhance the user command-line experience.

Bash

Install following one of the methods below.

System-wide

sudo cp comp/bash/chatgpt.sh /usr/share/bash-completion/completions/

User-specific

mkdir -p ~/.local/share/bash-completion/completions/
cp comp/bash/chatgpt.sh ~/.local/share/bash-completion/completions/

Visit the bash-completion repository.

Zsh

Install at the system location

sudo cp comp/zsh/_chatgpt.sh /usr/share/zsh/site-functions/

User-specific location

To set user-specific completion, make sure to place the completion script under a directory in the $fpath array.

The user may create the ~/.zfunc/ directory, for example, and add the following lines to her ~/.zshrc:

[[ -d ~/.zfunc ]] && fpath=(~/.zfunc $fpath)
autoload -Uz compinit
compinit

Make sure compinit is run after setting $fpath!

Visit the zsh-completion repository.

Shell Troubleshoot

Bash and Zsh completions should be active in new terminal sessions. If not, ensure your ~/.bashrc and ~/.zshrc source the completion files correctly.

Currently, the scripts defaults to the gpt-image model. The user must verify his OpenAI organisation before before granted access to this model! Otherwise, please specify positional arguments -i -m dall-e-3 or -i -m dall-e-2 to select other models for image endpoints.

Generate image according to prompt:

chatgpt.sh -i "Dark tower in the middle of a field of red roses."

chatgpt.sh -i "512x512" "A tower."

This script also supports xAI grok-2-image-1212 image model:

chatgpt.sh --xai -i -m grok-2-image-1212 "A black tower surrounded by red roses."

Image Variations

Generate image variation:

chatgpt.sh -i path/to/image.png

Image Edits

chatgpt.sh -i path/to/image.png path/to/mask.png "A pink flamingo."

Outpaint - Canvas Extension

In this example, a mask is made from the white colour.

-->

🔊 Speech Transcriptions / Translations

Generate transcription from audio file speech. A prompt to guide the model's style is optional. The prompt should match the speech language:

chatgpt.sh -w path/to/audio.mp3
chatgpt.sh -w path/to/audio.mp3 "en" "This is a poem about X."

1. Generate transcription from voice recording, set Portuguese as the language to transcribe to:

chatgpt.sh -w pt

This also works to transcribe from one language to another.

2. Transcribe any language speech input to Japanese (prompt should be in the same language as the input audio language, preferably):

chatgpt.sh -w ja "A job interview is currently being done."

3.1 Translate English speech input to Japanese, and generate speech output from the text response.

chatgpt.sh -wz ja "Getting directions to famous places in the city."

3.2 Also doing it conversely, this gives an opportunity to (manual) conversation turns of two speakers of different languages. Below, a Japanese speaker can translate its voice and generate audio in the target language.

chatgpt.sh -wz en "Providing directions to famous places in the city."

4. Translate speech from any language to English:

chatgpt.sh -W [speech_file]
chatgpt.sh -W

To retry with the last microphone recording saved in the cache, set speech_file as last or retry.

NOTE: Generate phrasal-level timestamps double setting option -ww or option -WW. For word-level timestamps, set option -www or -WWW.

Codex models are discontinued. Use models davinci or gpt-3.5+.

Start with a commented out code or instruction for the model, or ask it in comments to optimise the following code, for example. -->

Service Providers

Local LLM Software

• Ollama
• LocalAI

Free service providers

• GitHub Models
• Gemini Google Vertex
• Groq

Paid service providers

• OpenAI
• Mistral AI
• Anthropic
• Grok xAI
• DeepSeek
• OpenRouter API

Tip: Other providers may be set up manually.

LocalAI

LocalAI Server

Make sure you have got mudler's LocalAI, server set up and running.

The server can be run as a docker container or a binary can be downloaded.

Check LocalAI tutorials Container Images, and Run Models Manually for an idea on how to download and install a model and set it up.

LocalAI Tips

1. Download a binary of localai for your system from Mudler's release GitHub repo.

2. Run localai run --help to check command line options and environment variables.

3. Set up $GALLERIES before starting up the server:

export GALLERIES='[{"name":"localai", "url":"github:mudler/localai/gallery/index.yaml"}]'  #default
export GALLERIES='[{"name":"model-gallery", "url":"github:go-skynet/model-gallery/index.yaml"}]'
export GALLERIES='[{"name":"huggingface", "url": "github:go-skynet/model-gallery/huggingface.yaml"}]'

4. Install the model named phi-2-chat from a yaml file manually, while the server is running:

curl -L http://localhost:8080/models/apply -H "Content-Type: application/json" -d '{ "config_url": "https://raw.githubusercontent.com/mudler/LocalAI/master/embedded/models/phi-2-chat.yaml" }'

Running the shell wrapper

Finally, when running chatgpt.sh, set the model name:

chatgpt.sh --localai -c -m luna-ai-llama2

Setting some stop sequences may be needed to prevent the model from generating text past context:

chatgpt.sh --localai -c -m luna-ai-llama2  -s'### User:'  -s'### Response:'

Optionally set restart and start sequences for text completions endpoint (option -cd), such as -s'\n### User: ' -s'\n### Response:' (do mind setting newlines \n and whitespaces correctly).

And that's it!

Installing Models

Model names may be printed with chatgpt.sh -l. A model may be supplied as argument, so that only that model details are shown.

NOTE: Model management (downloading and setting up) must follow the LocalAI and Ollama projects guidelines and methods.

BASE URL Configuration

If the service provider Base URL is different from defaults, these tips may help make the script work with your API.

The environment variable $OPENAI_BASE_URL is read at invocation.

export OPENAI_BASE_URL="http://127.0.0.1:8080/v1"
chatgpt.sh -cd -m luna-ai-llama2

To set it a in a more permanent fashion, edit the script configuration file .chatgpt.conf.

Use vim:

vim ~/.chatgpt.conf

Or edit the configuration with a command line option.

chatgpt.sh -F

And set the following variable:

# ~/.chatgpt.conf
OPENAI_BASE_URL="http://127.0.0.1:8080/v1"

OpenAI Web Search

Use the in-house solution with chat command "/g [prompt]" or "//g [prompt]" to ground the prompt, or select models with search in the name, such as "gpt-4o-search-preview".

Running "//g [prompt]" will always use the in-house solution instead of any service provider specific web search tool.

export BLOCK_USR='"tools": [{
  "type": "web_search_preview",
  "search_context_size": "medium"
}]'

chatgpt.sh -cc -m gpt-4.1-2025-04-14

Check more search parameters at the OpenAI API documentation. https://platform.openai.com/docs/guides/tools-web-search?api-mode=chat. -->

Ollama

Visit Ollama repository, and follow the instructions to install, download models, and set up the server.

After having Ollama server running, set option -O (--ollama), and the name of the model in chatgpt.sh:

chatgpt.sh -c -O -m llama2

If Ollama server URL is not the default http://localhost:11434, edit chatgpt.sh configuration file, and set the following variable:

# ~/.chatgpt.conf
OLLAMA_BASE_URL="http://192.168.0.3:11434"

Google AI

Get a free API key for Google to be able to use Gemini and vision models. Users have a free bandwidth of 60 requests per minute, and the script offers a basic implementation of the API.

Set the environment variable $GOOGLE_API_KEY and run the script with option --google, such as:

chatgpt.sh --google -c -m gemini-pro-vision

OBS: Google Gemini vision models are not enabled for multiturn at the API side, so we hack it.

To list all available models, run chatgpt.sh --google -l.

Google Search

To enable live search in the API, use chat command /g [prompt] or //g [prompt], or set $BLOCK_CMD envar.

export BLOCK_CMD='"tools": [ { "google_search": {} } ]'
chatgpt.sh --goo -c -m gemini-2.5-flash-preview-05-20

Check more web search parameters at Google AI API docs.

Mistral AI

Set up a Mistral AI account, declare the environment variable $MISTRAL_API_KEY, and run the script with option --mistral for complete integration.

Groq

Sign in to Groq. Create a new API key or use an existing one to set the environmental variable $GROQ_API_KEY. Run the script with option --groq.

Groq Whisper STT

Groq API has got the speech-to-text model "whisper-large-v3", which can be used in the stand-alone STT mode with command line option -w, or as the default STT engine in chat mode.

Check the configuration file to set Groq Whisper STT.

Groq TTS

Groq also offers the text-to-speech model "canopylabs/orpheus-v1-english". This model can be used in the stand-alone TTS mode of command line option -z, or set up as the preferred chat TTS engine.

Check the configuration file to set Groq TTS.

Anthropic

Sign in to Antropic AI. Create a new API key or use an existing one to set the environmental variable $ANTHROPIC_API_KEY. Run the script with option --anthropic or --ant.

Check the Claude-4 models! Run the script as:

chatgpt.sh --anthropic -c -m claude-opus-4-5

Prompt caching is implemented in order to save a few bucks.

The script also works on text completions with models such as claude-2.1, although the API documentation flags it as deprecated.

Try:

chatgpt.sh --ant -cd -m claude-2.1

Anthropic Web Search

To enable live search in the API, use chat command /g [prompt] or //g [prompt], or set $BLOCK_USR envar.

export BLOCK_USR='"tools": [{
  "type": "web_search_20250305",
  "name": "web_search",
  "max_uses": 5
}]'
chatgpt.sh --ant -c -m claude-opus-4-0

Check more web search parameters at Anthropic API docs.

GitHub Models

GitHub has partnered with Azure to use its infrastructure.

As a GitHub user, join the wait list and then generate a personal token. Set the environmental variable $GITHUB_TOKEN and run the script with option --github or --git.

Check the on-line model list or list the available models and their original names with chatgpt.sh --github -l.

chatgpt.sh --github -c -m Phi-3-small-8k-instruct

Novita AI

Novita AI offers a range of LLM models at exceptional value.

Next, run the script such as chatgpt.sh --novita -cc.

Check the model list web page and the price of each model.

To list all available models, run chatgpt.sh --novita -l. Optionally set a model name with option -l to dump model details. -->

Some models work with the /completions endpoint, while others work with the /chat/completions endpoint.

Our script does not set the endpoint automatically!

Check model details and web pages to understand their capabilities, and then either run the script with option -c (chat completions), or options -cd (text completions).

As an exercise, set Novita AI integration manually instead:

export OPENAI_API_KEY=novita-api-key
export OPENAI_BASE_URL="https://api.novita.ai/v3/openai"
chatgpt.sh -c -m meta-llama/llama-3.3-70b-instruct

We are grateful to Novita AI for their support and collaboration. For more information, visit Novita AI.

OpenRouter API

To enable OpenRouter API integration, call the script with chatgpt.sh --openrouter -c at the command line.

List models with chatgpt.sh --openrouter -l.

When using OpenRouter to access Claude models, prompt caching is implemented to save a few bucks.

xAI

Visit xAI Grok to generate an API key (environment $XAI_API_KEY).

Run the script with option --xai and also with option -c (chat completions.).

Some models also work with native text completions. For that, set command-line options -cd instead.

xAI Live Search

The xAI live search feature has been discontinued server-side.

Use the in-house solution for simple search text dumps to ground the prompt, chat command /g [search string].

export BLOCK_USR='"search_parameters": {
  "mode": "auto",
  "max_search_results": 10
}'

chatgpt.sh --xai -cc -m grok-3-latest 

Check more live search parameters at xAI API docs.

xAI Image Generation

The model grok-2-image-1212 is supported for image generation with invocation chatgpt.sh --xai -i -m grok-2-image-1212 "[prompt]". -->

DeepSeek

Visit DeepSeek Webpage to get an API key and set envar $DEEPSEEK_API_KEY.

Run the script with option --deepseek. It works with chat completions (option -c) and text completions (options -cd) modes.

• Set $OPENAI_API_KEY with your OpenAI API key.

• Optionally, set $CHATGPTRC with path to the configuration file (run chatgpt.sh -FF to download a template configuration file. Default location = ~/.chatgpt.conf. -->

Arch Linux Users

This project PKGBUILD is available at the Arch Linux User Repository (AUR) to install the software in Arch Linux and derivative distros.

To install the programme from the AUR, you can use an AUR helper like yay or paru. For example, with yay:

yay -S chatgpt.sh

This PKGBUILD generates the package chatgpt.sh-git. Below is an installation example with just the PKGBUILD.

cd $(mktemp -d)

wget https://gitlab.com/fenixdragao/shellchatgpt/-/raw/main/pkg/PKGBUILD

makepkg

pacman -U chatgpt.sh-git*.pkg.tar.zst

-->

Termux Users

Dependencies Termux

Install the Termux and Termux:API apps from the F-Droid store.

Give all permissions to Termux:API in your phone app settings.

We recommend to also install sox, ffmpeg, pulseaudio, imagemagick, and vim (or nano).

Remember to execute termux-setup-storage to set up access to the phone storage.

In Termux proper, install the termux-api and termux-tools packages (pkg install termux-api termux-tools).

When recording audio (STT, Whisper, option -w), if pulseaudio is configured correctly, the script uses sox, ffmpeg or other competent software, otherwise it defaults to termux-microphone-record

Likewise, when playing audio (TTS, option -z), depending on pulseaudio configuration use sox, mpv or fallback to termux wrapper playback (play-audio is optional).

To set the clipboard, it is required termux-clipboard-set from the termux-api package.

In order to dump YouTube captions, yt-dlp is required.

TTS Chat - Removal of Markdown

Markdown in TTS input may stutter the model speech generation a little. If python modules markdown and bs4 are available, TTS input will be converted to plain text. As fallback, pandoc is used if present (chat mode only).

Tiktoken

Under Termux, make sure to have your system updated and installed with python, rust, and rustc-dev packages for building tiktoken.

pkg update
pkg upgrade
pkg install python rust rustc-dev
pip install tiktoken

Termux Troubleshoot

In order to set Termux access to recording the microphone and playing audio (with sox and ffmpeg), follow the instructions below.

A. Set pulseaudio one time only, execute:

pulseaudio -k
pulseaudio -L "module-sles-source" -D

B. To set a permanent configuration:

1. Kill the process with pulseaudio -k.
2. Add load-module module-sles-source to one of the files:

~/.config/pulse/default.pa
/data/data/com.termux/files/usr/etc/pulse/default.pa

3. Restart the server with pulseaudio -D.

C. To create a new user ~/.config/pulse/default.pa, you may start with the following template:

#!/usr/bin/pulseaudio -nF
.include /data/data/com.termux/files/usr/etc/pulse/default.pa
load-module module-sles-source

Troubleshoot

The script may work with newer models, alternative models and APIs, but users are responsible for configuring parameters appropriately.

Script and model settings can be adjusted or set to null using command‑line options, environment variables, or the configuration file.

For example, some models may not accept instructions (command line -S "" to unset), frequency / presence penalties (-A "", -a ""), or other options.

Other parameters, such as temperature (-t 1.0), token limits (maximum response tokens: -M 6000; model capacity: -N 1000000), etc., may need to be set to values supported by the new model.

See also:

• Shell Troubleshoot
• Termux Troubleshoot
• API Provider Setup
• API Base URL Configuration

For software alternatives that may better suit your needs, see the projects listed in the Acknowledgements section below.

💡 Notes and Tips

• Native chat completions is the default mode of script option -c since version 127. To activate the legacy plain text completions chat mode, set options -cd.

• The YouTube feature will get YouTube video heading title and its transcripts information only (when available).

• The PDF support feature extracts PDF text (no images) and appends it to the user request.

• Run chat commands with either operator ! or /.

• One can regenerate a response by typing in a new prompt a single slash /, or // to have last prompt edited before the new request.

• Edit live history entries with command !hist (comment out entries or context injection).

🎯 Project Objectives

• Main focus on chat models (multi-turn, text, image, and audio).

• Implementation of selected features from OpenAI API version 1. As text is the only universal interface, voice and image features will only be partially supported.

• Provide the closest API defaults and let the user customise settings.

Roadmap

• We shall decrease development frequency in 2025, hopefully.

• We plan to gradually wind down development of new features in the near future. The project will enter a maintenance phase from 2025 onwards, focusing primarily on bug fixes and stability.

• We may only partially support the image generation, image variations and image editing specific OpenAI endpoints.

  • Update: Dropped support for image generation, variations and editing endpoints (v122.5 Dec-2025).

• Text completions endpoint is planned to be deprecated when there are no models compatible with this endpoint anymore.

• The warper is deemed finished in the sense any further updates must not change the user interface significantly.

Portability across LLM providers is impractical anyways!
Even switching models within OpenAI (e.g., gpt-4o to gpt-4.1)
can alter behavior, and different providers require unique
optimizations and careful prompt refining.

-->

⚠️ Limitations

• OpenAI API version 1 is the focus of the present project implementation. Only selected features of the API will be covered.

• The script will not execute commands on behalf of users.

• This project doesn't support "Function Calling", "Structured Outputs", "Agents/Operators", nor "MCP Servers".

• We will not support "Real-Time" chatting, or video generation / editing.

• Support for "Responses API" is limited and experimental for now.

• Bash shell truncates input on \000 (null).

• Bash "read command" may not correctly display input buffers larger than the TTY screen size during editing. However, input buffers remain unaffected. Use the text editor interface for big prompt editing.

• Garbage in, garbage out. An idiot savant.

• The script logic resembles a bowl of spaghetti code after a cat fight.

• See LIMITS AND BUGS section in the man page.

Bug report

Please leave bug reports at the GitHub issues page.

📖 Help Pages

Read the online man page here.

Alternatively, a help page snippet can be printed with chatgpt.sh -h.

💪 Contributors

Many Thanks to everyone who contributed to this project.

• edshamis
• johnd0e
• Novita AI's GTM Leo

Everyone is welcome to submit issues, PRs, and new ideas!

Acknowledgements

The following projects are worth remarking. They were studied during development of this script and used as referential code sources.

1. Claude Code
2. Gemini CLI
3. OpenAI Codex CLI
4. Gauthier's Aider
5. sigoden's aichat
6. xenodium's chatgpt-shell
7. andrew's tgpt
8. TheR1D's shell_gpt
9. ErikBjare's gptme
10. SimonW's LLM
11. llm-workflow-engine
12. 0xacx's chatGPT-shell-cli
13. mudler's LocalAI
14. Ollama
15. Google Gemini
16. Groq
17. Antropic AI
18. Novita AI
19. xAI
20. f's awesome-chatgpt-prompts
21. PlexPt's awesome-chatgpt-prompts-zh

The project home is at GitLab

https://gitlab.com/fenixdragao/shellchatgpt

Mirror

https://github.com/mountaineerbr/shellChatGPT