TOOLS4AGENTSRelease

Gemini CLI v0.69.0

Gemini CLI v0.69.0: What Changed and How to Get It

2
Features
28
Fixes
3
Other changes
Published 2026-11-19 · Last verified 2026-11-19

Gemini CLI v0.69.0 adds a /stats heatmap for daily token usage and custom theme.json support, plus fixes for templates, files, and timeouts.

You run Gemini CLI all day and you want to know where your tokens go. A $ sign in your prompt gets mangled, a file reference loses its spacing, or a network hiccup leaves the terminal hanging. Release v0.69.0 of Gemini CLI is a maintenance release with two new features and a long list of fixes aimed at these daily annoyances. This post covers what the release notes say changed, who is affected, and how to get it.

What it is

Gemini CLI is a command line tool from Google that puts a Gemini agent in your terminal. Release v0.69.0 is a version bump of that tool. The release notes list the pull requests that went into it, grouped by area: core, cli, vscode, and acp.

Two items are new features. The rest are fixes.

The first feature is a /stats heatmap subcommand for daily token usage. It gives you a view of how many tokens you use each day, shown as a heatmap.

The second feature is support for a standalone theme.json configuration file for custom themes. You can define your own theme in a file instead of relying only on built-in options.

The release also includes a version bump commit that sets the version to 0.69.0-nightly.20261104.g89e9d25d6, and changelog entries for v0.67.0 and v0.68.0-preview.0.

What this release contains
What this release contains, in changes
Namechanges
Features
2
Fixes
28
Other changes
3

Why it matters

The release notes frame each change as a fix to a specific problem. Here is what they claim, said plainly.

Template placeholders no longer eat literal $ characters. If your prompt or template contains a dollar sign, it stays as written.

The /stats heatmap gives you a daily view of token usage, so you can see your consumption pattern over time.

An environment variable collision in expandEnvVars is fixed. The notes name the variable: __GCLI_EXPAND_TARGET__. The fix prevents that name from colliding during environment variable expansion.

ACP tool call updates now serialize AnsiOutput to text content. If you use the Agent Client Protocol path, tool call updates arrive as text rather than raw ANSI output.

Windows PowerShell substitution false positives and policy handling are fixed. If you work on Windows, this affects how substitutions are detected and how policy is applied.

Leading and trailing whitespace in @file references is preserved. When you point the agent at a file with @, the spacing around the reference survives.

Thought signature only turns are prevented, and multimodal tool responses are preserved.

Piped stdin now waits for EOF and no longer destroys process.stdin. If you pipe input into the CLI, this changes how the process handles that stream.

A pending tool confirmation is preserved when you escape an editor selection. You do not lose the confirmation prompt by pressing escape.

Error payloads in headless CLI formatting are normalized. If you run the CLI headless, error output is formatted consistently.

tildeifyPath now requires a path separator boundary. This is a path handling fix in core.

The /model command now validates model names and supports direct arguments. You can pass a model name directly to the command, and invalid names are checked.

File watcher errors are handled, and FSEvents are permitted in the macOS permissive sandbox.

Multi-part tool outputs are bounded, and older multimodal inlineData is evicted. This is a memory handling fix for tool outputs.

The VS Code extension gets a fix for barrel import bundle bloat and redundant setContext calls.

Mid-stream retries in ACP are handled to prevent text concatenation. If a retry happens mid-stream, text does not get glued together.

Silent multi-minute loading hangs on network failures are prevented.

Terminal model-turn 400s on resume and main-thread JSONL freezes are prevented.

Multi-hour quota retries are prevented, and the ACP client is notified on retry attempts. Instead of retrying for hours, the client gets told about the retry.

An orphan /dev/ptmx master file descriptor leaked on macOS PTY spawn is closed.

The 60 second API headers timeout can now be overridden across all auth modes. The notes give two names for this: the model.requestTimeoutMs setting and the GEMINI_API_HEADERS_TIMEOUT_MS environment variable.

The theme file home directory check now uses isSubpath. This is a safety check on where theme files live.

Folder trust is resolved before entering the macOS Seatbelt sandbox.

On headless abort, child processes are killed, cancelled tools are recorded, and the signal exit code is preserved.

Recursive interactive gemini sessions in shell mode are prevented.

MessageBus.request() is rejected immediately when publish fails. Instead of waiting, the request fails fast.

Read-many-files only inlines explicitly requested binary assets. The notes reference issue #29045.

TortoiseGitPlink is recognized as a PuTTY family SSH client. The notes reference issue #29917.

PDF inlineData and telemetry buffer memory retention are prevented.

Step by step

The release notes do not include install commands. They list the changes and link to a full changelog comparing v0.68.0 to v0.69.0. So the steps below cover what the notes do say: how to find the release, how to read the changelog, and how to use the two new features.

  1. Open the release page.The notes live at the v0.69.0 release tag on the gemini-cli GitHub repository. Read the "What's Changed" list to see every pull request in the release.
  1. Read the full changelog.The notes link a comparison between v0.68.0 and v0.69.0. That comparison shows the complete set of commits between the two versions.
  1. Check your current version.The release notes do not give a command for this. Use whatever version check your install method provides, then compare it to v0.69.0.
  1. Update to v0.69.0.The notes do not state an install or update command. Use the update path for the way you installed Gemini CLI. The notes only confirm that v0.69.0 exists as a tag and that the version was bumped in the release commit.
  1. Try the new stats heatmap.The release adds a /stats heatmap subcommand for daily token usage. Inside an interactive session, the notes describe it as a subcommand of /stats. The notes do not give the exact argument syntax, so check the command's own help output in your session.
  1. Set up a custom theme with theme.json. The release adds support for a standalone theme.json configuration file for custom themes. The notes do not give the file's location or schema. They do state that a theme file home directory check now uses isSubpath, which tells you theme files are checked against a home directory path.
  1. If you use ACP, note the retry behavior change.The ACP client is now notified on retry attempts, and mid-stream retries no longer concatenate text. If your client handles retry notifications, review that handling against this release.
  1. If you hit slow networks, note the timeout override.The 60 second API headers timeout can be overridden with the model.requestTimeoutMs setting or the GEMINI_API_HEADERS_TIMEOUT_MS environment variable, across all auth modes.
  1. If you run headless, check your abort handling.On headless abort, child processes are killed, cancelled tools are recorded, and the signal exit code is preserved. If your scripts read exit codes, this release changes what they see on abort.
  1. If you are on Windows, recheck PowerShell behavior.The release fixes Windows PowerShell substitution false positives and policy handling. If you had workarounds for false positives, review them against this release.

A worked example

Here is a scenario built only from features the release notes describe.

A developer uses Gemini CLI every day and wants to see how their token usage looks across days. Before this release, the notes do not describe a daily heatmap view. After updating to v0.69.0, they open an interactive session and use the /stats heatmap subcommand. The tool shows daily token usage as a heatmap. The developer can see which days were heavy and which were light.

The same developer has a prompt template that includes a dollar amount, for example a pricing string with a $ in it. Before this release, the notes say literal $ characters were not preserved during template placeholder replacement. After the fix, the $ stays as written.

Next, the developer references a file with @file and the file path has spaces around it in the prompt. Before this release, leading and trailing whitespace in @file references was not preserved. After the fix, the spacing survives.

Then the developer wants a custom look for the terminal. They create a standalone theme.json configuration file for a custom theme, a feature added in this release. The theme file home directory check uses isSubpath, so the file is checked against the home directory path.

Later, the developer's network drops mid-session. Before this release, the notes describe silent multi-minute loading hangs on network failures. After the fix, that hang is prevented. If a quota retry happens, it no longer runs for multiple hours, and the ACP client is notified on retry attempts.

Finally, the developer runs a headless job and aborts it. On abort, child processes are killed, cancelled tools are recorded, and the signal exit code is preserved. Their script reads the exit code and sees the signal code rather than a generic failure.

Each step above maps to a specific line in the release notes. Nothing in the scenario goes beyond what the notes state.

Pitfalls

The notes do not state costs, required keys, or required accounts for this release. They mention auth modes in the context of the timeout override, but they do not list which modes exist or what each needs.

The notes mention several platform specific behaviors. The macOS fixes cover FSEvents in the permissive sandbox, folder trust before the Seatbelt sandbox, and an orphan /dev/ptmx file descriptor on PTY spawn. The Windows fix covers PowerShell substitution false positives and policy handling. If you are not on those platforms, those fixes do not apply to you.

The notes mention an environment variable name, __GCLI_EXPAND_TARGET__, only as the name that used to collide. Do not treat it as a setting to configure.

The timeout override uses two names: model.requestTimeoutMs and GEMINI_API_HEADERS_TIMEOUT_MS. The notes say the override works across all auth modes, but they do not state default values beyond the 60 second headers timeout.

The release includes a nightly version string, 0.69.0-nightly.20261104.g89e9d25d6, in the version bump commit. That is the commit's version label, not a separate product.

Some fixes reference issue numbers, #29045 and #29917. The notes do not include the issue text, so read those issues if you need the full background.

FAQ

Does this release add new commands?

Yes. It adds a /stats heatmap subcommand for daily token usage. It also adds support for a standalone theme.json configuration file for custom themes.

Will my dollar signs in templates still break?

The release fixes literal $ characters being lost during template placeholder replacement. The notes state the fix preserves them.

Can I change the 60 second API headers timeout?

Yes. The notes say the 60 second API headers timeout can be overridden across all auth modes using model.requestTimeoutMs or GEMINI_API_HEADERS_TIMEOUT_MS.

What changes for headless runs?

On headless abort, child processes are killed, cancelled tools are recorded, and the signal exit code is preserved. Error payloads in headless CLI formatting are also normalized.

Does this release fix Windows PowerShell issues?

Yes. The notes list a fix for Windows PowerShell substitution false positives and policy handling.

Verdict

Use this release if you use Gemini CLI daily and any of the listed problems sound familiar. If your prompts contain $ characters, if your @file references lose spacing, if you pipe input into the CLI, if you run headless jobs and abort them, if you work on Windows with PowerShell, or if you use the macOS sandbox, the notes list a fix aimed at your case. If you want a daily view of token usage, the /stats heatmap is the reason to update. If you want your own terminal theme, the theme.json support is the other reason.

Skip it if none of the listed problems affect you and you do not need the two new features. This is a maintenance release, and the notes describe fixes to specific behaviors rather than a broad change to how the tool works. Also skip it if you need install commands or exact feature syntax from the release notes alone, because the notes do not provide them. You will need your install method's update path and the tool's own help output to finish the job.