j178/chatgpt: a terminal ChatGPT client built on Bubble Tea

What j178/chatgpt actually replaces

The browser tab is not the problem this tool solves. The problem is that the ChatGPT web interface cannot be composed with anything. You cannot pipe a YAML file into it, you cannot send its answer into `say`, and you cannot keep a prompt template on disk and invoke it by name. j178/chatgpt is a Go binary that wraps the OpenAI API in a terminal UI, so the model becomes another Unix process.

The intended user is someone who already has an API key and lives in a shell. The README's first instruction is to export `OPENAI_API_KEY`; there is no account creation, no login flow and no browser handoff. If you do not have a key, this tool has nothing to offer you. That single constraint separates it from the consumer product it shares a name with, and it is worth being blunt about that before anything else.

Bubble Tea, go-openai and a tokenizer in the dependency list

The repository layout is compact: `chatgpt.go`, `config.go`, `conversation.go`, `utils.go`, a `cmd/` directory, a `ui/` directory and a `tokenizer/` directory. The `go.mod` file names the moving parts. `github.com/charmbracelet/bubbletea` and `bubbles` provide the terminal event loop and widgets, `glamour` and `lipgloss` render the markdown answer with styling, `github.com/sashabaranov/go-openai` is the API client, and `github.com/pkoukk/tiktoken-go` with its loader handles token counting.

That is a conventional Bubble Tea architecture: a model holds the conversation state, the view renders it, and updates arrive as messages. The presence of a tokenizer package rather than a simple character count suggests context length is managed by counting tokens against the `context_length` setting, though the README does not spell out the truncation policy. `github.com/postfinance/single` appears in the direct requirements and typically guards against two instances writing the same state file, which matches the fact that conversations are persisted to disk.

The README also carries a note that support for other providers such as Claude, Gemini and Ollama is under development, pointing at issue #88. As of the README text, that work is not shipped. Treat the provider list as OpenAI-only.

Installing j178/chatgpt and running a first prompt

Four installation routes are documented: a release binary, Homebrew, Scoop and `go install`. The Homebrew tap is the shortest path on macOS and Linux.

brew install j178/tap/chatgpt

On Windows the README uses a Scoop bucket instead, adding it first and then installing the package.

scoop bucket add j178 https://github.com/j178/scoop-bucket.git
scoop install j178/chatgpt

If you prefer to build from source, the module path is explicit and the Go toolchain must satisfy the `go 1.23.0` directive in `go.mod`.

go install github.com/j178/chatgpt/cmd/chatgpt@latest

Before the first run, export the key. The README shows exactly this form, with no alternative variable name.

export OPENAI_API_KEY=xxx

Running `chatgpt` with no arguments opens the interactive chat mode. Running it with `-p` selects one of the named prompts from your configuration, so `chatgpt -p translator` starts a session already primed with that system prompt. The default configuration file lives at `~/.config/chatgpt/config.json` and conversation history is written to `~/.config/chatgpt/conversations.json`. The default prompt in that file is the line beginning "You are ChatGPT, a large language model trained by OpenAI", and the default model is `gpt-3.5-turbo` with `context_length` set to 6, `temperature` 1, `stream` true and `max_tokens` 1024.

The pipeline form is the part worth trying first, because it is what the web interface cannot do. The README gives two examples: piping a file into a prompt, and piping the answer onward.

cat config.yaml | chatgpt -p 'convert this yaml to json'
echo "Hello, world" | chatgpt -p translator | say

In the first case the file content is the user message and the named prompt is the instruction. In the second, the translated text goes straight into the macOS `say` command. If nothing is printed, check that the API key is exported in the same shell that runs the pipeline, since a non-interactive invocation has no UI to report a missing key gracefully.

Key bindings are configurable, and the default set is opinionated

The README documents a large key map, and the interesting part is that it is overridable. You add a `key_map` dictionary to the configuration file and supply arrays of key names. The example in the README reassigns `switch_multiline`, `submit`, `multiline_submit`, `insert_newline`, `multiline_insert_newline`, `help`, `quit`, `copy_last_answer`, `previous_question`, `next_question`, `new_conversation`, `previous_conversation`, `next_conversation`, `remove_conversation` and `forget_context`, each to a list such as `["ctrl+j"]` or `["esc", "ctrl+c"]`.

Defaults worth knowing before you rebind anything: `ctrl+j` toggles single-line and multi-line input, `enter` submits in single-line mode, `ctrl+d` submits in multi-line mode, `ctrl+y` copies the last answer to the clipboard, `ctrl+t` starts a new conversation, `ctrl+x` forgets the current context and `ctrl+r` removes the current conversation. Conversation navigation is bound to `ctrl+left` or `ctrl+g` for the previous one and `ctrl+right` or `ctrl+o` for the next.

Two of these deserve scrutiny. `forget_context` and `remove_conversation` are adjacent in the binding table and do different things: one drops the context used for the next request while keeping the conversation, the other deletes the conversation. Both are single keystrokes with no confirmation mentioned in the README. If you rebind anything, rebind those two away from each other.

Where the design shows its limits

The configuration is a JSON file with comments in the README examples, which is a JSONC presentation of a plain JSON file. That means you cannot paste the commented block directly into `config.json` and expect the parser to accept it. The README does not state which parser is used or whether comments are tolerated, so copy the keys without the comments.

Per-conversation overrides live in `conversations.json`, not in `config.json`. The README shows a conversation entry with its own `config` object carrying `prompt`, `context_length`, `model`, `stream` and `max_tokens`, alongside a `context` array of question and answer pairs and a top-level `last_idx`. Editing that file by hand while the tool is running is a race you should not run; the README does not document any locking behaviour or reload command.

There is no documented rollback or undo for `ctrl+r`, and no documented export format for the conversation history beyond the JSON file itself. The release cadence is also uneven: v1.3.5 is dated 2024-06-09, following v1.3.4 on 2024-01-17 and v1.3.3 on 2024-01-16. The repository's last push was on 2026-08-29, so work has continued after the most recent tagged release, but the gap between v1.3.4 and v1.3.5 is longer than the gap before it. Anyone pinning to a release should look at the commit history rather than the tags.

Finally, this is a client for one vendor's API. If your organisation requires a local model or a non-OpenAI endpoint, the `endpoint` key can be pointed elsewhere but the request shape is still the OpenAI chat completions format. The README's own note about Claude, Gemini and Ollama support points to issue #88, which means it is planned, not present.

How it differs from other terminal chat clients

The closest alternative in kind is a general-purpose terminal LLM client such as `llm`, which is also a command line front end to hosted models. The difference in approach is breadth against depth. `llm` is built around a plugin model and a prompt-and-response command, and it treats the interactive session as one mode among several. j178/chatgpt builds the interactive session first: the Bubble Tea viewport, the scrolling keys, the markdown rendering through glamour, the clipboard copy on `ctrl+y`, the conversation list you page through with `ctrl+left` and `ctrl+right`, and the history file that persists between runs.

If your work is mostly one-shot prompts inside scripts, that interactive machinery is weight you do not need, and a simpler command will be easier to reason about in a Makefile. If your work is long back-and-forth sessions where you want to scroll back, copy an answer and start a fresh conversation without losing the old one, the terminal UI is the reason to pick this tool. The pipeline examples in the README show it can do both, but the design centre is clearly the session.

A second difference is configuration locality. Everything lives under `~/.config/chatgpt/`, in two files you can read and edit. There is no database and no server process. That makes it easy to back up and easy to inspect, and it also means your API key sits in plain text in `config.json` unless you rely on the `OPENAI_API_KEY` environment variable instead.

Licence and maintenance cost

The repository metadata does not identify a licence, and the README does not carry a licence section. The top-level file list shows no `LICENSE` entry. Before you vendor this into a product or redistribute a binary, check the repository for a licence file directly, because the absence of one is not the same as permissive terms. This is a factual gap in what is published, not a legal opinion, and it is the kind of gap that blocks adoption in a company with a review process.

The upgrade cost is low in normal use. The binary is self-contained, the configuration is two JSON files, and the release page provides prebuilt binaries. The risk sits in the configuration schema: `conversations.json` stores a `config` object per conversation, so a future release that changes the meaning of `context_length` or `max_tokens` could apply new defaults to old entries. Back up `~/.config/chatgpt/` before upgrading across a major version, and read the release notes for the version you are moving to. The README does not describe a migration path.

Editorial conclusion

Adopt j178/chatgpt if you already hold an OpenAI API key and want a keyboard-driven client that pipes cleanly into shell commands. Skip it if you want a free ChatGPT account experience, image generation or a provider other than OpenAI, since the README lists only OpenAI endpoints and the multi-provider work is still an open issue. Before relying on it, verify the licence file, which the repository metadata does not identify, and confirm that the endpoint key in ~/.config/chatgpt/config.json points at the base URL you intend to use.

Frequently asked questions

Official sources

1. Issues
2. j178/chatgpt on GitHub
3. README
4. Releases