Updates to the main chatgpt script : interface to the OpenAI chat completion API

[stoerr]

The bin/chatgpt script is what got this project started and is probably the main tool that gives you access to the OpenAI chat completion API in many ways. It's a swiss knife type tool with many options that make it easy to compose prompts, add image input or audio prompts, add text files, create JSON output, have the AI use tools, even chat with the AI from the command line. I'll add a comment here whenever there is a new category of options for it. As a baseline, the current options are:

chatgpt - Submit a prompt to ChatGPT conversation and print the response to stdout. The prompt can be given on the command line or read from stdin.

Usage: chatgpt [options] [prompt]

Input Options:
  -               Reads prompt from stdin; if a prompt is given on the command line it is appended
  -f filename     Includes the content of the given [f]ile as additional message in https://www.stoerr.net/blog/aimouth pattern.
                  Can be given multiple times. if - is given as filename, the content is read from stdin.
  -ff filenames   Like -f, but for multiple [ff]iles - all further arguments are treated as filenames until there is a switch.
  -fp filename    Includes the content of the given [f]ile as codeblock into the [p]rompt, together with the filename. Can be given multiple times.
  -i imagefile    Includes the given image file as [i]mage, together with the filename. Can be given multiple times.
  -iu imageurl    Includes the given [i]mage [u]rl as image, together with the url. Can be given multiple times.
  -id detaillevel Sets the image [d]etail level. Can be 'low', 'high', or 'auto'. Default is 'auto'.
  -a audiofile    Includes the given audio file as [a]udio. Can be given multiple times.
  -au audiourl    Includes the given [a]udio [u]rl as audio. Can be given multiple times.
  -af format      Sets the audio [f]ormat, if not obvious from the file name or url. Can be 'mp3', 'wav'. Default is 'mp3'.

Prompt Options:
  -p prefix       Prefix the [p]rompt with a string.
  -pf prefixfile  Prefix the [p]rompt with the contents of a [f]ile
  -pl key         Add a prompt from the ChatGPT [p]rompt [l]ibrary using the given key (see script chatgptpromptlib)
  -pa             Prefix the [p]rompt with recorded [a]udio from the microphone until a key is pressed (transcribed using chatgptdictate)
  -u suffix       S[u]ffix the prompt with a string (that is, append that to the prompt)
  -uf suffixfile  S[u]ffix the prompt with the contents of a [f]ile
  -ua             S[u]ffix the prompt with recorded [a]udio from the microphone until a key is pressed (transcribed using chatgptdictate)

System Message Options:
  -s systemmsg    Use the given string as [s]ystem message
  -sf systemfile  Use as [s]ystem message the contents of the given file
  -sl key         Add a [s]ystem message from the ChatGPT prompt [l]ibrary using the given key with chatgptpromptlib

Conversation Options: (only 1 turn per call chatgpt except with -cr/ca; the conversation state is kept in a file)chatgpt)
  -cf convfile    Use the given file to keep a [c]onversation state [f]ile. Either creates this file or updates it after the answer is received.
  -cn             Starts a new stored [c]onversation: a [n]ew file in directory $HOME/.chatgpt/conversations is created and used as conversation state.
  -cc             [C]onversation [c]ontinue for the last conversation: the last file in directory $HOME/.chatgpt/conversations is used as conversation state.
  -cl convfile    [C]onversation [l]oad from the given file and uses it for the conversation, but is not updating the file.
  -cd             [C]onversation file [d]elete: removes the last automatically created conversation file (-cn) and then exits.
  -cp             [C]onversation - [p]rints the conversation state as JSON and then exits. Use -cc or -cf to specify which file to print.
  -cr             [C]onversation - multi tu[r]n conversation - abort the program to end this. Each message is finished with Ctrl-D.
  -ca             [C]onversation - multi turn conversation with dictated [a]udio - abort the program to end this.

Request Settings etc.:
  -m modelname    Use a specific [m]odel (default: gpt-4o-mini)
  -mh             Use the [m]odel with - the time of updating this script - [h]ighest general intelligence ("gpt-4o")
  -t number       Set max [t]okens for response (default: no limit)
  -v              [V]erbose output : prints the sent and received json message to stderr and gives info about connection retries
  -w column       [W]ord wrap the response to a specified column width using fmt.
  -abbrev         [Abbrev]iate ("clip") the message in the middle if it's too long for the model context window
  -api url        Use this URL instead of the OpenAI chat completion [API] (e.g. for local LLM or OpenAI compatible APIs)
  -o key=value    Other [o]ptions, e.g. for the OpenAI API -o temperature=0.5 . Can be given multiple times.
  -of key=file    Other [o]ptions read from a json [f]ile, e.g. for the OpenAI API tools. Can be given multiple times.
  --              Last option - option parsing stops, the rest is taken as prompt. E.g. for finishing a -ff list.

Help Options:
  -h, --help      Show this [h]elp message
  -ha, --helpai   Answer a question about the tool from this [h]elptext using [A]I and exit. The rest of the command line (prompt) is the question.

If the prompt or system message contain a construct like promptlib:key , the chatgptpromptlib command will be called with that key
and this will be replaced with the prompt library entry, as an alternative to -pl key .

The conversation files contain JSON arrays of the conversation messages.

[stoerr]

I've been adding a couple of options that make structured JSON output possible if you want to make sure the AI generates proper JSON output in a structure you expect. That ranges from making sure the output is proper JSON, over giving an actual JSON schema the AI will match to simplifications -ra and -rar for two common usecases. Use -ra if you just want a JSON object with the given keys (making them self-explanatory of course pays, as there are no descriptions that way) or -rar if you want a list of such JSON objects. You still have to give a prompt that says that it should generate JSON and a bit of what you need, though.

Response Options:
  -rj             [R]esponse mode JSON: model outputs a JSON object
  -rf schemafile  Structured output: requests that the [r]esponse conforms to the given JSON schema read from a [f]ile.
  -ra attr1,...   Structured output [r]esponse - JSON with [a]ttributes: comma separated list of attributes to include in the JSON response.
                  Alternative to -rf - creates a simple schema with these attributes as string properties.
  -rar attr1,...  Structured output for JSON [r]esponse [ar]ray of objects with the given attributes - e.g. for extracting
                  a list of entities from an input. Alternative to -rf and -ra , all are string properties.

[stoerr]

There is also now tools / function calling support: you can provide the possibility to call some command line programs or scripts for the AI before it creates the final answer. The AI does decide on it's own whether, when and how to call them, so please be careful that it can't do too much damage if something goes wrong.

Tooling options:
  -tf configfile  Use the given file as [t]ools configuration [f]ile for tools the LLM could use.

A tools config file contains an array of tool definitions: {"function":{"name":...,"description:"...", "parameters":..., "strict":...},
"commandline: [...], "stdin": ...}. The commandline array is used to call the tool, and stdin is the input for the tool.
In the command line array and stdin, $args is replaced by the arguments given to the tool, and $toolcall is replaced by the tool call JSON.