Skip to content
Back to search

chatgpt-cli

ChatGPT CLI is a powerful, multi-provider command-line interface for working with modern LLMs. It supports OpenAI, Azure, Perplexity, LLaMA, and more, with features like streaming, interactive chat, prompt files, image/audio I/O, MCP tool calls, and an experimental agent mode for safe, multi-step automation.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/kardolus/chatgpt-cli with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/kardolus/chatgpt-cli'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kardolus--chatgpt-cli/badge.svg)](/listings/kardolus--chatgpt-cli)

HTML

<a href="/listings/kardolus--chatgpt-cli"><img src="/api/listings/kardolus--chatgpt-cli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

ReAct mode (default):

chatgpt why is my test failing? --agent

Plan/Execute mode:

chatgpt what is the weather like in brooklyn --agent --agent-mode plan

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,030 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # ChatGPT CLI
  2. ![Test Workflow](https://github.com/kardolus/chatgpt-cli/actions/workflows/test.yml/badge.svg?branch=main) [![Public Backlog](https://img.shields.io/badge/public%20backlog-808080)](https://github.com/users/kardolus/projects/2)
  3. ChatGPT CLI is a powerful, multi-provider command-line interface for working with modern LLMs. It supports OpenAI,
  4. Azure, Perplexity, LLaMA, and more, and includes streaming, interactive chat, prompt files, image/audio I/O, MCP tool
  5. calls, and an experimental agent mode for multi-step tasks with safety and budget controls.
  6. ![a screenshot](cmd/chatgpt/resources/vhs.gif)
  7. ## Table of Contents
  8. - [Features](#features)
  9. - [Prompt Support](#prompt-support)
  10. - [Using the prompt flag](#using-the---prompt-flag)
  11. - [Example](#example)
  12. - [Explore More Prompts](#explore-more-prompts)
  13. - [Agent Mode (ReAct + Plan/Execute)](#agent-mode-react--planexecute)
  14. - [Quick Start](#quick-start)
  15. - [Workdir Safety](#workdir-safety)
  16. - [Budgets and Policy](#budgets-and-policy)
  17. - [Logs](#logs)
  18. - [MCP Support](#mcp-support)
  19. - [Overview](#overview)
  20. - [Examples](#examples)
  21. - [Headers and Authentication](#headers-and-authentication)
  22. - [MCP Session Management](#mcp-session-management)
  23. - [How MCP Results Are Used](#how-mcp-results-are-used)
  24. - [Installation](#installation)
  25. - [Using Homebrew (macOS)](#using-homebrew-macos)
  26. - [Direct Download](#direct-download)
  27. - [Apple Silicon](#apple-silicon)
  28. - [macOS Intel chips](#macos-intel-chips)
  29. - [Linux (amd64)](#linux-amd64)
  30. - [Linux (arm64)](#linux-arm64)
  31. - [Linux (386)](#linux-386)
  32. - [FreeBSD (amd64)](#freebsd-amd64)
  33. - [FreeBSD (arm64)](#freebsd-arm64)
  34. - [Windows (amd64)](#windows-amd64)
  35. - [Getting Started](#getting-started)
  36. - [Configuration](#configuration)
  37. - [General Configuration](#general-configuration)
  38. - [LLM Specific Configuration](#llm-specific-configuration)
  39. - [Agent Configuration](#agent-configuration)
  40. - [Default Policy](#default-policy)
  41. - [Custom Config and Data Directory](#custom-config-and-data-directory)
  42. - [Example for Custom Directories](#example-for-custom-directories)
  43. - [Variables for interactive mode](#variables-for-interactive-mode)
  44. - [Switching Between Configurations with --target](#switching-between-configurations-with---target)
  45. - [Azure Configuration](#azure-configuration)
  46. - [Perplexity Configuration](#perplexity-configuration)
  47. - [302 AI Configuration](#302ai-configuration)
  48. - [Atlas Cloud Configuration](#atlas-cloud-configuration)
  49. - [Command-Line Autocompletion](#command-line-autocompletion)
  50. - [Enabling Autocompletion](#enabling-autocompletion)
  51. - [Persistent Autocompletion](#persistent-autocompletion)
  52. - [Markdown Rendering](#markdown-rendering)
  53. - [Development](#development)
  54. - [Using the Makefile](#using-the-makefile)
  55. - [Testing the CLI](#testing-the-cli)
  56. - [Reporting Issues and Contributing](#reporting-issues-and-contributing)
  57. - [Uninstallation](#uninstallation)
  58. - [Useful Links](#useful-links)
  59. - [Additional Resources](#additional-resources)
  60. ## Features
  61. * **Streaming mode**: Real-time interaction with the GPT model.
  62. * **Query mode**: Single input-output interactions with the GPT model.
  63. * **Interactive mode**: The interactive mode allows for a more conversational experience with the model. Prints the
  64. token usage when combined with query mode.
  65. * **Thread-based context management**: Enjoy seamless conversations with the GPT model with individualized context for
  66. each thread, much like your experience on the OpenAI website. Each unique thread has its own history, ensuring
  67. relevant and coherent responses across different chat instances.
  68. * **Sliding window history**: To stay within token limits, the chat history automatically trims while still preserving
  69. the necessary context. The size of this window can be adjusted through the `context-window` setting.
  70. * **Custom context from any source**: You can provide the GPT model with a custom context during conversation. This
  71. context can be piped in from any source, such as local files, standard input, or even another program. This
  72. flexibility allows the model to adapt to a wide range of conversational scenarios.
  73. * **Agent mode (ReAct + Plan/Execute)**: Run multi-step tasks that can think, act, and observe using tools like shell,
  74. file operations, and LLM reasoning. Supports both iterative ReAct loops and Plan/Execute workflows, with built-in *
  75. *budget limits** (time, steps, tokens) and **policy enforcement** (allowed tools, denied commands, workdir
  76. sandboxing) for safe-by-default automation.
  77. * **Web search**: Allow compatible models (e.g. `gpt-5+`) to fetch live web data during a query. Enable with the `web`
  78. setting and tune results using `web_context_size`.
  79. * **MCP (Model Context Protocol) support**: Call external MCP tools via HTTP(S) or STDIO, inject their results into the
  80. conversation context, and continue the prompt seamlessly.
  81. * **MCP session management**: Built-in support for stateful MCP servers. The CLI automatically initializes
  82. sessions, attaches session identifiers, and renews them when they become invalid.
  83. * **Support for images**: Upload an image or provide an image URL using the `--image` flag. Note that image support may
  84. not be available for all models. You can also pipe an image directly: `pngpaste - | chatgpt "What is this photo?"`
  85. * **Generate images**: Use the `--draw` and `--output` flags to generate an image from a prompt (requires image-capable
  86. models like `gpt-image-1`).
  87. * **Edit images**: Use the `--draw` flag with `--image` and `--output` to modify an existing image using a prompt (
  88. e.g., "add sunglasses to the cat"). Supported formats: PNG, JPEG, and WebP.
  89. * **Audio support**: You can upload audio files using the `--audio` flag to ask questions about spoken content.
  90. This feature is compatible only with audio-capable models like gpt-4o-audio-preview. Currently, only `.mp3` and `.wav`
  91. formats are supported.
  92. * **Transcription support**: You can also use the `--transcribe` flag to generate a transcript of the uploaded audio.
  93. This uses OpenAI’s transcription endpoint (compatible with models like gpt-4o-transcribe) and supports a wider range
  94. of formats, including `.mp3`, `.mp4`, `.mpeg`, `.mpga`, `.m4a`, `.wav`, and `.webm`.
  95. * **Text-to-speech support**: Use the `--speak` and `--output` flags to convert text to speech (works with models like
  96. `gpt-4o-mini-tts`).
  97. If you have `afplay` installed (macOS), you can even chain playback like this:
  98. ```shell
  99. chatgpt --speak "convert this to audio" --output test.mp3 && afplay test.mp3
  100. ```
  101. * **Model listing**: Access a list of available models using the `-l` or `--list-models` flag.
  102. * **Advanced configuration options**: The CLI supports a layered configuration system where settings can be specified
  103. through default values, a `config.yaml` file, and environment variables. For quick adjustments,
  104. various `--set-<value>` flags are provided. To verify your current settings, use the `--config` or `-c` flag.
  105. ### Prompt Support
  106. We’re excited to introduce support for prompt files with the `--prompt` flag in **version 1.7.1**! This feature
  107. allows you to provide a rich and detailed context for your conversations directly from a file.
  108. #### Using the `--prompt` Flag
  109. The `--prompt` flag lets you specify a file containing the initial context or instructions for your ChatGPT
  110. conversation. This is especially useful when you have detailed instructions or context that you want to reuse across
  111. different conversations.
  112. To use the `--prompt` flag, pass the path of your prompt file like this:
  113. ```shell
  114. chatgpt --prompt path/to/your/prompt.md "Use a pipe or provide a query here"
  115. ```
  116. The contents of `prompt.md` will be read and used as the initial context for the conversation, while the query you
  117. provide directly will serve as the specific question or task you want to address.
  118. #### Example
  119. Here’s a fun example where you can use the output of a `git diff` command as a prompt:
  120. ```shell
  121. git diff | chatgpt --prompt ../prompts/write_pull-request.md
  122. ```
  123. In this example, the content from the `write_pull-request.md` prompt file is used to guide the model's response based on
  124. the diff data from `git diff`.
  125. #### Explore More Prompts
  126. For a variety of ready-to-use prompts, check out this [awesome prompts repository](https://github.com/kardolus/prompts).
  127. These can serve as great starting points or inspiration for your own custom prompts!
  128. ### Agent Mode (ReAct + Plan/Execute)
  129. ![a screenshot](cmd/chatgpt/resources/agent.gif)
  130. ChatGPT CLI includes an experimental **agent mode** that can plan and run multi-step tasks using tools (shell, file ops,
  131. and LLM reasoning), while enforcing **budget + policy** constraints.
  132. There are two agent modes:
  133. - **ReAct (-agent-mode react)**: iterative “think → act → observe” loop
  134. - **Plan/Execute (-agent-mode plan)**: generates a plan first, then executes it step-by-step
  135. #### Quick Start
  136. ReAct mode (default):
  137. ```
  138. chatgpt why is my test failing? --agent
  139. ```
  140. Plan/Execute mode:
  141. ```
  142. chatgpt what is the weather like in brooklyn --agent --agent-mode plan
  143. ```
  144. #### Workdir Safety
  145. Agent file access can be restricted to a working directory. This is useful to prevent accidental reads/writes outside a
  146. project.
  147. ```
  148. chatgpt "what files are in the /tmp directory" \
  149. --agent \
  150. --agent-work-dir .
  151. ```
  152. If a step tries to read/write outside the workdir, it will be denied by policy (e.g. kind=path_escape).
  153. #### Budgets and Policy
  154. Agent execution is governed by:
  155. - **Budget limits** (iterations, steps, tool calls, wall-time, token usage)
  156. - **Policy rules** (allowed tools, denied shell commands, file op allowlist, and workdir path restrictions)
  157. This keeps the agent useful while still being safe-by-default.
  158. #### Logs
  159. When running in agent mode, ChatGPT CLI automatically writes detailed execution logs to the cache directory, under:
  160. ```
  161. $OPENAI_CACHE_HOME/agent/
  162. ```
  163. These logs include:
  164. - Planner output (for Plan/Execute mode)
  165. - Tool calls and their results
  166. - Timing and budget usage
  167. - Debug-level traces when debug logging is enabled
  168. Each agent run gets its own timestamped log directory, making it easy to inspect what happened after the fact or debug
  169. unexpected behavior.
  170. This is especially useful when:
  171. - An agent run fails due to budget or policy limits
  172. - You want to understand why the agent chose certain steps
  173. - You’re developing or tuning agent policies and budgets
  174. ### MCP Support
  175. ChatGPT CLI supports the Model Context Protocol (MCP) over HTTP(S). This allows the CLI to call an MCP tool, inject the
  176. tool’s result into the current thread as context, and then run your prompt — all in one command. The integration is
  177. provider-agnostic.
  178. You provide:
  179. - MCP endpoint URL (`--mcp`)
  180. - Tool name (`--mcp-tool`)
  181. - Optional HTTP headers (`--mcp-header`)
  182. - Tool arguments (`--mcp-param` or `--mcp-params`)
  183. #### Overview
  184. When `--mcp` is set, the CLI will:
  185. 1. POST a JSON-RPC `tools/call` request to your MCP server
  186. 2. Automatically initialize and manage an MCP session if required
  187. 3. Extract the tool output
  188. 4. Store it as an assistant message in the active thread (prefixed with `[MCP: <tool>]`)
  189. 5. Submit your query to the model (if you provided one)
  190. #### Examples
  191. Local FastMCP echo server (minimal MCP HTTP example):
  192. ```bash
  193. chatgpt \
  194. --mcp "http://127.0.0.1:8000/mcp" \
  195. --mcp-tool echo \
  196. --mcp-param 'payload={"foo":"bar","count":3,"enabled":true}' \
  197. "What did the MCP server receive?"
  198. ```
  199. Apify MCP example (production MCP server):
  200. ```shell
  201. chatgpt \
  202. --mcp "https://mcp.apify.com/?tools=epctex/weather-scraper" \
  203. --mcp-tool "epctex-slash-weather-scraper" \
  204. --mcp-header "Authorization: Bearer $APIFY_API_KEY" \
  205. --mcp-param locations='["Brooklyn, NY"]' \
  206. --mcp-param timeFrame=today \
  207. --mcp-param units=imperial \
  208. --mcp-param proxyConfiguration='{"useApifyProxy":true}' \
  209. --mcp-param maxItems=1 \
  210. "what should I wear today"
  211. ```
  212. Using `--mcp-params` (raw JSON) instead of multiple `--mcp-param` flags:
  213. ```shell
  214. chatgpt \
  215. --mcp "https://your-mcp-server.example.com" \
  216. --mcp-tool "some-tool-name" \
  217. --mcp-params '{"locations":["Brooklyn, NY"],"timeFrame":"today"}' \
  218. "what should I wear today"
  219. ```
  220. Local MCP server over stdio (no HTTP, runs as a subprocess):
  221. ```shell
  222. chatgpt \
  223. --mcp "stdio:python test/mcp/stdio/mcp_stdio_server.py" \
  224. --mcp-tool echo \
  225. --mcp-param 'payload={"foo":"bar","count":3}' \
  226. "What did the MCP server receive?"
  227. ```
  228. #### Headers and Authentication
  229. MCP does not mandate a specific authentication mechanism. Some servers use Bearer tokens, others use API keys, cookies,
  230. or no auth at all. Use `--mcp-header` to pass whatever your MCP server requires:
  231. ```shell
  232. --mcp-header "Authorization: Bearer $TOKEN"
  233. --mcp-header "X-Api-Key: $API_KEY"
  234. ```
  235. #### MCP Session Management
  236. Some MCP servers require a session identifier (commonly `mcp-session-id`) to be established before tool calls are
  237. accepted. The ChatGPT CLI automatically manages MCP sessions for HTTP(S) servers that require them:
  238. - Initializes a session when needed
  239. - Caches the session identifier per endpoint
  240. - Attaches it to subsequent requests
  241. - Automatically re-initializes the session if the server invalidates it
  242. Stateless servers are also supported: if `initialize` returns no `mcp-session-id` header, the CLI proceeds without one
  243. (the streamable-HTTP spec makes the session id optional) rather than failing.
  244. You can explicitly pass a session header yourself using `--mcp-header`. If you do, the CLI will respect it and skip
  245. automatic session handling.
  246. #### How MCP Results Are Used
  247. Tool results are injected into the conversation thread as context before your query runs. The injected message is stored
  248. as an assistant message and prefixed like this:
  249. ```text
  250. [MCP: <tool-name>] ...
  251. ```
  252. If you run MCP without providing a query, the CLI will inject the context and exit:
  253. ```shell
  254. chatgpt \
  255. --mcp "https://your-mcp-server.example.com" \
  256. --mcp-tool "some-tool-name" \
  257. --mcp-params '{"foo":"bar"}'
  258. ```
  259. ## Installation
  260. ### Using Homebrew (macOS)
  261. You can install chatgpt-cli using Homebrew:
  262. ```shell
  263. brew tap kardolus/chatgpt-cli
  264. brew trust kardolus/chatgpt-cli
  265. brew install chatgpt-cli
  266. ```
  267. > **Note:** Homebrew 6.0+ requires you to explicitly trust third-party taps before
  268. > their formulae will run, so the `brew trust` step above is required (a one-time
  269. > action per machine). If you're upgrading and see
  270. > `Refusing to load formula ... from untrusted tap`, run
  271. > `brew trust kardolus/chatgpt-cli` and then `brew upgrade chatgpt-cli`.
  272. ### Direct Download
  273. For a quick and easy installation without compiling, you can directly download the pre-built binary for your operating
  274. system and architecture:
  275. #### Apple Silicon
  276. ```shell
  277. curl -L -o chatgpt https://github.com/kardolus/chatgpt-cli/releases/latest/download/chatgpt-darwin-arm64 && chmod +x chatgpt && sudo mv chatgpt /usr/local/bin/
  278. ```
  279. #### macOS Intel chips
  280. ```shell
  281. curl -L -o chatgpt https://github.com/kardolus/chatgpt-cli/releases/latest/download/chatgpt-darwin-amd64 && chmod +x chatgpt && sudo mv chatgpt /usr/local/bin/
  282. ```
  283. #### Linux (amd64)
  284. ```shell
  285. curl -L -o chatgpt https://github.com/kardolus/chatgpt-cli/releases/latest/download/chatgpt-linux-amd64 && chmod +x chatgpt && sudo mv chatgpt /usr/local/bin/
  286. ```
  287. #### Linux (arm64)
  288. ```shell
  289. curl -L -o chatgpt https://github.com/kardolus/chatgpt-cli/releases/latest/download/chatgpt-linux-arm64 && chmod +x chatgpt && sudo mv chatgpt /usr/local/bin/
  290. ```
  291. #### Linux (386)
  292. ```shell
  293. curl -L -o chatgpt https://github.com/kardolus/chatgpt-cli/releases/latest/download/chatgpt-linux-386 && chmod +x chatgpt && sudo mv chatgpt /usr/local/bin/
  294. ```
  295. #### FreeBSD (amd64)
  296. ```shell
  297. curl -L -o chatgpt https://github.com/kardolus/chatgpt-cli/releases/latest/download/chatgpt-freebsd-amd64 && chmod +x chatgpt && sudo mv chatgpt /usr/local/bin/
  298. ```
  299. #### FreeBSD (arm64)
  300. ```shell
  301. curl -L -o chatgpt https://github.com/kardolus/chatgpt-cli/releases/latest/download/chatgpt-freebsd-arm64 && chmod +x chatgpt && sudo mv chatgpt /usr/local/bin/
  302. ```
  303. #### Windows (amd64)
  304. Download the binary
  305. from [this link](https://github.com/kardolus/chatgpt-cli/releases/latest/download/chatgpt-windows-amd64.exe) and add it
  306. to your PATH.
  307. Choose the appropriate command for your system, which will download the binary, make it executable, and move it to your
  308. /usr/local/bin directory (or %PATH% on Windows) for easy access.
  309. ## Getting Started
  310. 1. Set the `OPENAI_API_KEY` environment variable to
  311. your [ChatGPT secret key](https://platform.openai.com/account/api-keys). To set the environment variable, you can add
  312. the following line to your shell profile (e.g., ~/.bashrc, ~/.zshrc, or ~/.bash_profile), replacing your_api_key with
  313. your actual key:
  314. ```shell
  315. export OPENAI_API_KEY="your_api_key"
  316. ```
  317. 2. To enable history tracking across CLI calls, create a ~/.chatgpt-cli directory using the command:
  318. ```shell
  319. mkdir -p ~/.chatgpt-cli
  320. ```
  321. Once this directory is in place, the CLI automatically manages the message history for each "thread" you converse
  322. with. The history operates like a sliding window, maintaining context up to a configurable token maximum. This
  323. ensures a balance between maintaining conversation context and achieving optimal performance.
  324. By default, if a specific thread is not provided by the user, the CLI uses the default thread and stores the history
  325. at `~/.chatgpt-cli/history/default.json`. You can find more details about how to configure the `thread` parameter in
  326. the
  327. [Configuration](#configuration) section of this document.
  328. 3. Try it out:
  329. ```shell
  330. chatgpt what is the capital of the Netherlands
  331. ```
  332. 4. To start interactive mode, use the `-i` or `--interactive` flag:
  333. ```shell
  334. chatgpt --interactive
  335. ```
  336. If you want the CLI to automatically create a new thread for each session, ensure that the `auto_create_new_thread`
  337. configuration variable is set to `true`. This will create a unique thread identifier for each interactive session.
  338. 5. To use the pipe feature, create a text file containing some context. For example, create a file named context.txt
  339. with the following content:
  340. ```shell
  341. Kya is a playful dog who loves swimming and playing fetch.
  342. ```
  343. Then, use the pipe feature to provide this context to ChatGPT:
  344. ```shell
  345. cat context.txt | chatgpt "What kind of toy would Kya enjoy?"
  346. ```
  347. 6. To list all available models, use the -l or --list-models flag:
  348. ```shell
  349. chatgpt --list-models
  350. ```
  351. 7. For more options, see:
  352. ```shell
  353. chatgpt --help
  354. ```
  355. ## Configuration
  356. The ChatGPT CLI adopts a four-tier configuration strategy, with different levels of precedence assigned to flags,
  357. environment variables, a config.yaml file, and default values, in that respective order:
  358. 1. Flags: Command-line flags have the highest precedence. Any value provided through a flag will override other
  359. configurations.
  360. 2. Environment Variables: If a setting is not specified by a flag, the corresponding environment variable (prefixed with
  361. the name field from the config) will be checked.
  362. 3. Config file (config.yaml): If neither a flag nor an environment variable is set, the value from the config.yaml file
  363. will be used.
  364. 4. Default Values: If no value is specified through flags, config.yaml, or environment variables, the CLI will fall back
  365. to its built-in default values.
  366. ### General Configuration
  367. | Variable | Description | Default |
  368. |--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
  369. | `name` | The prefix for environment variable overrides. | 'openai' |
  370. | `thread` | The name of the current chat thread. Each unique thread name has its own context. | 'default' |
  371. | `target` | Load configuration from config._target_.yaml | '' |
  372. | `omit_history` | If true, the chat history will not be used to provide context for the GPT model. | false |
  373. | `command_prompt` | The command prompt in interactive mode. Should be single-quoted. | '[%datetime] [Q%counter]' |
  374. | `output_prompt` | The output prompt in interactive mode. Should be single-quoted. | '' |
  375. | `command_prompt_color` | The color of the command_prompt in interactive mode. Supported colors: "red", "green", "blue", "yellow", "magenta". | '' |
  376. | `output_prompt_color` | The color of the output_prompt in interactive mode. Supported colors: "red", "green", "blue", "yellow", "magenta". | '' |
  377. | `auto_create_new_thread` | If set to `true`, a new thread with a unique identifier (e.g., `int_a1b2`) will be created for each interactive session. If `false`, the CLI will use the thread specified by the `thread` parameter. | `false` |
  378. | `auto_shell_title` | If set to true, sets the title of the shell to the name of the current thread. | `false` |
  379. | `track_token_usage` | If set to true, displays the total token usage after each query in --query mode, helping you monitor API usage. | `false` |
  380. | `debug` | If set to true, prints the raw request and response data during API calls, useful for debugging. | `false` |
  381. | `custom_headers` | Add a map of custom headers to each http request | {} |
  382. | `skip_tls_verify` | If set to true, skips TLS certificate verification, allowing insecure HTTPS requests. | `false` |
  383. | `http_timeout` | HTTP client timeout in seconds. Set to `0` for no timeout, useful for slow or local models. | `60` |
  384. | `max_retries` | Number of times to retry a request that fails with a connection error, `429`, or `5xx` status. A positive `Retry-After` header is honored; otherwise exponential backoff with jitter is used. `0` keeps the built-in default of 3; a negative value disables retries. Retries only re-establish the request, never mid-stream. Note: a retried completion `POST` can be processed twice server-side if the first response was lost after the request was received (same trade-off the official SDKs make). | `3` |
  385. | `retry_base_delay_ms` | Base delay in milliseconds for exponential backoff between retries (ignored when the server sends a `Retry-After` header). | `500` |
  386. | `multiline` | If set to true, enables multiline input mode in interactive sessions. | `false` |
  387. | `role_file` | Path to a file that overrides the system role (role). | '' |
  388. | `prompt` | Path to a file that provides additional context before the query. | '' |
  389. | `image` | Local path or URL to an image used in the query. | '' |
  390. | `audio` | Path to an audio file (MP3/WAV) used as part of the query. | '' |
  391. | `output` | Path where synthesized audio is saved when using --speak. | '' |
  392. | `transcribe` | Enables transcription mode. This flags takes the path of an audio file. | `false` |
  393. | `speak` | If true, enables text-to-speech synthesis for the input query. | `false` |
  394. | `draw` | If true, generates an image from a prompt and saves it to the path specified by `output`. Requires image-capable models. | `false` |
  395. | `web` | Enable web search for supported models (e.g. gpt-5+). | `false` |
  396. | `web_context_size` | Controls how much context is retrieved during web search (`low`, `medium`, `high`). | `low` |
  397. ### LLM-Specific Configuration
  398. | Variable | Description | Default |
  399. |--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------|
  400. | `api_key` | Your API key. | '' |
  401. | `api_key_file` | Load the API key from a file instead of the environment. Takes precedence over the environment variable. | '' |
  402. | `auth_header` | The header used for authorization in API requests. | 'Authorization' |
  403. | `auth_token_prefix` | The prefix to be added before the token in the `auth_header`. | 'Bearer ' |
  404. | `completions_path` | The API endpoint for completions. | '/v1/chat/completions' |
  405. | `context_window` | The memory limit for how much of the conversation can be remembered at one time. | 8192 |
  406. | `effort` | Sets the reasoning effort. Used by gpt-5 and o1-pro models. | 'low' |
  407. | `frequency_penalty` | Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far. | 0.0 |
  408. | `image_edits_path` | The API endpoint for image editing. | '/v1/images/edits' |
  409. | `image_generations_path` | The API endpoint for image generation. | '/v1/images/generations' |
  410. | `max_tokens` | The maximum number of tokens that can be used in a single API call. | 4096 |
  411. | `model` | The GPT model used by the application. | 'gpt-4o' |
  412. | `models_path` | The API endpoint for accessing model information. | '/v1/models' |
  413. | `presence_penalty` | Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far. | 0.0 |
  414. | `responses_path` | The API endpoint for responses. Used by o1-pro models. | '/v1/responses' |
  415. | `role` | The system role | 'You are a helpful assistant.' |
  416. | `seed` | Sets the seed for deterministic sampling (Beta). Repeated requests with the same seed and parameters aim to return the same result. | 0 |
  417. | `speech_path` | The API endpoint for text-to-speech synthesis. | '/v1/audio/speech' |
  418. | `temperature` | What sampling temperature to use, between 0 and 2. Higher values make the output more random; lower values make it more focused and deterministic. | 1.0 |
  419. | `top_p` | An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. | 1.0 |
  420. | `transcriptions_path` | The API endpoint for audio transcription requests. | '/v1/audio/transcriptions' |
  421. | `url` | The base URL for the API — **origin only** (scheme + host). The `*_path` values are appended to it, so don't include `/v1` here or requests will 404 with a doubled prefix (e.g. use `url: https://my-host` + `completions_path: /v1/chat/completions`). | 'https://api.openai.com' |
  422. | `user_agent` | The header used for the user agent in API requests. | 'chatgpt-cli' |
  423. | `voice` | The voice to use when generating audio with TTS models like gpt-4o-mini-tts. | 'nova' |
  424. | `response_format` | Structured output for the Chat Completions API: `json_object` for JSON mode, or a JSON Schema string to constrain the output. Empty disables it. | '' |
  425. | `tools` | Enable model-driven function calling. The model can call tools advertised by the `--mcp` endpoint and the CLI feeds results back until it answers. | `false` |
  426. | `max_tool_calls` | Maximum number of tool-call rounds per query before giving up (guards against a model that keeps calling tools). `0` uses the built-in default of 10. | `10` |
  427. ### Function calling & JSON mode
  428. * **JSON mode / structured output**: pass `--json` for plain JSON output
  429. (shorthand for `--response-format json_object`), or `--response-format
  430. '<schema>'` / `--response-format @schema.json` to constrain output to a JSON
  431. Schema. Also settable persistently via the `response_format` config. Note:
  432. OpenAI's `json_object` mode requires your prompt to mention "JSON" somewhere,
  433. otherwise the API rejects the request — phrase your request accordingly (a
  434. JSON Schema via `--response-format` does not have this constraint).
  435. * **Function calling**: pass `--tools` together with `--mcp <endpoint>` to let
  436. the model call that MCP server's tools autonomously. The CLI lists the
  437. server's tools (`tools/list`), advertises them to the model, dispatches each
  438. requested call (`tools/call`), and feeds the results back — looping until the
  439. model produces a final answer (bounded by `max_tool_calls`). This is a step up
  440. from the one-shot `--mcp-tool` context injection. Function calling forces
  441. non-streaming (`--query`) mode, since a tool call must be received in full
  442. before it can be dispatched.
  443. ### Agent Configuration
  444. | Variable | Description | Default |
  445. |------------------------------------|---------------------------------|-----------|
  446. | `agent` | Enable agent mode | `false` |
  447. | `agent.mode` | Strategy (`react` or `plan`) | `react` |
  448. | `agent.work_dir` | Working directory | `.` |
  449. | `agent.max_iterations` | Max ReAct iterations | `10` |
  450. | `agent.max_steps` | Max plan steps | `10` |
  451. | `agent.max_wall_time` | Max wall time (0 = unlimited) | `0` |
  452. | `agent.max_shell_calls` | Max shell calls (0 = unlimited) | `0` |
  453. | `agent.max_llm_calls` | Max LLM calls (0 = unlimited) | `10` |
  454. | `agent.max_file_ops` | Max file ops (0 = unlimited) | `0` |
  455. | `agent.max_llm_tokens` | Max LLM tokens (0 = unlimited) | `0` |
  456. | `agent.allowed_tools` | Allowed tools | see below |
  457. | `agent.denied_shell_commands` | Denied shell commands | see below |
  458. | `agent.allowed_file_ops` | Allowed file ops | see below |
  459. | `agent.restrict_files_to_work_dir` | Sandbox to workdir | `true` |
  460. | `agent.write_plan_json` | Write plan.json in plan mode | `true` |
  461. | `agent.plan_json_path` | Override plan.json path | `""` |
  462. | `agent.dry_run` | No side effects | `false` |
  463. You can also use flags, for example:
  464. ```shell
  465. chatgpt "what files are here?" --agent --agent-work-dir /tmp
  466. ```
  467. #### Default Policy
  468. ```yaml
  469. allowed_tools: [shell, llm, files]
  470. denied_shell_commands: [rm, sudo, dd, mkfs, shutdown, reboot]
  471. allowed_file_ops: [read, write]
  472. ```
  473. ### Custom Config, Cache and Data Directory
  474. By default, ChatGPT CLI stores configuration and history files in the `~/.chatgpt-cli` directory. However, you can
  475. easily override these locations by setting environment variables, allowing you to store configuration and history in
  476. custom directories.
  477. | Environment Variable | Description | Default Location |
  478. |----------------------|----------------------------------------------|--------------------------|
  479. | `OPENAI_CONFIG_HOME` | Overrides the default config directory path. | `~/.chatgpt-cli` |
  480. | `OPENAI_DATA_HOME` | Overrides the default data directory path. | `~/.chatgpt-cli/history` |
  481. | `OPENAI_CACHE_HOME` | Overrides the default cache directory path. | `~/.chatgpt-cli/cache` |
  482. #### Example for Custom Directories
  483. To change the default configuration or data directories, set the appropriate environment variables:
  484. ```
  485. export OPENAI_CONFIG_HOME="/custom/config/path"
  486. export OPENAI_DATA_HOME="/custom/data/path"
  487. export OPENAI_CACHE_HOME="/custom/cache/path"
  488. ```
  489. If these environment variables are not set, the application defaults to ~/.chatgpt-cli for configuration files and ~
  490. /.chatgpt-cli/history for history.
  491. ### Switching Between Configurations with --target
  492. You can maintain multiple configuration files side by side and switch between them using the `--target` flag. This is
  493. especially useful if you use multiple LLM providers (like OpenAI, Perplexity, Azure, etc.) or have different contexts or
  494. workflows that require distinct settings.
  495. How it Works
  496. When you use the `--target` flag, the CLI loads a config file named:
  497. ```shell
  498. config.<target>.yaml
  499. ```
  500. For example:
  501. ```shell
  502. chatgpt --target perplexity --config
  503. ```
  504. This will load:
  505. ```shell
  506. ~/.chatgpt-cli/config.perplexity.yaml
  507. ```
  508. If the --target flag is not provided, the CLI falls back to:
  509. ```shell
  510. ~/.chatgpt-cli/config.yaml
  511. ```
  512. Example Setup
  513. You can maintain the following structure:
  514. ```shell
  515. ~/.chatgpt-cli/
  516. ├── config.yaml # Default (e.g., OpenAI)
  517. ├── config.perplexity.yaml # Perplexity setup
  518. ├── config.azure.yaml # Azure-specific config
  519. └── config.llama.yaml # LLaMA setup
  520. ```
  521. Then switch between them like so:
  522. ```shell
  523. chatgpt --target azure "Explain Azure's GPT model differences"
  524. chatgpt --target perplexity "What are some good restaurants in the Red Hook area"
  525. ```
  526. Or just use the default:
  527. ```shell
  528. chatgpt "What's the capital of Sweden?"
  529. ```
  530. CLI and Environment Interaction
  531. * The value of `--target` is never persisted — it must be explicitly passed for each run.
  532. * The config file corresponding to the target is loaded before any environment variable overrides are applied.
  533. * Environment variables still follow the name: field inside the loaded config, so name: perplexity enables
  534. `PERPLEXITY_API_KEY`.
  535. #### Variables for interactive mode:
  536. - `%date`: The current date in the format `YYYY-MM-DD`.
  537. - `%time`: The current time in the format `HH:MM:SS`.
  538. - `%datetime`: The current date and time in the format `YYYY-MM-DD HH:MM:SS`.
  539. - `%counter`: The total number of queries in the current session.
  540. - `%usage`: The usage in total tokens used (only works in query mode).
  541. The defaults can be overridden by providing your own values in the user configuration file. The structure of this file
  542. mirrors that of the default configuration. For instance, to override
  543. the `model` and `max_tokens` parameters, your file might look like this:
  544. ```yaml
  545. model: gpt-3.5-turbo-16k
  546. max_tokens: 4096
  547. ```
  548. This alters the `model` to `gpt-3.5-turbo-16k` and adjusts `max_tokens` to `4096`. All other options, such as `url`
  549. , `completions_path`, and `models_path`, can similarly be modified.
  550. You can also add custom HTTP headers to all API requests. This is useful when working with proxies, API gateways, or
  551. services that require additional headers:
  552. ```yaml
  553. custom_headers:
  554. X-Custom-Header: "custom-value"
  555. X-API-Version: "v2"
  556. X-Client-ID: "my-client-id"
  557. ```
  558. If the user configuration file cannot be accessed or
  559. is missing, the application will resort to the default configuration.
  560. Another way to adjust values without manually editing the configuration file is by using environment variables.
  561. The `name` attribute forms the prefix for these variables. As an example, the `model` can be modified using
  562. the `OPENAI_MODEL` environment variable. Similarly, to disable history during the execution of a command, use:
  563. ```shell
  564. OPENAI_OMIT_HISTORY=true chatgpt what is the capital of Denmark?
  565. ```
  566. This approach is especially beneficial for temporary changes or for testing varying configurations.
  567. Moreover, you can use the `--config` or `-c` flag to view the present configuration. This handy feature allows users to
  568. swiftly verify their current settings without the need to manually inspect the configuration files.
  569. ```shell
  570. chatgpt --config
  571. ```
  572. Executing this command will display the active configuration, including any overrides instituted by environment
  573. variables or the user configuration file.
  574. To facilitate convenient adjustments, the ChatGPT CLI provides flags for swiftly modifying the `model`, `thread`
  575. , `context-window` and `max_tokens` parameters in your user configured `config.yaml`. These flags are `--set-model`
  576. , `--set-thread`, `--set-context-window` and `--set-max-tokens`.
  577. For instance, to update the model, use the following command:
  578. ```shell
  579. chatgpt --set-model gpt-3.5-turbo-16k
  580. ```
  581. This feature allows for rapid changes to key configuration parameters, optimizing your experience with the ChatGPT CLI.
  582. ### Azure Configuration
  583. For Azure, you need to configure these, or similar, value
  584. ```yaml
  585. name: azure
  586. api_key: <your azure api key>
  587. url: https://<your_resource>.openai.azure.com
  588. completions_path: /openai/deployments/<your_deployment>/chat/completions?api-version=<your_api>
  589. auth_header: api-key
  590. auth_token_prefix: " "
  591. ```
  592. You can set the API key either in the config.yaml file as shown above or export it as an environment variable:
  593. ```shell
  594. export AZURE_API_KEY=<your_key>
  595. ```
  596. ### Perplexity Configuration
  597. For Perplexity, you will need something equivelent to the following values:
  598. ```yaml
  599. name: perplexity
  600. api_key: <your perplexity api key>
  601. model: sonar
  602. url: https://api.perplexity.ai
  603. ```
  604. You can set the API key either in the config.yaml file as shown above or export it as an environment variable:
  605. ```shell
  606. export PERPLEXITY_API_KEY=<your_key>
  607. ```
  608. You can set the API key either in the `config.yaml` file as shown above or export it as an environment variable:
  609. ```shell
  610. export AZURE_API_KEY=<your_key>
  611. ```
  612. ### 302.AI Configuration
  613. I successfully tested 302.AI with the following values
  614. ```yaml
  615. name: ai302 # environment variables cannot start with numbers
  616. api_key: <your 302.AI api key>
  617. url: https://api.302.ai
  618. ```
  619. You can set the API key either in the config.yaml file as shown above or export it as an environment variable:
  620. ```shell
  621. export AI302_API_KEY=<your_key>
  622. ```
  623. ### Atlas Cloud Configuration
  624. [Atlas Cloud](https://www.atlascloud.ai) exposes an OpenAI-compatible API at `https://api.atlascloud.ai/v1`, giving
  625. access to 300+ models (DeepSeek, Llama, Qwen, and more) through a single endpoint. Because it speaks the OpenAI
  626. Chat Completions format, it works with ChatGPT CLI out of the box using the following values:
  627. ```yaml
  628. name: atlascloud
  629. api_key: <your Atlas Cloud api key>
  630. model: deepseek-ai/deepseek-v4-pro
  631. url: https://api.atlascloud.ai/v1
  632. ```
  633. You can set the API key either in the `config.yaml` file as shown above or export it as an environment variable:
  634. ```shell
  635. export ATLASCLOUD_API_KEY=<your_key>
  636. ```
  637. You can browse the full model catalog and create an API key from the [Atlas Cloud dashboard](https://www.atlascloud.ai).
  638. ### Command-Line Autocompletion
  639. Enhance your CLI experience with our new autocompletion feature for command flags!
  640. #### Enabling Autocompletion
  641. Autocompletion is currently supported for the following shells: Bash, Zsh, Fish, and PowerShell. To activate flag
  642. completion in your current shell session, execute the appropriate command based on your shell:
  643. - **Bash**
  644. ```bash
  645. . <(chatgpt --set-completions bash)
  646. ```
  647. - **Zsh**
  648. ```zsh
  649. . <(chatgpt --set-completions zsh)
  650. ```
  651. - **Fish**
  652. ```fish
  653. chatgpt --set-completions fish | source
  654. ```
  655. - **PowerShell**
  656. ```powershell
  657. chatgpt --set-completions powershell | Out-String | Invoke-Expression
  658. ```
  659. #### Persistent Autocompletion
  660. For added convenience, you can make autocompletion persist across all new shell sessions by adding the appropriate
  661. sourcing command to your shell's startup file. Here are the files typically used for each shell:
  662. - **Bash**: Add to `.bashrc` or `.bash_profile`
  663. - **Zsh**: Add to `.zshrc`
  664. - **Fish**: Add to `config.fish`
  665. - **PowerShell**: Add to your PowerShell profile script
  666. For example, for Bash, you would add the following line to your `.bashrc` file:
  667. ```bash
  668. . <(chatgpt --set-completions bash)
  669. ```
  670. This ensures that command flag autocompletion is enabled automatically every time you open a new terminal window.
  671. ## Markdown Rendering
  672. You can render markdown in real-time using the `mdrender.sh` script, located [here](scripts/mdrender.sh). You'll first
  673. need to
  674. install [glow](https://github.com/charmbracelet/glow).
  675. Example:
  676. ```shell
  677. chatgpt write a hello world program in Java | ./scripts/mdrender.sh
  678. ```
  679. ## Development
  680. To start developing, set the `OPENAI_API_KEY` environment variable to
  681. your [ChatGPT secret key](https://platform.openai.com/account/api-keys).
  682. ### Using the Makefile
  683. The Makefile simplifies development tasks by providing several targets for testing, building, and deployment.
  684. * **all-tests**: Run all tests, including linting, formatting, and go mod tidy.
  685. ```shell
  686. make all-tests
  687. ```
  688. * **binaries**: Build binaries for multiple platforms.
  689. ```shell
  690. make binaries
  691. ```
  692. * **shipit**: Run the release process, create binaries, and generate release notes.
  693. ```shell
  694. make shipit
  695. ```
  696. * **updatedeps**: Update dependencies and commit any changes.
  697. ```shell
  698. make updatedeps
  699. ```
  700. For more available commands, use:
  701. ```shell
  702. make help
  703. ```
  704. #### Windows build script
  705. ```ps1
  706. .\scripts\install.ps1
  707. ```
  708. ### Testing the CLI
  709. 1. After a successful build, test the application with the following command:
  710. ```shell
  711. ./bin/chatgpt what type of dog is a Jack Russel?
  712. ```
  713. 2. As mentioned previously, the ChatGPT CLI supports tracking conversation history across CLI calls. This feature
  714. creates a seamless and conversational experience with the GPT model, as the history is utilized as context in
  715. subsequent interactions.
  716. To enable this feature, you need to create a `~/.chatgpt-cli` directory using the command:
  717. ```shell
  718. mkdir -p ~/.chatgpt-cli
  719. ```
  720. ## Reporting Issues and Contributing
  721. If you encounter any issues or have suggestions for improvements,
  722. please [submit an issue](https://github.com/kardolus/chatgpt-cli/issues/new) on GitHub. We appreciate your feedback and
  723. contributions to help make this project better.
  724. ## Uninstallation
  725. If for any reason you wish to uninstall the ChatGPT CLI application from your system, you can do so by following these
  726. steps:
  727. ### Using Homebrew (macOS)
  728. If you installed the CLI using Homebrew you can do:
  729. ```shell
  730. brew uninstall chatgpt-cli
  731. ```
  732. And to remove the tap:
  733. ```shell
  734. brew untap kardolus/chatgpt-cli
  735. ```
  736. ### MacOS / Linux
  737. If you installed the binary directly, follow these steps:
  738. 1. Remove the binary:
  739. ```shell
  740. sudo rm /usr/local/bin/chatgpt
  741. ```
  742. 2. Optionally, if you wish to remove the history tracking directory, you can also delete the `~/.chatgpt-cli` directory:
  743. ```shell
  744. rm -rf ~/.chatgpt-cli
  745. ```
  746. ### Windows
  747. 1. Navigate to the location of the `chatgpt` binary in your system, which should be in your PATH.
  748. 2. Delete the `chatgpt` binary.
  749. 3. Optionally, if you wish to remove the history tracking, navigate to the `~/.chatgpt-cli` directory (where `~` refers
  750. to your user's home directory) and delete it.
  751. Please note that the history tracking directory `~/.chatgpt-cli` only contains conversation history and no personal
  752. data. If you have any concerns about this, please feel free to delete this directory during uninstallation.
  753. ## Useful Links
  754. * [Amazing Prompts](https://github.com/kardolus/prompts)
  755. * [OpenAI API Reference](https://platform.openai.com/docs/api-reference/chat/create)
  756. * [OpenAI Key Usage Dashboard](https://platform.openai.com/account/usage)
  757. * [OpenAI Pricing Page](https://openai.com/pricing)
  758. * [Perplexity API Reference](https://docs.perplexity.ai/reference/post_chat_completions)
  759. * [Perplexity Key Usage Dashboard](https://www.perplexity.ai/settings/api)
  760. * [Perplexity Models](https://docs.perplexity.ai/docs/model-cards)
  761. * [302.AI API Reference](https://302ai-en.apifox.cn/api-207705102)
  762. ## Additional Resources
  763. * ["Summarize any text instantly with a single shortcut"](https://medium.com/@kardolus/summarize-any-text-instantly-with-a-single-shortcut-582551bcc6e2)
  764. on Medium: Dive deep into the capabilities of this CLI tool with this detailed walkthrough.
  765. * [Join the conversation](https://www.reddit.com/r/ChatGPT/comments/14ip6pm/summarize_any_text_instantly_with_a_single/)
  766. on Reddit: Discuss the tool, ask questions, and share your experiences with our growing community.
  767. Thank you for using ChatGPT CLI!
  768. <div align="center" style="text-align: center; display: flex; justify-content: center; align-items: center;">
  769. <a href="#top">
  770. <img src="https://img.shields.io/badge/Back%20to%20Top-000000?style=for-the-badge&logo=github&logoColor=white" alt="Back to Top">
  771. </a>
  772. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.