Command reference
On Sun, 04 Oct 2026, by @lucasdicioccio, 287 words, 8 code snippets, 11 links, 0images.
Generated from README.md, the repository is the canonical source and may be ahead of this page.
Command reference
The exact help text of each command, as printed by the binary this site was produced with: agents-exe –help, check, config, init, run, tui, serve, mcp-server, session, describe, new.
Command Reference
Global Options
These options apply to all commands:
| Option | Default | Description |
|---|---|---|
--api-keys FILE | ~/.config/agents-exe/secret-keys | Path to JSON file containing API keys |
--log-file LOGFILE | agents-logfile | Raw log file for debugging |
--log-http URL | (none) | HTTP endpoint for JSON log sink |
--log-json-file FILE | (none) | Local JSON file log sink |
--session-json-file-prefix PREFIX | (none) | Prefix for session JSON files |
--agent-file AGENTFILE | (auto-discovered) | Root agent description file(s). Can be specified multiple times. Defaults to agent.json |
Commands
check
Validates agent configuration files.
agents-exe check
agents-exe check --agent-file custom-agent.json
init
Initializes a new agent project with a sample agent.json and tools directory structure.
agents-exe init
agents-exe init --agent-file my-agent.json
tui - Terminal User Interface
Launches an interactive terminal UI for chatting with agents.
agents-exe tui
agents-exe tui --agent-file my-agent.json
run - Execute a One-Shot Command
Runs a single prompt through an agent and outputs the result.
Prompt Options:
| Option | Short | Description |
|---|---|---|
--prompt TEXT | -p | Add a text paragraph to the prompt |
--file FILE | -f | Include contents of a file in the prompt |
--shell CMD | Include stdout of a shell command in the prompt | |
--sep4 SEP | -s | Add a short separator (4 repetitions) |
--sep40 SEP | -S | Add a long separator (40 repetitions) |
--session-file FILE | Resume from or save to a session file |
Examples:
# Simple prompt
agents-exe run --prompt "Hello, how are you?"
# Include file contents
agents-exe run --prompt "Summarize this:" --file README.md
# Include command output
agents-exe run -p "Explain this diff:" -s "---" --shell "git diff"
# Multiple prompts (concatenated with newlines)
agents-exe run -p "First part" -p "Second part"
# Resume a session
agents-exe run --session-file previous.json -p "Continue where we left off"
echo-prompt
Echoes the constructed prompt without sending it to the agent. Useful for debugging prompt construction.
agents-exe echo-prompt -p "Hello" -f README.md
describe
Outputs a JSON self-description of the tool interface. Useful when agents-exe is used as a sub-tool.
agents-exe describe
mcp-server
Runs agents-exe as an MCP (Model Context Protocol) server, exposing agents as tools via stdin/stdout.
agents-exe mcp-server
agents-exe mcp-server --agent-file agent1.json --agent-file agent2.json
The MCP server exposes each configured agent as a callable tool to MCP clients like Claude Desktop.
session-print
Prints a session file in human-readable markdown format.
| Option | Description |
|---|---|
--show-tool-call-results | Show the results of tool calls |
--n-turns N | Limit output to first N turns |
--repeat-system-prompt | Repeat system prompt at each turn |
--repeat-tools | Repeat available tools at each turn |
--antichronological | Display newest turns first (default: oldest first) |
Examples:
# Print entire session
agents-exe session-print my-session.json
# Print with tool results
agents-exe session-print --show-tool-call-results my-session.json
# Print last 10 turns only, newest first
agents-exe session-print --n-turns 10 --antichronological my-session.json