CLI Reference

CLI Reference#

gptme provides the following commands:

This is the full CLI reference. For a more concise version, run gptme --help.

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 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
The interface provides /commands during a conversation:
Available commands:
/undo Undo the last action
/log Show the conversation log
/edit Edit the conversation in your editor
/rename Rename the conversation
/fork Create a copy of the conversation
/delete Delete a conversation by ID (alias: /rm)
/summarize Summarize the conversation
/replay Replay tool operations
/export Export conversation as HTML
/model Show or switch the current model
/models List available models
/tokens Show token usage and costs (alias: /cost)
/context Show context token breakdown
/tools Show available tools
/commit Ask assistant to git commit
/compact Compact the conversation
/impersonate Impersonate the assistant
/plugin Manage plugins
/clear Clear the terminal screen
/setup Setup gptme with completions and configuration
/doctor Run system diagnostics
/restart Restart gptme process
/help Show this help message
/exit Exit the program
Keyboard shortcuts:
Ctrl+X Ctrl+E Edit prompt in your editor
Ctrl+J Insert a new line without executing the prompt
Utilities (gptme-util):
gptme-util tools list List all tools and their availability
gptme-util tools info TOOL Show detailed tool instructions/examples
gptme-util chats list List past conversations
gptme-util chats search Q Search conversations for query
gptme-util chats rename Rename a conversation
gptme-util models list List available models
gptme-util context index Index project files for RAG
gptme-util llm generate Direct LLM generation without chat

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

gptme [OPTIONS] [PROMPTS]...

Options

--name <name>#

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

-m, --model <model>#

Model to use, e.g. openai/gpt-5, anthropic/claude-sonnet-4-6. 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 most recent conversation.

-y, --no-confirm#

Skip all confirmation prompts.

-n, --non-interactive#

Non-interactive mode. Implies –no-confirm.

--system <prompt_system>#

System prompt [full|short|<custom>]. Defaults to ‘full’.

-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’). Available: append, autocommit, autocompact, browser, chats, choice, complete, computer, elicit, form, gh, ipython, lessons, mcp, patch, precommit, read, restart, save, shell, subagent, tmux, todo, vision.

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

--stream, --no-stream#

Stream responses

--show-hidden#

Show hidden system messages.

-v, --verbose#

Show verbose output.

--version#

Show version and configuration information

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

Arguments

PROMPTS#

Optional argument(s)

gptme-server#

gptme server commands.

gptme-server [OPTIONS] COMMAND [ARGS]...

openapi#

Generate OpenAPI specification without starting server.

gptme-server openapi [OPTIONS]

Options

-o, --output <output>#

Output file path

serve#

Starts a server and web UI for gptme.

Note that this is very much a work in progress, and is not yet ready for normal use.

gptme-server serve [OPTIONS]

Options

--debug#

Debug mode

-v, --verbose#

Verbose output

--model <model>#

Model to use by default, can be overridden in each request.

--host <host>#

Host to bind the server to.

--port <port>#

Port to run the server on.

--tools <tools>#

Tools to enable, comma separated.

--cors-origin <cors_origin>#

CORS origin to allow. Use ‘*’ to allow all origins.

token#

Display the server authentication token.

gptme-server token [OPTIONS]

gptme-eval#

Run evals for gptme. Pass eval or suite names to run, or result files to print.

Output from evals will be captured, unless a single eval is run, and saved to the results directory.

gptme-eval [OPTIONS] [EVAL_NAMES_OR_RESULT_FILES]...

Options

-m, --model <_model>#

Model to use, can be passed multiple times. Can include tool format with @, e.g. ‘gpt-4@tool’

-t, --timeout <timeout>#

Timeout for code generation

-p, --parallel <parallel>#

Number of parallel evals to run

--tool-format <tool_format>#

Tool format to use. Can also be specified per model with @format.

Options:

markdown | xml | tool

--use-docker#

Run evals in Docker container for isolation (prevents host environment pollution)

Arguments

EVAL_NAMES_OR_RESULT_FILES#

Optional argument(s)

gptme-auth#

Authenticate with various gptme providers.

gptme-auth [OPTIONS] COMMAND [ARGS]...

login#

Login to gptme cloud using RFC 8628 Device Flow.

Initiates an OAuth Device Authorization Grant flow:

1. Requests a device code from the gptme service
2. Prompts you to visit a URL and enter a code in your browser
3. Polls until you approve (or the code expires)
4. Saves the token for future use

Works great for SSH sessions and headless environments.

gptme-auth login [OPTIONS]

Options

--url <url>#

gptme service URL to authenticate with.

Default:

'https://fleet.gptme.ai'

--no-browser#

Don’t open the browser automatically.

logout#

Remove stored credentials for gptme cloud.

gptme-auth logout [OPTIONS]

Options

--url <url>#

gptme service URL to log out from.

Default:

'https://fleet.gptme.ai'

openai-subscription#

Authenticate with OpenAI using your ChatGPT Plus/Pro subscription.

This opens a browser for you to log in with your OpenAI account. After successful login, tokens are stored locally for future use.

gptme-auth openai-subscription [OPTIONS]

status#

Show current login status for gptme cloud.

gptme-auth status [OPTIONS]

Options

--url <url>#

gptme service URL to check.

Default:

'https://fleet.gptme.ai'

gptme-util#

Utility commands for gptme.

gptme-util [OPTIONS] COMMAND [ARGS]...

Options

-v, --verbose#

Enable verbose output.

chats#

Commands for managing chat logs.

gptme-util chats [OPTIONS] COMMAND [ARGS]...

clean#

Find and remove empty or trivial conversations.

By default, lists conversations with 0-1 messages (dry-run). Use –delete to actually remove them.

Examples:
gptme-util chats clean # List empty conversations
gptme-util chats clean -n 2 # Include conversations with <=2 messages
gptme-util chats clean –delete # Delete empty conversations
gptme-util chats clean –include-test # Include test/eval conversations
gptme-util chats clean [OPTIONS]

Options

-n, --max-messages <max_messages>#

Treat conversations with at most N messages as empty (default: 1).

--include-test#

Include test/eval conversations in scan.

--delete#

Actually delete empty conversations (default is dry-run).

--json#

Output as JSON.

export#

Export a conversation to HTML or markdown.

Exports the conversation with the given ID to a file. Use –format to choose between HTML (self-contained) and markdown.

Examples:

gptme-util chats export my-conversation

gptme-util chats export my-conversation -f html -o chat.html

gptme-util chats export [OPTIONS] ID

Options

-f, --format <fmt>#

Export format (default: markdown).

Options:

html | markdown

-o, --output <output>#

Output file path.

Arguments

ID#

Required argument

list#

List conversation logs.

gptme-util chats list [OPTIONS]

Options

-n, --limit <limit>#

Maximum number of chats to show.

--summarize#

Generate LLM-based summaries for chats

read#

Read a specific chat log.

gptme-util chats read [OPTIONS] ID

Arguments

ID#

Required argument

rename#

Rename a conversation’s display name.

Updates the conversation’s display name without moving files. The conversation ID remains unchanged.

gptme-util chats rename [OPTIONS] ID NAME

Arguments

ID#

Required argument

NAME#

Required argument

stats#

Show conversation statistics.

Displays overview of conversation history including counts, date ranges, message totals, and activity breakdown.

gptme-util chats stats [OPTIONS]

Options

--since <since>#

Only include conversations since this date (YYYY-MM-DD or Nd for N days ago).

--json#

Output as JSON.

context#

Commands for context generation.

gptme-util context [OPTIONS] COMMAND [ARGS]...

index#

Index a file or directory for context retrieval.

gptme-util context index [OPTIONS] PATH

Arguments

PATH#

Required argument

retrieve#

Search indexed documents for relevant context.

gptme-util context retrieve [OPTIONS] QUERY

Options

--full#

Show full context of search results

Arguments

QUERY#

Required argument

llm#

LLM-related utilities.

gptme-util llm [OPTIONS] COMMAND [ARGS]...

generate#

Generate a response from an LLM without any formatting.

gptme-util llm generate [OPTIONS] [PROMPT]

Options

-m, --model <model>#

Model to use (e.g. openai/gpt-4o, anthropic/claude-sonnet-4-6)

--stream, --no-stream#

Stream the response

Arguments

PROMPT#

Optional argument

mcp#

Commands for managing MCP servers.

gptme-util mcp [OPTIONS] COMMAND [ARGS]...

info#

Show detailed information about an MCP server.

Checks configured servers first, then searches registries if not found locally.

gptme-util mcp info [OPTIONS] SERVER_NAME

Arguments

SERVER_NAME#

Required argument

list#

List MCP servers and check their connection health.

gptme-util mcp list [OPTIONS]

test#

Test connection to a specific MCP server.

gptme-util mcp test [OPTIONS] SERVER_NAME

Arguments

SERVER_NAME#

Required argument

models#

Model-related utilities.

gptme-util models [OPTIONS] COMMAND [ARGS]...

info#

Show detailed information about a specific model.

gptme-util models info [OPTIONS] MODEL_NAME

Arguments

MODEL_NAME#

Required argument

list#

List available models.

gptme-util models list [OPTIONS]

Options

--provider <provider>#

Filter by provider (e.g., openai, anthropic, gemini)

--pricing#

Show pricing information

--vision#

Show only models with vision support

--reasoning#

Show only models with reasoning support

--simple#

Output one model per line as provider/model

--include-deprecated#

Include deprecated/sunset models in the listing

--available#

Only show models from providers with configured API keys

profile#

Commands for managing agent profiles.

Profiles define system prompts, tool access, and behavior rules. Tool restrictions are hard-enforced in subagent and CLI mode.

Example:

gptme-util profile list # List all profiles gptme-util profile show explorer # Show profile details

gptme-util profile [OPTIONS] COMMAND [ARGS]...

list#

List available agent profiles.

gptme-util profile list [OPTIONS]

show#

Show details for a specific profile.

gptme-util profile show [OPTIONS] NAME

Arguments

NAME#

Required argument

validate#

Validate all profiles against available tools.

Checks that tool names specified in profiles match actual loaded tools.

gptme-util profile validate [OPTIONS]

prompts#

Commands for prompt utilities.

gptme-util prompts [OPTIONS] COMMAND [ARGS]...

expand#

Expand a prompt to show what will be sent to the LLM.

Shows exactly how file paths in prompts are expanded into message content, using the same logic as the main gptme tool.

gptme-util prompts expand [OPTIONS] PROMPT...

Arguments

PROMPT#

Required argument(s)

providers#

Commands for managing custom providers.

gptme-util providers [OPTIONS] COMMAND [ARGS]...

list#

List configured custom OpenAI-compatible providers.

gptme-util providers list [OPTIONS]

skills#

Browse and inspect skills and lessons.

gptme-util skills [OPTIONS] COMMAND [ARGS]...

check#

Validate lesson/skill health: frontmatter, keywords, sizing.

gptme-util skills check [OPTIONS]

Options

--workspace <workspace>#

Agent workspace to check (default: current directory).

Default:

'.'

dirs#

Show directories searched for skills and lessons.

gptme-util skills dirs [OPTIONS]

init#

Create a new skill from a template.

PATH is the directory to create the skill in.

Example:
gptme-util skills init ./my-skill –name my-skill -d “Does cool things”
gptme-util skills init [OPTIONS] PATH

Options

-n, --name <name>#

Skill name (defaults to directory name)

-d, --description <description>#

Short description

-a, --author <author>#

Author name

-t, --tags <tags>#

Comma-separated tags

Arguments

PATH#

Required argument

install#

Install a skill from a source.

SOURCE can be:

- A skill name from the registry (e.g. ‘code-review-helper’)
- A git URL (e.g. ‘user/skills.git’)
- A local path to a skill directory (e.g. ‘./my-skill/’)
gptme-util skills install [OPTIONS] SOURCE

Options

-n, --name <name>#

Override skill name

-f, --force#

Overwrite existing installation

Arguments

SOURCE#

Required argument

installed#

List installed skills from the user’s skill directory.

gptme-util skills installed [OPTIONS]

Options

--json#

Output as JSON

list#

List available skills (and optionally lessons).

gptme-util skills list [OPTIONS]

Options

--all#

Show both skills and lessons

--json#

Output as JSON

publish#

Validate and package a skill for sharing.

PATH is the skill directory (containing SKILL.md).

Creates a .tar.gz archive and shows instructions for submitting to the gptme-contrib registry.

gptme-util skills publish [OPTIONS] PATH

Arguments

PATH#

Required argument

show#

Show the full content of a skill or lesson.

gptme-util skills show [OPTIONS] NAME

Arguments

NAME#

Required argument

uninstall#

Uninstall a skill by name.

gptme-util skills uninstall [OPTIONS] NAME

Arguments

NAME#

Required argument

validate#

Validate a skill directory or SKILL.md file.

Checks for required frontmatter fields and marketplace metadata.

gptme-util skills validate [OPTIONS] PATH

Arguments

PATH#

Required argument

tokens#

Commands for token counting.

gptme-util tokens [OPTIONS] COMMAND [ARGS]...

count#

Count tokens in text or file.

gptme-util tokens count [OPTIONS] [TEXT]

Options

-m, --model <model>#

Model to use for token counting.

-f, --file <file>#

File to count tokens in.

Arguments

TEXT#

Optional argument

tools#

Tool-related utilities.

gptme-util tools [OPTIONS] COMMAND [ARGS]...

call#

Call a tool with the given arguments.

gptme-util tools call [OPTIONS] TOOL_NAME FUNCTION_NAME

Options

-a, --arg <arg>#

Arguments to pass to the function. Format: key=value

Arguments

TOOL_NAME#

Required argument

FUNCTION_NAME#

Required argument

info#

Show detailed information about a tool.

Displays tool instructions, examples, and token usage estimates. Use this to understand how a tool works and how to use it.

Output is truncated by default. Use -v for full output.

gptme-util tools info [OPTIONS] TOOL_NAME

Options

-v, --verbose#

Show full output (not truncated)

--no-examples#

Hide examples section

--no-tokens#

Hide token estimates

Arguments

TOOL_NAME#

Required argument

list#

List available tools.

By default shows only available tools (dependencies installed). Use –all to include unavailable tools as well.

gptme-util tools list [OPTIONS]

Options

--available, --all#

Show only available tools or all tools

--langtags#

Show language tags for code execution

--compact#

Compact single-line format