Skip to content

Latest commit

 

History

History
145 lines (105 loc) · 5.59 KB

CLI_SPEC.md

File metadata and controls

145 lines (105 loc) · 5.59 KB

CLI Specification for rx

This document details the command-line interface for the rx autonomous agent.

Usage

rx [OPTIONS] [GOAL]...

Arguments

Argument Description
[GOAL]... The goal or task description for the agent to execute. Multiple words are joined by spaces. Required unless using --list or --resume.

Options

Option Description Default
--max-iterations <N> Sets the maximum number of iterations the agent is allowed to perform. 50
--auto-commit Enables auto-commit mode. The agent will automatically commit changes to the state. false
--resume <GOAL_ID> [Ignored in Phase 1] Resumes a previously started session identified by GOAL_ID. None
--debug-log <PATH> Writes structured debug events to the supplied file (JSONL). The path may contain a {goal_id} placeholder that is substituted with the active goal ID. disabled
--list Lists all stored goals and their IDs with timestamps. false
--tool-verbose Prints tool inputs and outputs to stdout during execution. false
--model <NAME> Overrides the main agent model for this run. config value, then OPENAI_MODEL, then gpt-4o
--small-model <NAME> Overrides the small model for this run (auto-commit + goal slug generation). config value (or gpt-5-mini when auto-commit enabled)
--agent <NAME> Activates a named agent profile defined in .rx/config.toml, applying profile-specific defaults and optional model overrides. none

New sessions are assigned goal IDs in this format: YYYYMMDD-HHMMSS-<goal-slug>.

<goal-slug> is derived from the goal text. If small_model is configured and OPENAI_API_KEY is present, rx asks the small model to produce the slug and then sanitizes it.

Agent Profile Overrides

You can bundle deterministic defaults for a workspace by defining a named agent profile in .rx/config.toml. The profile looks like:

[agent]
name = "writer"
model = "gpt-5.3-codex"

[agent.cli_defaults_overrides]
max_iterations = 80
tool_verbose = true

When rx --agent writer runs, --agent acts as an overlay between [cli_defaults] and explicit CLI flags. Precedence is:

  1. Built-in defaults
  2. [cli_defaults]
  3. [agent.cli_defaults_overrides]
  4. Explicit CLI flags

Requesting a profile that does not match any [agent] entry is a hard error. Unknown keys inside the profile are ignored with a warning, keeping deterministic behavior intact.

Environment Variables

Variable Description Default
OPENAI_API_KEY The API key for OpenAI. If not set, the agent defaults to using a MockModel for testing. None
OPENAI_MODEL The specific OpenAI model to use. gpt-4o

Files

File Description Location
LOOP_PROMPT.md The system prompt file used to initialize the agent's context. Current working directory
rx_state.db The SQLite database storing agent state and history. System local data directory (e.g., ~/.local/share/rx_data/ on Linux/macOS)
config.toml File for loading default CLI parameter values. <workspace-root>/.rx/config.toml

Examples

Start a new task

rx "Refactor the authentication module to use JWT"

Start a task with a higher iteration limit

rx --max-iterations 100 "Analyze the logs for error patterns"

Override models for one run

rx --model gpt-5.2-codex --small-model gpt-5-mini "Refactor auth flow"

List previous sessions

rx --list

Resume a previous session

rx --resume 20231027-103000-refactor-auth-module

Configuration File Specification

rx loads a local .rx/config.toml to set default CLI options.

.rx/config.toml schema:

[cli_defaults]
max_iterations = 50         # Positive integer
auto_commit = false         # Boolean
small_model = ""            # String model name for commit messages and optional goal slug generation
resume = ""               # String goal ID (ignored in Phase 1)
debug_log = ""             # Path string (empty disables logging). Supports `{goal_id}` placeholder to embed the goal ID.
list = false                # Boolean
model_name = ""            # String model name for main agent
tool_verbose = false        # Boolean

[agent]
name = "writer"            # Required profile identifier. Must match `--agent` when specified.
model = "gpt-5.3-codex"    # Optional override for the CLI `--model` value when this profile is active.

[agent.cli_defaults_overrides]
# Same schema as [cli_defaults]; values overlay `[cli_defaults]` when the profile is active.

[tools]
enabled = ["read_file", "write_file", "done"] # Optional allow-list. Missing = all built-in tools.
disabled = ["exec"]                            # Optional deny-list applied after `enabled`.

Place this configuration file at the root of the workspace. Missing keys fall back to the CLI_SPEC.md defaults.

When --auto-commit is enabled and small_model is unset, commit messages default to the gpt-5-mini model.

auto_commit_model is accepted as a deprecated compatibility key and is used only when small_model is not set.

Tool registry behavior:

  • If [tools] is omitted, all built-in tools are registered.
  • enabled limits the registry to listed tools (unknown names are ignored with a warning).
  • disabled removes listed tools after enabled is applied (unknown names are ignored with a warning).
  • done is always kept registered even if excluded/disabled.

For more details on configuration and precedence rules, refer to CONFIG_SPEC.md.