Quickstart | Examples | Actions | Commands | Configuration | Experimental | Developer Guide
Install Terminal AI:
npm install @dwmkerr/terminal-ai
Run the tool to configure your environment and start interactively interfacing with AI:
ai
That's it. The quickest way to learn how to use the tool is to look at the Examples.
Quick links:
- Simple Chat
- Initialising or Updating Config
- Multiline Input
- Copying to the Clipboard or Saving to a File
- Writing Code
- Executing Scripts
- Piping Input
- Advanced
To chat, run ai
and follow the prompts. If you press 'Enter' in the chat prompt instead of replying then the actions menu will pop up with more options:
To execute a chat command, pass your message as a parameter. Note that you should always separate the message parameter from any other flags or commands by using the --
separator:
ai -- "How can I programatically create a calendar invite?"
If ai
detects that you are using a TTY then it will prompt you to continue the conversation. If you are not, the message will be responded to and the tool will close:
ai -- "How can I programatically create a calendar invite?" > answer.txt
Set or update your configuration (such as the OpenAI API key) with the ai init
command:
Run this command with:
ai init
To provide multiline input (or paste multiple lines input input) you can use the Actions Menu to select the 'Chat (Multiline)' action. Just press Enter
at the prompt. Your $EDITOR
will open:
Open the Actions menu with 'Enter' and choose 'Copy Response'. The most recent message will be copied. To save a file, use the 'Save Response' action.
You can copy to the clipboard by specifying the -c
or --copy
parameter:
ai -c -- "Travel time for London to Paris?"
You can also copy to the clipboard by piping to a program like pbcopy
. This example uses the code
intent to ask for code output only and writes to the clipboard:
ai -- "code: bash script to zip all files in current directory" | pbcopy
To provide multiline input (or paste multiple lines input input) you can use the Actions Menu to select the 'Chat (Multiline)' action. Just press Enter
at the prompt. Your $EDITOR
will open:
If you want a response to only contain code, prefix your message with code:
. This makes it much easier to create a response which is ready to be pasted into a file or saved and executed:
To run as a command:
ai -- "code: Python code to find largest file in current directory" > findfile.py
The code
output intent tries to ensure that a single code block is created, rather than multiple blocks in multiple languages. It does this by asking for a single listing with comments used to indicate whether other scripts or operations are needed.
You can execute scripts by asking for code
output, pressing 'Enter' in the response prompt to open the Actions menu and then choosing 'Execute Response'. Terminal AI will ask you to verify the code (using your configured $EDITOR
) and then ask for confirmation before executing:
You can pipe content to ai
- in this example the current uncommitted changes in a repo are analysed:
Tips:
- You must provide a prompt, e.g:
git diff | ai -- 'do I have enough tests?
- You can also pipe the results, e.g:
gif diff | ai -- 'write a git patch that adds tests' > tests.patch
- You can refer to the input with the file name
stdin
, e.g:ai -- 'how many words in stdin?' < dictionary.txt
Advanced or experimental features.
Force color output (useful if you are piping and need color codes):
# Force color output:
# - set FORCE_COLOR=1
# - ascii formatting will be applied even if stdout is not a tty
# - use 'less -r' (-r = raw, render color codes) as a way to quickly test.
FORCE_COLOR=1 ai 'show me some markdown features' | less -r
Example of how to interactively stage, generate a conventional commit:
aigac.sh
- AI Git Add Commit shell script
When you press Enter
in the chat prompt, the Actions menu will pop up. These actions offer additional features to work with AI.
The 'Change Model' action allows you to change the model that is in use:
Models which have been extensively tested and verified to work with Terminal AI are shown in the list first, along with a short description of the model and its capabilities. Models which are offered by AI APIs but have not been extensively tested are shown next.
You can also provide the ID of any model that is not in the list by changing the model
setting in the Configuration.
Verified models are provided by the ai-providers-and-models
project.
ai
The default ai
command initiates a chat. Simply run ai
:
ai
You can provide the initial message as a parameter to the tool:
ai -- "How do I install NodeJS?"
The following parameters are available:
Parameter | Description |
---|---|
-c, --copy |
Copy response to the clipboard and exit. |
-r, --raw |
Do not format markdown or change the response in any way. |
--assistant |
(Experimental). Use the Assistants API rather than the Completions API. |
--no-context-prompts |
Disable context prompts (e.g. 'my shell is bash'). |
--no-output-prompts |
Disable output prompts (e.g. 'show code only'). |
ai init
The ai init
commands allows you to initialise or update your configuration (such as your API key). It also offers the option to validate your configuration:
ai init
Check https://github.com/dwmkerr/terminal-ai#api-key for API key help...
✔ OpenAI API Key: **************************************************
********************************************************************
**********************************************
✔ Test API Key & Configuration? Yes
Checking configuration...
OpenAP API Key validated
Configuration validated
✔ What next?: Chat
This command also allows advanced configuration such as the model to be updated.
ai check
The ai check
command validates your configuration, ensuring your OpenAI API key is configured correctly:
ai check
Checking configuration...
OpenAP API Key validated
Configuration validated
ai config
Shows the current configuration, which is loaded from the configuration files in the [~/.ai
] folder, environment variables and the prompts
folder.
The following error codes can be returned by ai
:
Code | Name | Description |
---|---|---|
1 | ERROR_CODE_WARNING |
A warning was shown to the user. |
2 | ERROR_CODE_INVALID_CONFIFGURATION |
Network connectivity error. |
3 | ERROR_CODE_CONNECTION |
Configuration error. |
An OpenAI API key is needed to be able to make calls to ChatGPT. At the time of writing a subscription fee is needed to create an API key. Create an API key by following the instructions at:
https://platform.openai.com/api-keys
Once you have your API key you can configure it in the ai
tool by running ai
or ai init
.
Most 'stable' configuration can be specified in the ~/.ai/config.yaml
file. Experimental features might only be available in the form of environment variables.
The configuration schema is changing rapidly, the file ./src/configuration/configuration.ts
is the most authoritative source of configuration options. However, some important values are:
Configuration | Environment | Config | Description |
---|---|---|---|
Force colors. | FORCE_COLOR=1 |
n/a | Force ASCII color codes in output even if it not a TTY. |
OpenAI Model | n/a | openai.model |
OpenAI API model to use, default is gpt-3.5-turbo |
OpenAI Model
Any text value can be used for the model. The ai check
command will make a best-effort attempt to validate that the model is correct by calling a chat API. The ai init
command also tries to be helpful by showing a list of pre-defined models that have been loaded from the OpenAI APIs, and validated against ai-providers-and-models
. However models are changing rapidly and new ones may take time to be incorporated. However there is nothing stopping you from simply entering any new model ID in the config file.
Assistants API
You can try using the Assistants APIs rather than the Completions APIs with the --assistant
flag:
ai --assistant -- "Who are you?"
Note that responses will be considerably slower and more API calls will be made.
Clone the repo, install dependencies, build and then run:
git clone [email protected]:dwmkerr/boxes.git
# optional: use the latest node with:
# nvm use --lts
npm install
npm start
# If 'actionlint' is installed, the GitHub workflows will be linted.
brew install actionlint
If you want to install the ai
command run the following:
npm run build # or 'npm run build:watch' to live rebuild...
npm install -g .
# Now run ai commands such as:
ai "ask me anything" # run 'ai' again if the build has updated...
# Clean up when you are done...
npm uninstall -g .
The debug
library is used to make it easy to provide debug level output. Debug logging to the console can be enabled with:
AI_DEBUG_ENABLE="1" npm start
The debug namespaces can be configured like so:
AI_DEBUG_NAMESPACE='ai*'
The following commands are helpful when testing:
# Run all tests. Run tests with coverage.
npm run test
npm run test:cov
# Run (or watch, or debug) tests that match a pattern.
npm run test -- theme
npm run test:watch -- theme
npm run test:debug -- theme
To create a terminal recording for the documentation:
- Install asciinema
brew install asciinema
- Check that you have your profiles setup as documented in
./scripts/record-demo.sh
- Run the script to start a 'clean' terminal
./scripts/record-demo.sh
- Download your recording, e.g. to
./docs/620124.cast
- Install svg-term-cli
npm install -g svg-term-cli
- Convert to SVG:
./scripts/demo-to-svg.sh
Actions - these are commander.js functions that are called by the CLI. They should validate/decode parameters and ask for missing parameters. They will then call a command. Commands - these are the underlying APIs that the CLI offers - they are agnostic of the command line interface (and could therefore be exposed in a web server or so on). Context - information which is provided via prompts to shape the intended output. More details below.
"Context" refers to prompts which are passed to the model before the user interacts, which can provide the model with more information about the environment of the user or their potential intent. Examples would be:
- That the user is running in a shell, with a given set of terminal dimensions
- What the operating system is that the user is running
- (WIP) the organisation and name of the local Git repo
- (WIP) the primary language of the current Git repo.
When expanding context prompts (e.g. ./prompts/chat/context/context.txt) environment variables may be used to give more specific information. As well as those provided by the system (or yourself), the following are automatically set for convenience:
Environment Variable | Description |
---|---|
OS_PLATFORM |
nodejs os.platform() |
TTY_WIDTH |
The terminal width (or 80 if not set) |
TTY_HEIGHT |
The terminal height (or 24 if not set) |