Commands Reference

September 4, 2026 · View on GitHub

← Back to README

This document provides comprehensive documentation for all commands available in the Inference Gateway CLI.

Table of Contents

Project Initialization

infer init

Initializes the Inference Gateway CLI configuration in your userspace home directory. This creates:

  • .infer/ under ~/.infer/ with:
    • config.yaml - Main configuration file (the shared baseline)
    • prompts.yaml, keybindings.yaml, channels.yaml, heartbeat.yaml, judge.yaml, computer_use.yaml, browser_use.yaml, agents.yaml, mcp.yaml, shortcuts/, skills/ - the split config files and directories
  • .env.example template for provider API keys is written by infer env, not by init.

All state (conversations, logs, history, artifacts, ...) is written under ~/.infer/, never into a project directory. To override a setting for a single project, use infer config set --project, which writes a sparse ./.infer/config.yaml override on top of the userspace baseline.

This is the recommended command to start working with Inference Gateway CLI in a new project.

Options:

  • --overwrite: Overwrite existing files if they already exist
  • --skip-migrations: Skip running database migrations

infer env

Generate a .env.example file in the current directory with all the different provider API environment variables needed by the Inference Gateway. This is a convenient shortcut so you don't need to remember which providers are available or what environment variables to set.

If .env.example already exists, the command will error. Use --overwrite to replace it.

If no .gitignore exists in the project root, one is created with .env added to it.

Options:

  • --overwrite: Overwrite .env.example if it already exists

Examples:

# Create .env.example with all provider API keys
infer env

# Overwrite existing .env.example
infer env --overwrite

Next steps after creation:

cp .env.example .env
# Edit .env and add your API keys

Configuration Management

infer config

Manage CLI configuration with a uniform interface: read any value with config get, write any value with config set, and create the file with config init. There are no per-setting subcommands - every config.yaml key is reachable by its dotted path.

infer config init

Initialize the userspace baseline ~/.infer/config.yaml with default settings.

A project ./.infer/config.yaml is an override layer, not a second full config - create it with infer config set --project <key> <value>, which writes only the keys you set. Seeding a full default config into a project would shadow the entire userspace baseline, because project values win key-by-key and project lists replace (rather than extend) userspace lists.

For complete initialization of the full baseline, use infer init instead.

Options:

  • --overwrite: Overwrite existing configuration file

Examples:

infer config init
infer config init --overwrite

infer config get [key]

Print the effective value of a configuration key, or the whole config when no key is given. The value reflects what the CLI actually runs with: built-in defaults, the global ~/.infer/config.yaml merged key-by-key with the local .infer/config.yaml override when present, and INFER_* environment overrides. Keys are dotted paths into config.yaml.

Options:

  • -f, --format <yaml|json>: Output format (default yaml)

Examples:

infer config get                          # dump the whole effective config
infer config get agent.model
infer config get tools.bash               # print a whole subtree
infer config get tools.sandbox.directories
infer config get tools.web_fetch -f json

infer config set <key> <value>

Set a configuration value in config.yaml. The value is parsed to the field's type (bool, integer, number or string); list keys take a comma-separated value that replaces the whole list. Unknown keys are rejected.

By default the userspace ~/.infer/config.yaml baseline is updated; pass --project to write a sparse override into the project .infer/config.yaml instead. Project overrides are meant to be committed; they never receive runtime-generated files.

Examples:

# Scalars
infer config set agent.model "openai/gpt-4-turbo"
infer config set agent.max_turns 100
infer config set agent.max_concurrent_tools 5
infer config set agent.skills.enabled true

# Tools
infer config set tools.enabled true
infer config set tools.bash.enabled true
infer config set tools.web_search.enabled true
infer config set tools.grep.backend ripgrep
infer config set tools.safety.require_approval true

# List values (comma-separated, replaces the whole list)
infer config set tools.sandbox.directories ".,/tmp,/data"
infer config set tools.web_fetch.allowed_domains "example.com,github.com"

# Write a project-level override into ./.infer/config.yaml instead
infer config set agent.model "openai/gpt-4o" --project

System prompts and per-tool descriptions live in prompts.yaml (e.g. prompts.agent.system_prompt), which is edited directly rather than via config set.

Tool configuration (enable/disable, allowed, sandbox, backends, domains, approval) is done with config get/config set on the tools.* keys - see the examples above. To run a tool directly or check a command against the allowed list, use the top-level infer tools command below.

infer tools

Run agent tools directly or check whether a bash command is allowed, using the same execution and validation path as the agent.

Subcommands:

  • execute <tool> [json-args] [--format text|json]: Execute any enabled tool directly
  • validate <command>: Check whether a bash command would be allowed, without running it

Examples:

# Execute a tool (JSON args, exactly as the agent invokes it)
infer tools execute Bash '{"command":"ls -la"}'
infer tools execute Read '{"file_path":"README.md"}'
infer tools execute Tree '{"path":".", "max_depth":2}'

# Validate a bash command against the allowed list
infer tools validate "git status"

Agent Management

infer agents

Manage A2A (Agent-to-Agent) agent configurations. This command allows you to configure and manage connections to specialized A2A agents for task delegation and distributed processing.

Subcommands:

  • init: Initialize agents.yaml configuration file
  • add <name> [url]: Add a new A2A agent endpoint
  • update <name> [flags]: Update an existing agent's configuration
  • list: List all configured agents
  • show <name>: Show details for a specific agent
  • remove <name>: Remove an agent from configuration

Update Flags:

  • --url <url>: Update agent URL
  • --model <model>: Update model for the agent
  • --oci <image>: Update OCI image reference
  • --tag <tag>: Replace the tag of the agent's default image (known agents only, mutually exclusive with --oci)
  • --artifacts-url <url>: Update artifacts server URL
  • --environment <KEY=VALUE>: Set environment variables
  • --run: Enable local execution with Docker

Examples:

# Initialize agents configuration
infer agents init

# Add a known agent (with defaults)
infer agents add browser-agent

# Add a known agent with custom model
infer agents add documentation-agent --model "anthropic/claude-4-5-sonnet"

# Add a known agent on a specific image tag (browser-agent ships one tag per browser engine)
infer agents add browser-agent --tag lightpanda

# Pin a known agent to a released version
infer agents add browser-agent --tag chromium-0.8.0

# Add a custom remote agent
infer agents add code-reviewer https://agent.example.com

# Add a local agent with OCI image
infer agents add test-runner https://localhost:8081 --oci ghcr.io/org/test-runner:latest --run

# List all agents
infer agents list

# Show agent details
infer agents show browser-agent

# Update agent URL
infer agents update browser-agent --url http://browser-agent:9090

# Update agent model
infer agents update browser-agent --model "deepseek/deepseek-v4-pro"

# Switch to another image tag
infer agents update browser-agent --tag lightpanda

# Update multiple settings
infer agents update browser-agent --url http://browser-agent:9090 --model "openai/gpt-4"

# Remove agent
infer agents remove browser-agent

For more details on A2A agents, see the Tools Reference - A2A Tools section.

Chat and Agent Execution

infer chat

Start an interactive chat session with model selection. Provides a conversational interface where you can select models and have conversations.

Features:

  • Interactive model selection
  • Conversational interface
  • Real-time streaming responses
  • Scrollable chat history with mouse wheel and keyboard support

Navigation Controls:

  • Mouse wheel: Scroll up/down through chat history
  • Arrow keys (↑/↓) or Vim keys (k/j): Scroll one line at a time
  • page up/page down: Scroll by page
  • home/end: Jump to top/bottom of chat history
  • shift+↑/shift+↓: Half-page scrolling
  • ctrl+o (default): Toggle expanded view of tool results (configurable via tools_toggle_tool_expansion)
  • ctrl+k (default): Toggle expanded view of model thinking blocks (configurable via display_toggle_thinking)
  • shift+tab: Cycle agent mode (Standard → Plan → Auto-Accept → Auto+Judge)
  • ↓ (when not navigating input history): Select the status indicators below the input. ←/→ (or tab/shift+tab) move between the actionable indicators, enter opens the matching view (model indicator → model selection, theme indicator → theme selection, A2A: indicator → registered A2A agents, Tools: indicator → available tools, background-jobs ⚙ indicator → task management), ↑/esc return to the input, and typing any other key lands back in the input seamlessly

Agent Modes:

The chat interface supports four operational modes that can be toggled with shift+tab:

  • Standard Mode (default): Normal operation with all configured tools and approval checks enabled. The agent has access to all tools defined in your configuration and will request approval for sensitive operations (Write, Edit, Delete, Bash, etc.).

  • Plan Mode: Read-only mode designed for planning and analysis. In this mode, the agent:

    • Can only use Read, Grep, Tree, and A2A_QueryAgent tools to gather information
    • Is instructed to analyze tasks and create detailed plans without executing changes
    • Provides step-by-step breakdowns of what would be done in Standard mode
    • Plan Approval: When the agent completes planning, you'll be prompted to:
      • Accept (Enter/y): Accept the plan and switch to Auto-Accept mode for execution
      • Reject (n or Esc): Reject the plan and provide feedback or changes
      • Approve Each Step (s): Accept the plan but stay in Standard mode, approving each action
    • Useful for understanding codebases or previewing changes before implementation

  • ⚡ Auto-Accept Mode (YOLO mode): All tool executions are automatically approved without prompting. The agent:

    • Has full access to all configured tools
    • Bypasses all approval checks and safety guardrails
    • Executes modifications immediately without confirmation
    • Ideal for trusted workflows or when rapid iteration is needed
    • Use with caution - ensure you have backups and version control

  • ⚖ Auto+Judge Mode: Autonomous with a gate: tool calls that would prompt a human are decided by an LLM judge (one call per gated tool) instead of a human, so the agent runs unattended but not unrestricted:

    • Uses the standard approval rules - allow-listed bash commands pass without a judge call
    • Gated calls are decided by the judge against your latest request; rejections arrive with the judge's reason
    • The model can ask you to override a rejection with the RequestApproval tool: the regular approval box opens with the judge's reason; approve runs that one call with the judge bypassed, reject feeds the decision back to the model
    • Configured in judge.yaml (model, timeout, max_tokens, on_error, prompt) - see Judge Mode
    • Ideal for CI and headless runs where an approval prompt would deadlock

The current mode is displayed below the input field when not in Standard mode. Toggle between modes anytime during a chat session.

System Reminders:

System reminders inject short <system-reminder> messages into the conversation at defined points of the agent loop (hook points) to keep durable guidance in context. They are configured in reminders.yaml (project ./.infer/ or ~/.infer/), each with a hook and a trigger. See System Reminders for the full schema.

  • Hook points: fire at pre_stream, post_tool, pre_session, and more
  • Triggers: gate firing - always, every Nth turn (interval), near the turn limit (turns_before_max), once per run, or only after a failed tool call (on_failure)
  • Non-intrusive: reminders are sent to the model but don't interrupt the user experience
  • Inline/CI supply: provide reminders without a file via INFER_REMINDERS_CONFIG (inline YAML) or --reminders-file PATH

Examples:

infer chat

infer headless

Execute a task using an autonomous agent in headless (non-interactive) mode. The CLI works iteratively until the task is considered complete. Particularly useful for SCM tickets like GitHub issues, CI/CD pipelines, and automated workflows.

Features:

  • Autonomous execution: Agent works independently to complete tasks
  • Iterative processing: Continues until task completion criteria are met
  • Tool integration: Full access to all available tools (Bash, Read, Write, etc.)
  • Parallel tool execution: Executes multiple tool calls simultaneously for improved efficiency
  • Background operation: Runs without interactive user input
  • Task completion detection: Automatically detects when tasks are complete
  • Configurable concurrency: Control the maximum number of parallel tool executions (default: 5)
  • Multiple output formats: --format json|ag-ui|text for different consumption patterns
  • Multimodal support: Process images and files with vision-capable models
  • Session resumption: Resume previous sessions to continue work from where it left off
  • Slash commands: The chat shortcuts work here too - see below

Slash commands:

A task that starts with a registered shortcut runs that command instead of being sent to the model verbatim:

  • Commands that produce a prompt (/init, a custom shortcut with a snippet) run that prompt as the task.
  • Commands that answer by themselves (/help, /context, /cost, /stats, /traces, /clear, /new, /compact, custom shortcuts) print their output and exit without calling a model.
  • Commands that only open a TUI panel (/diff, /explorer, /tools, /conversations) say so and exit 0.
  • Anything else keeping a leading slash - a skill invocation like /maintainer, a file path - is passed to the model unchanged.
infer headless "/init"      # writes AGENTS.md from the configured init prompt
infer headless "/cost"      # prints the session cost breakdown, no model call

Options:

  • -m, --model: Model to use`: Model to use (e.g. openai/gpt-4)
  • -f, --files: Files or images to include (can be specified multiple times)
  • --session-id: Resume an existing session by conversation ID
  • --no-save: Disable saving conversation to database
  • --require-approval: Enable IPC-based tool approval via stdin/stdout (used by channel manager)
  • --heartbeat: Use heartbeat system prompt (used by the heartbeat service)
  • --remote: Use remote-control system prompt (used by the daemon)
  • --result-file: Write the final assistant message and outcome as JSON to this path on exit
  • --format json|ag-ui|text: Output format (default json)
  • --mode: Agent mode: standard, plan, auto, auto-with-judge (env: INFER_AGENT_MODE); a value that fails validation, or auto-with-judge with no resolvable judge model, fails before the gateway or agent starts

Examples:

# Execute a task described in a GitHub issue
infer headless "Please fix the github issue 38"

# Use a specific model
infer headless --model "openai/gpt-4" "Implement the feature described in issue #42"

# Debug a failing test
infer headless "Debug the failing test in PR 15"

# Refactor code
infer headless "Refactor the authentication module to use JWT tokens"

# Analyze screenshots with vision-capable models
infer headless "Analyze this screenshot and identify the UI issue" --files screenshot.png

# Process multiple images
infer headless "Compare these diagrams and suggest improvements" -f diagram1.png -f diagram2.png

# Mix images and code files using @filename syntax
infer headless "Review @app.go and @architecture.png and suggest refactoring"

# Combine --files flag with @filename references
infer headless "Analyze @error.log and this screenshot" --files debug-screen.png

# Output as AG-UI protocol events
infer headless --format ag-ui "fix the failing test"

# Session resumption - list conversations to find session IDs
infer conversations list

conversations list

# Resume an existing session with new instructions
infer headless "continue fixing the authentication bug" --session-id abc-123-def

# Resume with additional files
infer headless "analyze these new error logs" --session-id abc-123-def --files error.log

# Resume without saving (testing mode)
infer headless "try a different refactoring approach" --session-id abc-123-def --no-save

Session Resumption:

The headless command supports resuming previous sessions, allowing you to continue work from where it left off:

  • Use infer conversations list to find available session IDs
  • Pass --session-id <id> to resume a specific session
  • The session history is loaded from storage and the new task description is appended
  • Turn counter resets to full budget when resuming
  • Session ID is preserved for continued persistence

Image and File Support:

The headless command supports multimodal content for vision-capable models:

  • Use --files or -f flag to attach images or files
  • Use @filename syntax in the task description to reference files
  • Supported image formats: PNG, JPEG, GIF, WebP
  • Images are automatically encoded as base64 and sent as multimodal content
  • Text files are embedded in code blocks
  • Requires gateway configuration: VISION_ENABLED=true

Utility Commands

infer status

Check the status of the inference gateway including health checks and resource usage.

Examples:

infer status

infer conversations

Inspect saved conversation history from the configured storage backend (works with jsonl, sqlite, postgres, redis, and memory - the command loads through the storage layer rather than reading files directly).

Subcommands:

  • list: List saved conversations with metadata (id, title, message/request counts, tokens, cost). Scoped to the current project by default; pass --all-projects for every project's conversations.
  • show <session-id>: Print a single conversation's entries in chronological order.

show flags:

  • --include-hidden: Include entries marked hidden - system reminders, plan-approval prompts, drained background-task results, and the synthetic verify message injected by infer headless. Off by default.
  • --format text|json: text (default) is human-readable; json emits one JSON object per line (NDJSON), matching the infer headless stdout shape for piping into jq or log scrapers.

The <session-id> is resolved the same way as infer headless --session-id: a literal UUID is used as-is, while any other value is treated as a session group key and resolved to that group's current session id (registering the group if it is new).

Examples:

# List conversations to find a session id
infer conversations list

# Show a conversation's entries (hidden entries omitted)
infer conversations show 12345678-1234-1234-1234-123456789abc

# Show by session group name (e.g. a channel group key)
infer conversations show channel-telegram-12345

# Include hidden entries such as system reminders
infer conversations show <session-id> --include-hidden

# One JSON object per line for piping into jq
infer conversations show <session-id> --format json | jq .

See conversation-storage.md for backend configuration.

infer conversation-title

Manage AI-powered conversation title generation. The CLI can automatically generate descriptive titles for conversations to improve organization and searchability.

Subcommands:

  • generate [conversation-id]: Generate titles for conversations (all or specific)
  • status: Show title generation status and statistics
  • daemon: Run title generation daemon in background

Examples:

# Generate titles for all conversations without titles
infer conversation-title generate

# Generate title for a specific conversation
infer conversation-title generate conv-12345

# Check title generation status
infer conversation-title status

# Run daemon for automatic title generation
infer conversation-title daemon

Features:

  • Automatic Generation: Titles are generated based on conversation content
  • Batch Processing: Generate titles for multiple conversations at once
  • Configurable Model: Use any available model for title generation
  • Background Daemon: Optional daemon mode for continuous title generation

Configuration:

conversation:
  title_generation:
    enabled: true
    model: "deepseek/deepseek-v4-pro"
    batch_size: 5
    interval: 30  # seconds between generation attempts

For more details, see the Conversation Title Generation documentation.

infer version

Display version information for the Inference Gateway CLI.

Examples:

infer version

← Back to README