gptme-util

gptme-util#

Utility commands for gptme.

Usage

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

Options

-v, --verbose#

Enable verbose output.

context#

Commands for context generation.

Usage

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

files#

Print the contents of all files listed in gptme.toml [prompt] files.

Replaces ad-hoc context scripts in non-gptme harnesses (autonomous runs, project-monitoring) that manually concatenate gptme.toml prompt files.

Usage

gptme-util context files [OPTIONS]

Options

--config <config>#

Path to gptme.toml (default: auto-discover from git root or cwd)

git#

Summarise the current git repo: branch, recent commits, staged/unstaged changes.

Usage

gptme-util context git [OPTIONS]

index#

Index a file or directory for context retrieval.

Usage

gptme-util context index [OPTIONS] PATH

Arguments

PATH#

Required argument

journal#

Print journal entries from the last N days.

Usage

gptme-util context journal [OPTIONS]

Options

--days <days>#

Days to look back

--path <path>#

Journal directory

retrieve#

Search indexed documents for relevant context.

Usage

gptme-util context retrieve [OPTIONS] QUERY

Options

--full#

Show full context of search results

Arguments

QUERY#

Required argument

search-conversations#

Search indexed conversations for relevant context.

Returns the most relevant past conversation snippets for the given query. Requires conversations to be indexed first with rag_index_conversations (use rag_index_conversations() via the ipython tool, or gptme context index on a directory).

Usage

gptme-util context search-conversations [OPTIONS] QUERY

Options

--top-k <top_k>#

Number of results to return

Default:

3

Arguments

QUERY#

Required argument

tree#

Print workspace directory tree (respects .gitignore).

Usage

gptme-util context tree [OPTIONS]

Options

--path <path>#

Workspace root

--max-depth <max_depth>#

Tree depth

llm#

LLM-related utilities.

Usage

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

generate#

Generate a response from an LLM without any formatting.

Usage

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

--system <system_prompt>#

System message to prepend.

Default:

'You are a helpful assistant.'

--max-tokens <max_tokens>#

Maximum number of tokens to generate.

--temperature <temperature>#

Sampling temperature (0.0=deterministic, higher=more creative). Range: 0.0–2.0.

--output-format <output_format>#

Output format: ‘text’ (default) or ‘json’ (includes model and usage metadata). Incompatible with –stream.

Default:

'text'

Options:

text | json

Arguments

PROMPT#

Optional argument

models#

Model-related utilities.

Usage

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

info#

Show detailed information about a specific model.

Usage

gptme-util models info [OPTIONS] MODEL_NAME

Options

--json#

Output as JSON.

Arguments

MODEL_NAME#

Required argument

list#

List available models.

Usage

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

--json#

Output as JSON.

test#

Test connectivity to a model by making a minimal API call.

Verifies that the API key is configured, the model is reachable, and returns a response. Useful for troubleshooting provider setup and verifying model availability.

Examples:

gptme-util models test # test default model from config gptme-util models test anthropic # test provider default gptme-util models test anthropic/claude-opus-4-7 # specific model gptme-util models test –json anthropic # machine-readable output

Usage

gptme-util models test [OPTIONS] [MODEL_NAME]

Options

--json#

Output as JSON.

Arguments

MODEL_NAME#

Optional argument

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

Usage

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

list#

List available agent profiles.

Usage

gptme-util profile list [OPTIONS]

show#

Show details for a specific profile.

Usage

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.

Usage

gptme-util profile validate [OPTIONS]

prompts#

Commands for prompt utilities.

Usage

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.

Usage

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

Arguments

PROMPT#

Required argument(s)

providers#

Commands for managing custom providers.

Usage

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

add#

Interactively add a custom OpenAI-compatible provider.

Prompts for provider name, base URL, API key, and default model, then writes the configuration to gptme.toml.

Example providers: Ollama (http://localhost:11434/v1), LM Studio (http://localhost:1234/v1), vLLM, or any OpenAI-compatible relay.

Usage

gptme-util providers add [OPTIONS]

list#

List configured and auto-discovered local OpenAI-compatible providers.

Configured [[providers]] entries are listed first. Then gptme probes Ollama (http://127.0.0.1:11434/v1/models) and LM Studio (http://127.0.0.1:1234/v1/models) and reports each candidate — live servers and the reason a probe did not count as available. Discovery never writes config; use gptme providers add to persist a provider.

Usage

gptme-util providers list [OPTIONS]

Options

--discover, --no-discover#

Probe well-known local OpenAI-compatible endpoints (Ollama :11434, LM Studio :1234).

--json#

Output as JSON.

test#

Test connectivity to a custom provider.

Connects to the provider’s API and lists available models.

Usage

gptme-util providers test [OPTIONS] PROVIDER_NAME

Arguments

PROVIDER_NAME#

Required argument

tokens#

Commands for token counting.

Usage

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

count#

Count tokens in text or file.

Usage

gptme-util tokens count [OPTIONS] [TEXT]

Options

-m, --model <model>#

Model to use for token counting.

-f, --file <file>#

File to count tokens in. Use ‘-’ to read from stdin.

Arguments

TEXT#

Optional argument

tools#

Tool-related utilities.

Usage

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

call#

Call a tool with the given arguments.

Usage

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.

Usage

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

--json#

Output as JSON.

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.

Usage

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

--json#

Output as JSON.

Contents