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.

-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-budget <context_budget>#: Compaction threshold as a window fraction (0<x≤1) or absolute tokens (>1).

--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.

--allow-hosts <allow_hosts>#: Comma-separated hostnames the agent may access via web tools (e.g. ‘github.com,*.googleapis.com’). Default: unrestricted. Wildcard subdomains supported.

Arguments

PROMPTS#: Optional argument(s)

Environment variables

GPTME_ALLOW_HOSTS: Provide a default for --allow-hosts