gptme

gptme is a chat-CLI for LLMs, empowering them with tools to run shell commands, execute code, read and manipulate files, and more.

If PROMPTS are provided, a new conversation will be started with it. PROMPTS can be chained with the ‘-’ separator.

Examples:

gptme “hello” Start a conversation

gptme “fix TODOs” main.py Include file or URL in context

gptme “review” github.com/org/repo/pull/1 Include a GitHub PR in context

gptme –tools none “what is 2+2” No tools, just chat

gptme -t read-only “summarize this repo” Read files only; no writes or execution

gptme -t patch,save “fix typo” main.py Only specific tools (comma-separated)

gptme -t +subagent “plan a refactor” Default tools + subagent

gptme -t=-browser “summarize code” Default tools minus browser

gptme –context files “do task” Skip context_cmd, keep project files

Available tools:

{available_tools}

The interface provides /commands during a conversation:

{commands_help}

Subcommand shortcuts:

gptme search QUERY Search conversation logs (alias for gptme-util chats search)

gptme chats [args] Any gptme-util subcommand works directly (chats, tools, skills, …)

gptme <cmd> [args] gptme-util subcommand or gptme-<cmd> binary, in that order

(installed gptme-* binaries in PATH are listed at the bottom of this help)

Utilities:

gptme tools list List all tools and their availability

gptme tools info TOOL Show detailed tool instructions/examples

gptme skills list List discoverable skills in the current workspace

gptme skills show NAME Show a skill or lesson by name

gptme chats list List past conversations

gptme chats search Q Search conversations for query (full options)

gptme chats send ID MSG Queue a prompt for a running chat from another terminal

gptme chats rename Rename a conversation

gptme models list List available models

gptme snapshot list List workspace snapshots outside a session

gptme context index Index project files for RAG

gptme llm generate Direct LLM generation without chat

Run ‘gptme-util –help’ for all utility commands.

Usage

gptme [OPTIONS] [PROMPTS]...

Options

--name <name>

Conversation ID (used to resume). Defaults to a random name.

-m, --model <model>

Model to use, e.g. {model_examples}. If only provider given then a default is used.

-w, --workspace <workspace>

Path to workspace directory, or ‘@log’ to use the log directory.

--agent-path <agent_path>

Path to agent workspace directory.

-r, --resume

Load the most recent conversation in this workspace. Use –name ID to select one.

-y, --no-confirm

Skip all confirmation prompts.

--gear <gear>

Autonomy preset: 0=observe, 1=review, 2=plan, 3=execute, 4=integrate. Explicit –tools/–agent-profile/–no-confirm override preset parts.

-n, --non-interactive

Non-interactive mode. Implies –no-confirm.

--output-format <output_format>

Output format for non-interactive mode. ‘json’ emits one JSON object per line on stdout.

Options:

text | json

--system <prompt_system>

System prompt [full|full-noexamples|short|<custom>]. Defaults to ‘full’, or the value of system in gptme.toml [prompt] if set. ‘full-noexamples’ omits tool examples (~40% token reduction).

-t, --tools <tool_allowlist>

Tools to allow. Comma-separated or repeated. Use ‘+tool’ to add to defaults (e.g., ‘-t +subagent’). Use ‘-tool’ to exclude from defaults (e.g., ‘-t=-browser’). Use ‘none’ to disable all tools. Supports .py file paths for custom tools (e.g., ‘-t path/to/tool.py’). See ‘Available tools’ above for the list.

--agent-profile <agent_profile>

Agent profile to use. Profiles provide system prompts, tool access hints, and behavior rules. Use ‘gptme-util profile list’ to see available profiles.

--tool-format <tool_format>

Tool format to use.

Options:

markdown | xml | tool

--prune-tool-output, --no-prune-tool-output

Use a summary model to keep only the relevant lines from large shell/read tool outputs.

--stream, --no-stream

Stream responses

--show-hidden

Show hidden system messages.

--show-prompt-stats

Show startup system-prompt token stats for the current configuration and exit.

-v, --verbose

Show verbose output.

--version

Show version. With -v/–verbose, show full configuration info.

--version-json

Show version info as JSON (machine-readable, for scripting).

--profile

Enable profiling and save results to gptme-profile-{timestamp}.prof

--context <context_include>

Context to include (default: all). Comma-separated or repeated. Tools and agent config (–agent-path) are always included.

--no-workspace

Skip all workspace context (prompt files and context_cmd). Tools and agent config are still included.

--architect

Enable architect/editor split mode: plan with strong model, execute with cheap model.

--architect-model <architect_model>

Model to use for the architect (planning) turn. E.g. openai/o3, anthropic/claude-opus-4-7.

--editor-model <editor_model>

Model to use for the editor (execution) turn. E.g. anthropic/claude-sonnet-4-5, openai/gpt-5-mini.

--auto-accept-architect

Skip user confirmation between architect and editor turns.

--injection-hygiene <injection_hygiene>

Prompt injection hygiene for tool outputs: off (disabled), warn (flag suspicious content), block (redact HIGH-severity patterns). Overrides GPTME_INJECTION_HYGIENE env var.

Options:

off | warn | block

--manifest-dir <manifest_dir>

Write a JSON record before and after each tool call to this directory. Records can be committed alongside session artifacts for tool-call-level attribution.

Arguments

PROMPTS

Optional argument(s)

Environment variables

GPTME_INJECTION_HYGIENE

Provide a default for --injection-hygiene

GPTME_MANIFEST_DIR

Provide a default for --manifest-dir