gemiterm 2.1.0 → 2.2.0-beta.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GemiTerm contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,268 +1,337 @@
+<div align="center">
+
 # GemiTerm
 
-Access and manage your Gemini web chats from the command line. GemiTerm bridges Playwright-based Google authentication to let you list, fetch, export, continue, and delete conversations trapped in the Gemini web interface — without a standard API. Built with [Bun](https://bun.sh) and TypeScript.
+### Google Gemini in your terminal — list, search, export, continue, and debate from the command line.
 
-## Prerequisites
+[![npm version](https://img.shields.io/npm/v/gemiterm?color=cb3837&label=npm)](https://www.npmjs.com/package/gemiterm)
+[![Bun](https://img.shields.io/badge/Runtime-Bun-f9f1e1?logo=bun&logoColor=black)](https://bun.sh)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Strict-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-22c55e)](LICENSE.md)
+[![Platforms](https://img.shields.io/badge/Platforms-Windows%20%7C%20Linux%20%7C%20macOS-6366f1)](#installation)
 
-- **[Bun](https://bun.sh)** runtime ≥ 1.0.0
-- **Chromium Browser** — GemiTerm uses your system Chrome/Edge if available, otherwise installs Playwright's Chromium automatically
-- **Google Account** with access to [Gemini](https://gemini.google.com)
+**List · Search · Export · Continue · Debate · Automate**
 
-## Quick Start (no install)
+[Quick Start](#quick-start) · [Features](#features) · [Cross-Agent Debates](#cross-agent-debates-with-gemini) · [Commands](#commands) · [Configuration](#configuration) · [Contributing](#contributing) · [Acknowledgements](#acknowledgments)
 
-Use `bunx` to run GemiTerm directly — no install step needed:
+</div>
 
-```bash
-bunx gemiterm auth          # authenticate with Google
-bunx gemiterm list          # list your chats
-```
+---
 
-## Installation
+## What is GemiTerm?
 
-### Global install (recommended for daily use)
+[Gemini](https://gemini.google.com) is one of the most capable AI assistants available — and almost all of your best conversations with it live **trapped inside the web UI**, with no public API to reach them. GemiTerm is the bridge.
 
-```bash
-bun install gemiterm -g
-```
+It's a fast, scriptable command-line client for the **Google Gemini web app**. Authenticate once, then list, search, fetch, export, continue, and delete chats from your shell. Pipe JSON into other tools. Wire it into CI. Or hand it to your AI coding agent and let it argue trade-offs with Gemini in real time.
 
-Then use from anywhere:
+GemiTerm is built with **[Bun](https://bun.sh)** and TypeScript, ships as a single native binary, and authenticates via Playwright — no Google API key, no rate limits, no quota.
 
-```bash
-gemiterm auth
-gemiterm list
-```
+> **TL;DR:** If you've ever wanted to `grep` your Gemini history, bulk-export months of chats, or have your coding agent debate Gemini about architecture before you commit — GemiTerm is for you.
 
-### Install scripts (binary drop)
+## Why GemiTerm?
 
-For systems without Bun — the script auto-bootstraps Bun if needed.
+- **No public API? No problem.** GemiTerm drives the real Gemini web app via a headless browser. It sees exactly what you see, including your entire history.
+- **Cross-agent debates built-in.** Spin up a `debate-with-gemini` skill and your coding agent (Claude Code, OpenCode, GitHub Copilot, …) will argue both sides of a technical decision with real Gemini responses, for N rounds. Catch design flaws before they ship.
+- **Scriptable & pipeable.** First-class `text` and `json` output. Works in cron jobs, Makefiles, shell loops, and CI.
+- **Searchable archive.** Bulk-export to Markdown or JSON and run `grep`, `rg`, or your favorite search tool over months of AI conversations.
+- **Multi-profile, multi-account.** Keep work, personal, and side-project identities separate. One CLI, many Gemini accounts.
+- **Single binary, every OS.** Native builds for Windows, Linux, and macOS. No Node, no Python, no runtime to install.
+- **Local-first, private.** Cookies never leave your machine. 7-day freshness window. You own your data.
 
-**Windows** (PowerShell 7+):
+## Features
 
-```powershell
-irm https://github.com/expert-vision-software/GemiTerm/releases/latest/download/install.ps1 | iex
-```
+- 🔍 **List & search** — find any Gemini chat by title, date, or content (`--sort`, `--after`, `--before`, `--search`, `--all`, `--all-profiles`)
+- 📥 **Bulk export** — Markdown or JSON, indexed `index.md`, ready for grep and archival
+- 💬 **Continue or start** — interactive REPL or one-shot, with `--prompt-file` for long prompts
+- 🗑️ **Delete with confirmation** — clean up old chats safely (`--force` to skip)
+- 👤 **Multi-profile** — separate identities for work / personal / side-projects, one-click switching
+- 🤖 **AI-agent skills** — plug into OpenCode, Claude Code, GitHub Copilot, and any agent that reads skills
+- 🗣️ **Cross-agent debates** — your agent argues both sides with Gemini, surfaces real agreements and disagreements
+- 📦 **Single binary** — Bun-compiled, no runtime required; works on Windows, Linux, macOS
+- 🔐 **Local cookies** — never uploaded; 7-day freshness window
 
-**Linux / WSL**:
+## Cross-Agent Debates with Gemini
 
-```bash
-curl -fsSL https://github.com/expert-vision-software/GemiTerm/releases/latest/download/install.sh | bash
-```
+The killer feature isn't just CLI access — it's what your **AI coding agent** can do with it.
 
-See [docs/INSTALL.md](docs/INSTALL.md) for the full guide, uninstall instructions, troubleshooting, and build-from-source steps.
+GemiTerm ships with a companion **skills package** (`opencode-gemiterm-skills`) that teaches any LLM-powered terminal how to use GemiTerm on demand. Two skills are included:
 
-> **Upgrading from v1.4.1?** Your profiles, cookies, and default profile marker are preserved. See the "Upgrade from v1.4.1" section in [docs/INSTALL.md](docs/INSTALL.md) for details.
+| Skill | What it does |
+| --- | --- |
+| **`gemiterm`** | Search, list, export, and manage your Gemini chats from inside an agent session. |
+| **`debate-with-gemini`** | Run structured multi-turn technical debates with Gemini — perfect for stress-testing architecture decisions, trade-offs, and design choices. |
 
-## Development
+Install in one command:
 
 ```bash
-bun install
-bun run dev              # run the CLI
-bun test                 # run tests (Bun test runner)
-bun run typecheck        # TypeScript type checking
-bun run build            # compile to standalone Bun binary
-bun run build:linux      # cross-compile for Linux x64
-bun run build:windows    # cross-compile for Windows x64
+gemiterm install-skills
+# or, for any agent that supports the skills CLI
+bunx opencode-gemiterm-skills install
 ```
 
-For installing Chromium, use the platform-specific wrapper scripts:
-```bash
-bash scripts/install-browser.sh   # Linux/macOS
-pwsh scripts/install-browser.ps1 # Windows
-```
+Then in your agent session, just ask:
 
-## Building from source
+> **You:** "Debate Gemini for/against using SQLite as the primary database for a SaaS app. Context: docs/arch.md. 5 turns."
 
-GemiTerm is built with [Bun](https://bun.sh) 1.3.13 or later.
+The agent reads your context, seeds a fresh Gemini chat with the opposing view, and runs a 5-round autonomous back-and-forth:
 
-```bash
-bun run build            # native binary (dist/gemiterm or dist/gemiterm.exe)
-bun run build:linux      # Linux x64 binary (dist/gemiterm)
-bun run build:windows    # Windows x64 binary (dist/gemiterm.exe)
-bun run build:release    # minified release binary (dist/gemiterm)
+```
+Debate complete (5 turns). Gemini argued FOR SQLite (simplicity, zero-config).
+I argued AGAINST (concurrency limits, no network access, scaling ceiling).
+Key agreements: fine for prototyping, migrate to Postgres before 100+ concurrent users.
 ```
 
-Output paths:
-- **Linux/macOS**: `dist/gemiterm`
-- **Windows**: `dist/gemiterm.exe`
+Other use cases for `debate-with-gemini`:
 
-## Release artifacts
+- **Validate API design** — "Have Gemini argue against this REST contract. 3 turns."
+- **Review a refactor** — "Stress-test the migration to event-sourcing with Gemini. 4 turns."
+- **Compare libraries** — "Argue both sides of `Zod` vs. `valibot` for this schema. 3 turns."
+- **Continue a previous debate** — "Resume chat `c_abc123` for 3 more turns."
 
-The v2.0.0 release ships the following GitHub Release assets:
-- `GemiTerm` — Linux x64 binary
-- `GemiTerm.exe` — Windows x64 binary
-- `install.sh` — POSIX installer script
-- `install.ps1` — Windows PowerShell installer script
+The full skill bundle lives at [`opencode-gemiterm-skills`](https://www.npmjs.com/package/opencode-gemiterm-skills).
 
-## Usage
+## Quick Start
 
-### Authentication
+### Try without installing
 
 ```bash
-gemiterm auth
+bunx gemiterm auth          # sign in to Google
+bunx gemiterm list          # show your recent chats
 ```
 
-Opens a browser window to log in with your Google account. Cookies are saved for future use.
-
-### Check Status
+### Install globally (recommended for daily use)
 
 ```bash
-gemiterm status
+bun install -g gemiterm
+
+gemiterm auth
+gemiterm list
 ```
 
-Shows the config directory and a table of all profiles with their authentication state.
+### Install scripts (no Bun required — bootstraps it for you)
 
-### List Chats
+**Windows (PowerShell 7+):**
 
-```bash
-gemiterm list
+```powershell
+irm https://github.com/expert-vision-software/GemiTerm/releases/latest/download/install.ps1 | iex
 ```
 
-Options:
-- `-n, --limit N`: Maximum number of chats (default: 10)
-- `--offset N`: Skip first N chats (default: 0)
-- `--sort <recent|oldest|alpha>`: Sort order
-- `-s, --search <query>`: Filter by title
-- `--after <date>`: Only chats after this date
-- `--before <date>`: Only chats before this date
-- `--all`: Show all chats (no limit)
-- `--all-profiles`: Merge chats from all profiles
-- `-f, --format <text|json>`: Output format
-- `-p, --path <path>`: Save output to file
-
-### Fetch Chat History
+**Linux / macOS:**
 
 ```bash
-gemiterm fetch <conversation_id>
+curl -fsSL https://github.com/expert-vision-software/GemiTerm/releases/latest/download/install.sh | bash
 ```
 
-Options:
-- `-f, --format <text|json>`: Output format
-- `-p, --path <path>`: Save output to file
+> **Upgrading from v1.4.1?** Your profiles, cookies, and default profile marker are preserved. See [docs/INSTALL.md](docs/INSTALL.md) for details.
+
+See [docs/INSTALL.md](docs/INSTALL.md) for the full guide, uninstall instructions, troubleshooting, and build-from-source steps.
+
+## Prerequisites
+
+- **[Bun](https://bun.sh)** runtime ≥ 1.0.0 (only required for `bunx` / `bun install` use — not needed for install scripts)
+- **Chromium browser** — GemiTerm prefers your system Chrome / Edge; otherwise it installs Playwright's Chromium automatically (`gemiterm install-browser`)
+- **Google Account** with access to [Gemini](https://gemini.google.com)
 
-### Continue a Chat
+## Commands
+
+| Command | Alias | Purpose |
+| --- | --- | --- |
+| `gemiterm auth` | `gemiterm login` | Sign in to Google and save cookies |
+| `gemiterm status` | — | Show config dir and profile table |
+| `gemiterm list` | — | List chats (filter, sort, search) |
+| `gemiterm fetch <id>` | — | Fetch a chat's full history |
+| `gemiterm new [message]` | — | Start a new chat (one-shot or REPL) |
+| `gemiterm continue <id> [msg]` | — | Continue an existing chat |
+| `gemiterm export <id>` | — | Export one chat to Markdown / JSON |
+| `gemiterm export-all` | — | Bulk-export all chats with `index.md` |
+| `gemiterm delete <id>` | — | Delete a chat (with confirmation) |
+| `gemiterm profile <sub>` | — | Manage profiles (list / add / delete / rename / default) |
+| `gemiterm install-browser` | — | Install Playwright Chromium |
+| `gemiterm install-skills` | — | Install the cross-agent skills bundle |
+| `gemiterm -v <cmd>` | — | Verbose logging for any command |
+
+### `gemiterm list`
+
+List, filter, and search your Gemini chats.
 
 ```bash
-gemiterm continue <conversation_id> [message]
+gemiterm list
+gemiterm list -n 50 --sort alpha
+gemiterm list --search "react server components"
+gemiterm list --after 2026-01-01 --before 2026-06-01
+gemiterm list --all --all-profiles -f json -p chats.json
 ```
 
-Without a message, enters an interactive REPL session. Without a conversation ID, falls back to `list`.
+| Flag | Description |
+| --- | --- |
+| `-n, --limit N` | Max chats to show (default: 10) |
+| `--offset N` | Skip the first N chats |
+| `--sort <recent\|oldest\|alpha>` | Sort order |
+| `-s, --search <query>` | Filter by title |
+| `--after <date>` | Only chats after this date |
+| `--before <date>` | Only chats before this date |
+| `--all` | Show all chats (no limit) |
+| `--all-profiles` | Merge chats from all profiles |
+| `-f, --format <text\|json>` | Output format |
+| `-p, --path <path>` | Save output to file |
 
-### Start a New Chat
+### `gemiterm fetch <conversation_id>`
+
+Fetch a single conversation's full history.
 
 ```bash
-gemiterm new [message]
+gemiterm fetch c_abc123
+gemiterm fetch c_abc123 -f json -p chat.json
 ```
 
-Options:
-- `-p, --profile <name>`: Use a specific profile
+| Flag | Description |
+| --- | --- |
+| `-f, --format <text\|json>` | Output format |
+| `-p, --path <path>` | Save output to file |
 
-Without a message, enters an interactive REPL session.
+### `gemiterm new [message]`
 
-### Export Chat
+Start a new chat. One-shot if you pass a message; otherwise drops into an interactive REPL.
 
 ```bash
-gemiterm export <conversation_id>
+gemiterm new "Explain the CAP theorem like I'm 12"
+gemiterm new --profile work "Draft a status update"
+gemiterm new --prompt-file ./long-prompt.md
 ```
 
-Options:
-- `-o, --output <path>`: Custom output file path
-- `-f, --format <markdown|json>`: Export format (default: markdown)
-- `--include-metadata`: Include full metadata in export
+| Flag | Description |
+| --- | --- |
+| `-p, --profile <name>` | Use a specific profile |
+| `-f, --prompt-file <path>` | Read the message from a file (bypasses shell arg-length limits) |
+| `-h, --help` | Show help |
+
+### `gemiterm continue <conversation_id> [message]`
 
-### Export All Chats
+Continue an existing chat. With no message, enters an interactive REPL. With no conversation ID, falls back to `list`.
 
 ```bash
-gemiterm export-all
+gemiterm continue c_abc123
+gemiterm continue c_abc123 "And what about edge cases?"
+gemiterm continue c_abc123 --prompt-file ./refactor-context.md
 ```
 
-Options:
-- `-o, --output-dir <dir>`: Output directory (default: `./exports`)
-- `--since <date>`: Only chats newer than this date
-- `--include-metadata`: Include full metadata
-- `-a, --all-profiles`: Export from all profiles
+| Flag | Description |
+| --- | --- |
+| `-f, --prompt-file <path>` | Read the message from a file (bypasses shell arg-length limits) |
+| `-h, --help` | Show help |
 
-Creates an `index.md` with links to all exported files.
+> **Long prompts?** On Windows the shell argument limit is roughly 2 048 UTF-16 code units. GemiTerm detects oversized messages and **spills them to a temp file automatically** — or you can use `--prompt-file` explicitly to read from a file you control.
 
-### Delete a Chat
+### `gemiterm export <conversation_id>`
+
+Export a single chat to a file.
 
 ```bash
-gemiterm delete <conversation_id>
+gemiterm export c_abc123
+gemiterm export c_abc123 -o ./chat.md -f json --include-metadata
 ```
 
-Options:
-- `-f, --force`: Skip confirmation prompt
+| Flag | Description |
+| --- | --- |
+| `-o, --output <path>` | Custom output file path |
+| `-f, --format <markdown\|json>` | Export format (default: `markdown`) |
+| `--include-metadata` | Include full metadata in the export |
+
+### `gemiterm export-all`
 
-### Manage Profiles
+Bulk-export every chat (or every chat since a date) with an auto-generated `index.md`.
 
 ```bash
-gemiterm profile list                    # list all profiles
-gemiterm profile add <name>               # add a new profile
-gemiterm profile delete <name>            # delete a profile
-gemiterm profile rename <name> <newName>  # rename a profile
-gemiterm profile default <name>          # set default profile
+gemiterm export-all
+gemiterm export-all --since 2026-01-01 --include-metadata
+gemiterm export-all -o ./exports -a
 ```
 
-### Install Browser
+| Flag | Description |
+| --- | --- |
+| `-o, --output-dir <dir>` | Output directory (default: `./exports`) |
+| `--since <date>` | Only chats newer than this date |
+| `--include-metadata` | Include full metadata |
+| `-a, --all-profiles` | Export from all profiles |
+
+### `gemiterm delete <conversation_id>`
+
+Delete a chat from your Gemini account. Confirms by default.
 
 ```bash
-gemiterm install-browser
+gemiterm delete c_abc123
+gemiterm delete c_abc123 --force
 ```
 
-Checks for system Chrome/Edge first, falls back to installing Playwright's Chromium.
+| Flag | Description |
+| --- | --- |
+| `-f, --force` | Skip the confirmation prompt |
+
+### `gemiterm profile <subcommand>`
 
-### Verbose Logging
+Manage multiple Gemini profiles (separate Google accounts or isolated cookie stores).
 
 ```bash
-gemiterm -v <command>
+gemiterm profile list
+gemiterm profile add work
+gemiterm profile delete work
+gemiterm profile rename work jobs
+gemiterm profile default work
 ```
 
-## Skills
+### `gemiterm install-browser`
+
+Checks for a system Chrome / Edge first; falls back to Playwright's Chromium. Usually only needed once after install.
+
+### `gemiterm install-skills`
 
-GemiTerm has an associated skills repository for AI coding agents (Copilot, Claude, etc.) that provides domain-specific instructions for working with **gemiterm** and automating common workflows. There's also a fun `debate-with-gemini` skill that created an interactive turn-based conversation between your agent and gemini. See [opencode-gemiterm-skills](https://www.npmjs.com/package/opencode-gemiterm-skills).
+Installs the [`opencode-gemiterm-skills`](https://www.npmjs.com/package/opencode-gemiterm-skills) bundle so your AI agent can use GemiTerm (and the `debate-with-gemini` skill) automatically.
 
 ## Configuration
 
-### Configuration Directory
+### Configuration directory
 
-Default locations:
-- **Binary**: `$env:LOCALAPPDATA\GemiTerm\` (Windows), `~/.local/bin/gemiterm` (Linux/macOS)
-- **Config**: `%APPDATA%\gemiterm\` (Windows), `~/gemiterm/` (Linux/macOS)
+| Platform | Config dir | Binary location (install script) |
+| --- | --- | --- |
+| Windows | `%APPDATA%\gemiterm\` | `%LOCALAPPDATA%\GemiTerm\` |
+| Linux / macOS | `~/gemiterm/` | `~/.local/bin/gemiterm` |
 
 Override with:
+
 ```bash
 export GEMITERM_CONFIG_DIR=/custom/path
 ```
 
-### Profile Storage
+### Profile storage
 
 ```
 gemiterm/
   profiles/
-    .default              # text file with default profile name
+    .default              # text file with the default profile name
     <profile-name>/
-      storage_state.json  # authentication cookies
+      storage_state.json  # authenticated cookies
 ```
 
-### Environment Variables
+Upgrading from v1.4.1 keeps these paths and files unchanged.
+
+### Environment variables
 
 | Variable | Description | Default |
-|----------|-------------|---------|
-| `GEMITERM_CONFIG_DIR` | Configuration directory | Platform default |
+| --- | --- | --- |
+| `GEMITERM_CONFIG_DIR` | Override the configuration directory | Platform default |
 
-## Architecture
+## Contributing
 
-```
-src/
-  cli/            # CLI commands, argument parsing, output formatting
-  core/           # Mediator pattern (CQRS), typed commands/queries, handlers, domain types
-  services/       # Business logic: auth flow, cookie management, Gemini API client
-  infrastructure/  # Config, file I/O, logging, validation, formatters
-tests/
-  cli/            # CLI command tests
-  core/           # Query handler tests
-  services/       # Service layer tests
-  infrastructure/  # Infrastructure tests
-  fixtures/       # Shared test fixtures
-```
+Architecture, development workflow, build instructions, and contribution guidelines live in **[CONTRIBUTING.md](CONTRIBUTING.md)**. The agent guide — including the path-mediation rules, the sensitive auth files, and the OpenSpec workflow — lives in **[AGENTS.md](AGENTS.md)**.
+
+## Acknowledgments
+
+- [Google Gemini](https://gemini.google.com) — the model and web app this CLI wraps
+- [Bun](https://bun.sh) — runtime, bundler, and the path to single-binary distribution
+- [`@playwright/cli`](https://www.npmjs.com/package/@playwright/cli) — the headless browser that powers authentication
+- [OpenCode](https://opencode.ai) and the broader AI-agent ecosystem — for the `debate-with-gemini` use case that inspired the skills bundle
+- [`opencode-gemiterm-skills`](https://www.npmjs.com/package/opencode-gemiterm-skills) — the agent-skills companion package
+
+## License
 
-Core uses a **Mediator pattern** with typed Command/Query messages dispatching to registered handlers, decoupling CLI commands from business logic.
+[MIT](LICENSE.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gemiterm",
-  "version": "2.1.0",
+  "version": "2.2.0-beta.0",
   "module": "index.ts",
   "type": "module",
   "repository": {

package/src/cli/commands/continue-command.ts

@@ -9,13 +9,18 @@ import {
   type SendMessageCommandResult,
 } from "../../core/command-handlers.ts";
 import { runInteractiveLoop, type MessageHandlerResult } from "../utils/interactive-prompt.ts";
+import { checkArgLength } from "../utils/long-arg-guard.ts";
+import { loadPromptFromFile, spillOverToTempFile } from "../utils/prompt-file.ts";
+import { removeFile } from "../../infrastructure/io.ts";
 
 interface ContinueCommandOptions {
   help: boolean;
+  promptFile: string | null;
 }
 
 const DEFAULT_OPTIONS: ContinueCommandOptions = {
   help: false,
+  promptFile: null,
 };
 
 export class ContinueCommand implements CliCommand {
@@ -36,6 +41,7 @@ export class ContinueCommand implements CliCommand {
 
     for (const arg of args) {
       if (arg.startsWith("--") || arg.startsWith("-")) continue;
+      if (options.promptFile && arg === options.promptFile) continue;
       if (!conversationId) {
         conversationId = arg;
       } else if (!message) {
@@ -43,11 +49,66 @@ export class ContinueCommand implements CliCommand {
       }
     }
 
+    if (options.promptFile) {
+      if (!conversationId) {
+        console.error(
+          chalk.red(
+            `Error: --prompt-file requires a conversation_id. ` +
+              `Specify a conversation to continue, e.g. \`gemiterm continue <conversation_id> --prompt-file <path>\`.`,
+          ),
+        );
+        process.exit(1);
+      }
+      if (message) {
+        console.error(
+          chalk.red(
+            `Error: cannot use --prompt-file together with a positional message argument. ` +
+              `Use one or the other, not both.`,
+          ),
+        );
+        process.exit(1);
+      }
+    }
+
     if (!conversationId) {
       await this.invokeListCommand(context);
       return;
     }
 
+    let effectivePromptFile: string | null = null;
+    let isSpillover = false;
+    if (options.promptFile) {
+      effectivePromptFile = options.promptFile;
+    } else if (message) {
+      const guard = checkArgLength(message);
+      if (!guard.safe) {
+        const spilled = await spillOverToTempFile(message);
+        effectivePromptFile = spilled;
+        isSpillover = true;
+        console.log(
+          chalk.dim(
+            `[gemiterm] Message is ${guard.length} UTF-16 code units, exceeding the ${guard.limit} limit. ` +
+              `Spilled to temp file '${spilled}' and loading from there.`,
+          ),
+        );
+      }
+    }
+
+    if (effectivePromptFile) {
+      try {
+        message = await loadPromptFromFile(effectivePromptFile);
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`));
+        process.exit(1);
+      }
+      if (isSpillover) {
+        try {
+          removeFile(effectivePromptFile);
+        } catch {
+        }
+      }
+    }
+
     const mediator: Mediator = context.mediator;
 
     if (message) {
@@ -128,9 +189,19 @@ export class ContinueCommand implements CliCommand {
   private parseArgs(args: string[]): ContinueCommandOptions {
     const options = { ...DEFAULT_OPTIONS };
 
-    for (const arg of args) {
+    for (let i = 0; i < args.length; i++) {
+      const arg = args[i];
       if (arg === "--help" || arg === "-h") {
         options.help = true;
+      } else if (arg === "--prompt-file" || arg === "-f") {
+        const next = args[i + 1];
+        if (next && !next.startsWith("-")) {
+          options.promptFile = next;
+          i++;
+        } else {
+          console.error(chalk.red(`Error: --prompt-file requires a path`));
+          process.exit(1);
+        }
       }
     }
 
@@ -149,6 +220,9 @@ export class ContinueCommand implements CliCommand {
     );
     console.log("");
     console.log(chalk.bold("Options:"));
+    console.log(
+      `  ${chalk.cyan("--prompt-file, -f <path>".padEnd(22))}${chalk.dim("Read the message from a file (bypasses the 2048 code unit arg limit)")}`,
+    );
     console.log(`  ${chalk.cyan("--help, -h".padEnd(22))}${chalk.dim("Show this help message")}`);
     console.log("");
     console.log(chalk.dim("If no conversation_id is provided, the list command will be invoked."));

package/src/cli/commands/new-command.ts

@@ -8,15 +8,20 @@ import {
   type StartNewChatCommandResult,
 } from "../../core/command-handlers.ts";
 import { runInteractiveLoop, type MessageHandlerResult } from "../utils/interactive-prompt.ts";
+import { checkArgLength } from "../utils/long-arg-guard.ts";
+import { loadPromptFromFile, spillOverToTempFile } from "../utils/prompt-file.ts";
+import { removeFile } from "../../infrastructure/io.ts";
 
 interface NewCommandOptions {
   help: boolean;
   profile: string | null;
+  promptFile: string | null;
 }
 
 const DEFAULT_OPTIONS: NewCommandOptions = {
   help: false,
   profile: null,
+  promptFile: null,
 };
 
 export class NewCommand implements CliCommand {
@@ -37,11 +42,56 @@ export class NewCommand implements CliCommand {
     for (const arg of args) {
       if (arg.startsWith("--") || arg.startsWith("-")) continue;
       if (options.profile && arg === options.profile) continue;
+      if (options.promptFile && arg === options.promptFile) continue;
       if (!message) {
         message = arg;
       }
     }
 
+    if (options.promptFile && message) {
+      console.error(
+        chalk.red(
+          `Error: cannot use --prompt-file together with a positional message argument. ` +
+            `Use one or the other, not both.`,
+        ),
+      );
+      process.exit(1);
+    }
+
+    let effectivePromptFile: string | null = null;
+    let isSpillover = false;
+    if (options.promptFile) {
+      effectivePromptFile = options.promptFile;
+    } else if (message) {
+      const guard = checkArgLength(message);
+      if (!guard.safe) {
+        const spilled = await spillOverToTempFile(message);
+        effectivePromptFile = spilled;
+        isSpillover = true;
+        console.log(
+          chalk.dim(
+            `[gemiterm] Message is ${guard.length} UTF-16 code units, exceeding the ${guard.limit} limit. ` +
+              `Spilled to temp file '${spilled}' and loading from there.`,
+          ),
+        );
+      }
+    }
+
+    if (effectivePromptFile) {
+      try {
+        message = await loadPromptFromFile(effectivePromptFile);
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`));
+        process.exit(1);
+      }
+      if (isSpillover) {
+        try {
+          removeFile(effectivePromptFile);
+        } catch {
+        }
+      }
+    }
+
     const mediator: Mediator = context.mediator;
 
     if (message) {
@@ -121,6 +171,15 @@ export class NewCommand implements CliCommand {
           console.error(chalk.red(`Error: --profile requires a profile name`));
           process.exit(1);
         }
+      } else if (arg === "--prompt-file" || arg === "-f") {
+        const next = args[i + 1];
+        if (next && !next.startsWith("-")) {
+          options.promptFile = next;
+          i++;
+        } else {
+          console.error(chalk.red(`Error: --prompt-file requires a path`));
+          process.exit(1);
+        }
       }
     }
 
@@ -139,6 +198,9 @@ export class NewCommand implements CliCommand {
     console.log(
       `  ${chalk.cyan("--profile, -p <name>".padEnd(22))}${chalk.dim("Use a specific profile (default profile used if omitted)")}`,
     );
+    console.log(
+      `  ${chalk.cyan("--prompt-file, -f <path>".padEnd(22))}${chalk.dim("Read the message from a file (bypasses the 2048 code unit arg limit)")}`,
+    );
     console.log(`  ${chalk.cyan("--help, -h".padEnd(22))}${chalk.dim("Show this help message")}`);
     console.log("");
     console.log(chalk.dim("If no message is provided, an interactive chat session will start."));

package/src/cli/utils/long-arg-guard.ts

@@ -0,0 +1,28 @@
+export const WINDOWS_COMMAND_LINE_ARG_LIMIT = 2048;
+
+export type LongArgGuardResult =
+  | { safe: true; arg: string }
+  | { safe: false; arg: string; length: number; limit: number; suggestion: string };
+
+export function checkArgLength(arg: string): LongArgGuardResult {
+  const length = utf16CodeUnitLength(arg);
+  if (length <= WINDOWS_COMMAND_LINE_ARG_LIMIT) {
+    return { safe: true, arg };
+  }
+  return {
+    safe: false,
+    arg,
+    length,
+    limit: WINDOWS_COMMAND_LINE_ARG_LIMIT,
+    suggestion:
+      `Argument is ${length} UTF-16 code units, which exceeds the ${WINDOWS_COMMAND_LINE_ARG_LIMIT} ` +
+      `code unit limit imposed by Bun's Windows process spawn path (appendWindowsArgument in ` +
+      `Bun's run_command.zig panics with "index out of bounds" when this limit is exceeded). ` +
+      `Pipe the message via stdin (e.g. \`echo "..." | gemiterm new\`) or save it to a file and ` +
+      `pass it with \`--prompt-file <path>\`.`,
+  };
+}
+
+function utf16CodeUnitLength(s: string): number {
+  return s.length;
+}

package/src/cli/utils/prompt-file.ts

@@ -0,0 +1,26 @@
+import { IOError, readTextFile, writeTextFile } from "../../infrastructure/io.ts";
+import { getTempFilePath } from "../../infrastructure/path-utils.ts";
+
+export async function loadPromptFromFile(filePath: string): Promise<string> {
+  try {
+    return readTextFile(filePath);
+  } catch (err) {
+    if (err instanceof IOError) {
+      throw new Error(`Could not read prompt file '${filePath}': ${err.message}`);
+    }
+    throw err;
+  }
+}
+
+export async function spillOverToTempFile(content: string): Promise<string> {
+  const path = getTempFilePath("gemiterm-arg-spill", ".txt");
+  try {
+    writeTextFile(path, content);
+  } catch (err) {
+    if (err instanceof IOError) {
+      throw new Error(`Could not spill message to temp file: ${err.message}`);
+    }
+    throw err;
+  }
+  return path;
+}

package/src/infrastructure/io.ts

@@ -114,6 +114,14 @@ function removeDir(path: string): void {
   }
 }
 
+function removeFile(path: string): void {
+  try {
+    rmSync(path, { force: true });
+  } catch (err) {
+    throw wrap("removeFile", path, err instanceof Error ? err : undefined);
+  }
+}
+
 function renameDir(src: string, dest: string): void {
   try {
     renameSync(src, dest);
@@ -155,6 +163,7 @@ export {
   readJsonFile,
   writeJsonFile,
   removeDir,
+  removeFile,
   renameDir,
   isDirectory,
   listSubdirectories,