CLI Reference

agents-exe [GLOBAL_OPTS] COMMAND [COMMAND_OPTS]

agents-exe check [--tools MODE] [--show-config]

# Check default agents
agents-exe check

# Check specific agent
agents-exe check --agent-file ./custom-agent.json

# List tools in agents-exe format
agents-exe check --tools agents-exe

agents-exe run [OPTIONS]

{"status": "paused",
 "reason": "waiting for deferred tool calls",
 "session_id": "…",
 "deferred_calls": [{"tool": "approve_deploy", "tool_call_id": "call_9", "continuation_token": "…"}]}

# Auto-detect MIME type from extension
agents-exe run -m /path/to/image.png --prompt "Describe this image"

# Explicit MIME type (semicolon separator)
agents-exe run -m "image/jpeg;/path/to/photo.jpg" --prompt "Analyze this photo"

# Simple prompt
agents-exe run --agent-file agent.json --prompt "Hello!"

# Read from file
agents-exe run --agent-file agent.json --file prompt.txt

# Shell command output as prompt
agents-exe run --agent-file agent.json --shell "git diff"

# Resume session
agents-exe run --agent-file agent.json --session-file session.json

# Use alias
agents-exe run --agent-file agent.json --alias code-review --file changes.patch

# Multi-part prompt with separators
agents-exe run \
  --prompt "Review this code:" \
  --sep4 "----" \
  --file code.py \
  --sep40 "========================================" \
  --prompt "What improvements can be made?"

# Inject previous session at medium verbosity
agents-exe run \
  --agent-file agent.json \
  --session-m previous-session.json \
  --prompt "Continue from where we left off"

# Attach single image
agents-exe run \
  --agent-file vision-agent.json \
  -m ./screenshot.png \
  --prompt "What do you see in this image?"

# Attach multiple images
agents-exe run \
  --agent-file vision-agent.json \
  -m ./image1.png \
  -m ./image2.jpg \
  -m "image/gif;./animation.gif" \
  --prompt "Compare these images"

# Attach document for analysis
agents-exe run \
  --agent-file document-agent.json \
  -m ./report.pdf \
  --prompt "Summarize the key findings"

# Combine media with text from file
agents-exe run \
  --agent-file multimodal-agent.json \
  --prompt "Analyze this diagram and code:" \
  -m ./diagram.png \
  --sep4 "----" \
  --file ./source-code.py

agents-exe tui [--agent-file FILE...] [--keymap FILE] [--db PATH]
agents-exe tui --attach URL|PATH [--token TOKEN | --token-file FILE] [--keymap FILE]

# Single agent TUI
agents-exe tui --agent-file agent.json

# Multi-agent TUI
agents-exe tui \
  --agent-file coder.json \
  --agent-file reviewer.json \
  --agent-file tester.json

# Attach to a server started elsewhere with `agents-exe serve`
agents-exe tui --attach http://127.0.0.1:8080
agents-exe tui --attach unix:///run/agents/agents.sock
agents-exe tui --attach https://agents.example --token-file ~/.agents-token

agents-exe spectate --attach URL|PATH [--token TOKEN | --token-file FILE]
                    [--panels SPEC] [--refresh SECONDS] [--layout-file FILE]

--panels tree,tools,text               # three equal columns
--panels text                          # only the text
--panels tree+tools+text               # one stack
--panels text/70,tree:30+tools:70/30   # text on the left, wide

# In one terminal: a server, and a TUI or any other client driving it
agents-exe serve --socket /run/agents/agents.sock --stream-tokens
agents-exe tui --attach /run/agents/agents.sock

# In another: watch
agents-exe spectate --attach /run/agents/agents.sock

# The same, as three columns refreshed twice a second
agents-exe spectate --attach /run/agents/agents.sock --panels tree,tools,text --refresh 0.5

agents-exe mcp-server [--agent-file FILE...]

# Single agent MCP server
agents-exe mcp-server --agent-file agent.json

# Multi-agent MCP server
agents-exe mcp-server \
  --agent-file research-agent.json \
  --agent-file writing-agent.json

agents-exe echo-prompt [OPTIONS]

agents-exe echo-prompt \
  --prompt "Context:" \
  --file context.txt \
  --prompt "Question:" \
  --file question.txt

agents-exe session-print [OPTIONS] SESSIONFILE

# Print full session
agents-exe session-print session.json

# Print with tool results visible
agents-exe session-print --show-tool-call-results shown session.json

# Elide long outputs (show first/last 10 lines)
agents-exe session-print --show-tool-call-results elided session.json

# Last 5 turns only
agents-exe session-print --n-turns 5 session.json

# Reverse order
agents-exe session-print --antichronological session.json

agents-exe session-edit [OPTIONS] < input.json > output.json

# Keep only first 10 turns
agents-exe session-edit --take --count 10 < session.json > trimmed.json

# Keep only last 5 turns
agents-exe session-edit --take-tail --count 5 < session.json > recent.json

# Remove first 2 turns
agents-exe session-edit --drop --count 2 < session.json > dropped.json

# Remove all tool calls
agents-exe session-edit --censor-tool-calls < session.json > no-tools.json

# Remove thinking content
agents-exe session-edit --censor-thinking < session.json > no-thinking.json

agents-exe session-index [OPTIONS]

# Build the search index
agents-exe session-index --build

# Check index status
agents-exe session-index --status

# Update index incrementally
agents-exe session-index --update

# Remove the index
agents-exe session-index --clean

# Build with tool outputs included
agents-exe session-index --build --include-tool-outputs

# Custom database location
agents-exe session-index --build --db-path ~/.config/agents-exe/search.db

agents-exe session-search [OPTIONS] "QUERY"

# Basic fuzzy search
agents-exe session-search "database error"

# Search with auto-update
agents-exe session-search "migration" --auto

# Include tool outputs in search
agents-exe session-search "config.yaml" --include-tool-outputs

# Filter by date and tool
agents-exe session-search "auth" --after 2024-01-01 --tool write-file

# Filter by agent
agents-exe session-search "refactor" --agent my-coder

# JSON output for scripting
agents-exe session-search "TODO" --json

# Show context lines
agents-exe session-search "deploy" --preview 5

# Combined filters
agents-exe session-search "fix" --after 2024-01-01 --before 2024-12-31 --tool bash_write-file --json

{
  "resultItems": [
    {
      "resultMetadata": {
        "resultSessionId": "550e8400-e29b-41d4-a716-446655440000",
        "resultFilePath": "/path/to/session.json",
        "resultAgentSlug": "my-agent",
        "resultTurnCount": 15,
        "resultRank": 0.5
      },
      "resultPreview": "...context around match...",
      "resultMatchedTerms": ["error", "database"]
    }
  ],
  "resultTotalMatches": 42,
  "resultQueryTimeMs": 15.3,
  "resultIndexWasUpdated": false
}

agents-exe list-tool-calls [OPTIONS] SESSIONFILE

# List tool calls in human-readable format
agents-exe list-tool-calls session.json

# Output as JSON
agents-exe list-tool-calls session.json --format json

# Brief format for quick overview
agents-exe list-tool-calls session.json --format brief

agents-exe replay-tool-call --session FILE --tool-call INDEX --tool TOOLPATH [OPTIONS]

# First, list tool calls to find the index
agents-exe list-tool-calls session.json

# Validate and execute a tool call
agents-exe replay-tool-call \
  --session session.json \
  --tool-call 0 \
  --tool ./tools/read-file.sh

# Only validate without executing
agents-exe replay-tool-call \
  --session session.json \
  --tool-call 1 \
  --tool ./tools/grep-files.sh \
  --validate-only

# Execute and show raw output
agents-exe replay-tool-call \
  --session session.json \
  --tool-call 2 \
  --tool ./tools/write-file.sh \
  --raw

echo '{}' | agents-exe tool-call TOOLNAME [OPTIONS]

# Call a tool with arguments
echo '{"filepath": "./README.md"}' | \
    agents-exe tool-call read-file --agent-file ./agent.json

# Call with logging
echo '{"command": "ls -la"}' | \
    agents-exe tool-call bash --log-file ./tool-debug.log

agents-exe serve [--agent-file FILE...] [--agent SLUG] [OPTIONS]

# Explicit agent files, like agents-server
agents-exe serve --agent-file ./weather.json --api-keys ./keys.json --port 8080

# From a directory with an agents-exe.cfg.json
agents-exe serve --port 8080

# One agent from a multi-agent config, over a local socket only auth-tokens gate
agents-exe serve --agent architect --socket /run/agents-exe/agents.sock --auth-tokens ./tokens.json

cat payload.json | agents-exe check-tool-call --tool TOOLPATH

# Create a test payload
echo '{"filepath": "/path/to/file"}' | agents-exe check-tool-call --tool ./tools/read-file.sh

# Validate from file
cat payload.json | agents-exe check-tool-call --tool ./tools/my-tool.sh

agents-exe init [--agent-file FILE]

agents-exe init --agent-file ./my-agent.json

agents-exe new (agent|tool) [OPTIONS]

agents-exe new agent SLUG FILE [MODEL] [OPTIONS]

# Create agent with the default OpenAI preset
agents-exe new agent my-assistant ./my-assistant.json

# Create agent with custom model (preset inferred from the catalog)
agents-exe new agent coder ./coder.json gpt-4o

# Create agent in a subdirectory and list it in agents-exe.cfg.json
agents-exe new agent my-assistant ./agents/assistant.json --add-to-config

# Overwrite existing
agents-exe new --force agent my-assistant ./my-assistant.json

{
  "tag": "OpenAIAgentDescription",
  "contents": {
    "slug": "my-assistant",
    "apiKeyId": "main-key",
    "flavor": "OpenAIv1",
    "modelUrl": "https://api.openai.com/v1",
    "modelName": "gpt-4-turbo-preview",
    "announce": "a helpful assistant powered by gpt-4-turbo-preview",
    "systemPrompt": [
      "You are my-assistant, a helpful AI assistant.",
      "You provide clear, accurate, and concise responses.",
      "When using tools, you explain your actions to the user."
    ],
    "toolDirectory": "tools",
    "mcpServers": [],
    "fileSandboxes": {
      "workspace": {
        "fsbPredicate": {"tag": "DirectoryRecursive", "contents": "./"},
        "fsbMaxFileSize": 52428800,
        "fsbName": null
      }
    },
    "builtinToolboxes": [
      {
        "tag": "DeveloperToolbox",
        "contents": {
          "Name": "developer",
          "Description": "Tools for developing agents and tools",
          "Capabilities": ["show-spec", "validate-agent", "create-agent", "create-tool", "read-file-range", "write-file-range", "patch-file"],
          "FileSandbox": {"ref": "workspace"}
        }
      },
      {
        "tag": "SystemToolbox",
        "contents": {
          "Name": "system",
          "Description": "Working directory and directory listings",
          "Capabilities": ["working-directory", "list-directory"],
          "FileSandbox": {"ref": "workspace"}
        }
      },
      {
        "tag": "SqliteToolbox",
        "contents": {
          "Name": "memory",
          "Description": "Notes and facts to remember across conversations",
          "Versioning": {"tag": "SqliteReadWrite", "path": "./my-assistant-memory.sqlite"}
        }
      }
    ]
  }
}

agents-exe new tool SLUG LANGUAGE FILE [OPTIONS]

# Create bash tool (default)
agents-exe new tool my-tool bash ./tools/my-tool

# Create Python tool
agents-exe new tool my-tool python ./scripts/my-tool

# Create Haskell tool
agents-exe new tool my-tool haskell ./tools/my-tool

# Create Node.js tool
agents-exe new tool my-tool node ./scripts/my-tool

#!/bin/bash
# my-tool - A bash tool for agents-exe

set -euo pipefail

# Agents-exe tool protocol: describe|run
# Environment variables available during 'run':
#   AGENT_SESSION_ID      - UUID of the current session
#   AGENT_CONVERSATION_ID - UUID of the conversation
#   AGENT_TURN_ID         - UUID of the current turn
#   AGENT_AGENT_ID        - UUID of the executing agent (if available)

case "${1:-}" in
  describe)
    cat <<'DESCRIBE_EOF'
{
  "slug": "my-tool",
  "description": "Tool my-tool - describe what this tool does",
  "args": [],
  "empty-result": {
    "tag": "AddMessage",
    "contents": "--no output--"
  }
}
DESCRIBE_EOF
    ;;
  run)
    # TODO: Implement tool logic
    # Access arguments via environment or command line
    echo "Tool my-tool executed"
    ;;
  *)
    echo "Usage: my-tool <describe|run>" >&2
    exit 1
    ;;
esac

agents-exe config [-f|--force] (local|keymap|api-key) ...

agents-exe config local init

agents-exe config keymap init FILE

agents-exe config api-key list

agents-exe config api-key create NAME

# Start a project: config file, then an agent listed in it
agents-exe config local init
agents-exe new agent helper ./helper.json --add-to-config

# Declare the key the agent's preset refers to, then fill in its value
agents-exe config api-key create main-key
agents-exe config api-key list

# Customize the TUI key bindings
agents-exe config keymap init ./keymap.json

agents-exe spec TOPIC

# Display bash-tools specification
agents-exe spec bash-tools

agents-exe describe-tool TOOL_PATH [OPTIONS]

agents-exe describe-tool ./tools/my-tool.sh

# Pretty format
agents-exe describe-tool ./tools/my-tool.sh --format pretty

# Only check validity
agents-exe describe-tool ./tools/my-tool.sh --check-only

{
  "slug": "my-tool",
  "description": "What this tool does",
  "args": [...],
  "empty-result": {...}
}

agents-exe paths [OPTIONS]

# Human-readable output
agents-exe paths

# JSON output
agents-exe paths --json

agents-exe export [OPTIONS]

# Export to tar.gz
agents-exe export --output ./my-agent.tar.gz

# Export to git
agents-exe export \
  --git-url https://github.com/user/agents-repo \
  --git-branch main \
  --git-message "Update agent" \
  --git-push

# Export tools only
agents-exe export --tools-only --output ./tools.tar.gz

# Export specific agent
agents-exe export --agent-slug my-agent --output ./agent.tar.gz

# With namespace
agents-exe export --namespace team-a.project-1 --output ./export.tar.gz

agents-exe import [OPTIONS]

# Import from archive
agents-exe import --from-file ./agent.tar.gz

# Import from git
agents-exe import \
  --git-url https://github.com/user/agents-repo \
  --git-ref main

# Import tools to agent
agents-exe import \
  --from-file ./tools.tar.gz \
  --install-to-agent ./my-agent.json

# Import with overwrite
agents-exe import --from-file ./agent.tar.gz --overwrite

# List namespaces
agents-exe import --git-url https://github.com/user/repo --list-namespaces

# Import specific namespace
agents-exe import \
  --git-url https://github.com/user/repo \
  --namespace team-a.tools \
  --to ./tools/

agents-exe cowsay [MESSAGE] [OPTIONS]

agents-exe cowsay "Hello, agents!"

# With custom width
agents-exe cowsay "A much longer message that needs more space" --width 60

# Pipe from another command
echo "System ready" | agents-exe cowsay

agents-exe describe [OPTIONS]

agents-exe self-describe

{
  "agentsConfigDir": "/custom/config/path",
  "agentsDirectories": [
    "./agents",
    "./more-agents"
  ],
  "agentsFiles": [
    "./main-agent.json"
  ],
  "promptAliases": {
    "translate": {
      "systemPrompt": ["You are a translator..."],
      "userPromptPrefix": "Translate to English:"
    }
  },
  "selfDescribeSlug": "my-agent",
  "selfDescribeDescription": "A custom agent",
  "agentsLogs": {
    "logJsonHttpEndpoint": "http://localhost:8080/log",
    "logJsonPath": "./logs/agents.json",
    "logRawPath": "./logs/agents.log"
  },
  "sessions": {
    "writeLocation": "./sessions/",
    "readLocations": [
      "./sessions/",
      "./.agents-sessions/",
      "~/.config/agents-exe/sessions/"
    ]
  }
}

# 1. Initialize new agent
agents-exe new agent my-assistant

# 2. Create a custom tool
agents-exe new tool file-reader python ./tools/file-reader

# 3. Edit tool and agent configurations
# (edit files as needed)

# 4. Check configuration
agents-exe check --agent-file ./my-assistant.json

# 5. Test with one-shot
agents-exe run --agent-file ./my-assistant.json --prompt "Test"

# 6. Start interactive session
agents-exe tui --agent-file ./my-assistant.json

# 7. Export for sharing
agents-exe export --agent-file ./my-assistant.json --output ./my-assistant.tar.gz

# 8. Import elsewhere
agents-exe import --from-file ./my-assistant.tar.gz --to ./new-location/

# Start multi-agent TUI
agents-exe tui \
  --agent-file ./router.json \
  --agent-file ./coder.json \
  --agent-file ./reviewer.json

# Start multi-agent MCP server
agents-exe mcp-server \
  --agent-file ./router.json \
  --agent-file ./coder.json

# Run an agent session
agents-exe run \
    --agent-file ./my-agent.json \
    --session-file ./session.json \
    --prompt "Let's work on a project"

# Later, inspect the session
agents-exe session-print ./session.json

# List all tool calls from the session
agents-exe list-tool-calls ~/.config/agents-exe/sessions/session-*.json

# Replay a specific tool call for debugging
agents-exe replay-tool-call \
  --session ./session.json \
  --tool-call 0 \
  --tool ./tools/read-file.sh \
  --validate-only

# Trim to last 20 turns
agents-exe session-edit --take-tail --count 20 < ./session.json > ./trimmed.json
mv ./trimmed.json ./session.json

# Continue the session
agents-exe run \
    --agent-file ./my-agent.json \
    --session-file ./session.json \
    --prompt "Where were we?"

# Build the search index
agents-exe session-index --build

# Search for error-related sessions
agents-exe session-search "error" --json

# Find sessions using specific tool after a date
agents-exe session-search "config" --after 2024-01-01 --tool write-file

# Search with context preview
agents-exe session-search "TODO" --preview 3

# Auto-update index before searching
agents-exe session-search "refactor" --auto --limit 10

# Analyze a screenshot with a vision-capable agent
agents-exe run \
    --agent-file ./vision-agent.json \
    -m ./screenshot.png \
    --prompt "What UI issues do you see in this screenshot?"

# Analyze multiple images
agents-exe run \
    --agent-file ./design-agent.json \
    -m ./mockup-v1.png \
    -m ./mockup-v2.png \
    --prompt "Compare these two design mockups and recommend which to use"

# Analyze a PDF document
agents-exe run \
    --agent-file ./document-agent.json \
    -m ./report.pdf \
    --prompt "Summarize the key findings and recommendations"

# Combine image with code for debugging
agents-exe run \
    --agent-file ./debug-agent.json \
    --prompt "This error appears in the UI:" \
    -m ./error-screenshot.png \
    --sep4 "----" \
    --prompt "Here's the relevant code:" \
    --file ./src/Main.hs

# Process all files in directory
for file in *.txt; do
    agents-exe run \
        --agent-file ./processor.json \
        --prompt "Process this file:" \
        --file "$file" \
        --prompt "End of file."
done

# Git pre-commit hook
agents-exe run \
    --agent-file ./reviewer.json \
    --shell "git diff --cached" \
    --prompt "Review these changes."

# Daily summary from logs
agents-exe run \
    --agent-file ./summarizer.json \
    --shell "cat /var/log/app.log | tail -100" \
    --prompt "Summarize any errors or warnings"

# Automated image analysis with timestamp
agents-exe run \
    --agent-file ./monitor-agent.json \
    -m ./screenshots/$(date +%Y%m%d-%H%M%S).png \
    --prompt "Check for any alerts or errors in this status dashboard"

# Learn the tool protocol
agents-exe spec bash-tools

# Create and validate a tool
agents-exe new tool my-validator bash ./tools/my-validator
# (edit the tool)
agents-exe describe-tool ./tools/my-validator --format pretty

# Validate a payload
echo '{"input": "test"}' | agents-exe check-tool-call --tool ./tools/my-validator

# Test the tool directly
echo '{"input": "test"}' | agents-exe tool-call my-validator

# Create agent with dev tools
agents-exe new agent dev-assistant
# (add DeveloperToolbox to builtinToolboxes)
# Now the agent can use developer file-editing tools and show specs!

# Create a tool that outputs media
agents-exe new tool chart-generator bash ./tools/chart-gen
# Add to describe output:
#   "output-media-type": "image/png"
# Now the tool's output is treated as a PNG image

# Run an agent session
agents-exe run --agent-file ./my-agent.json --prompt "Read the README"

# Find the session file
agents-exe paths

# List all tool calls
agents-exe list-tool-calls ~/.config/agents-exe/sessions/session-*.json

# Replay with validation only
agents-exe replay-tool-call \
  --session ~/.config/agents-exe/sessions/session-xxx.json \
  --tool-call 0 \
  --tool ./tools/read-file.sh \
  --validate-only

# Actually replay the tool call
agents-exe replay-tool-call \
  --session ~/.config/agents-exe/sessions/session-xxx.json \
  --tool-call 0 \
  --tool ./tools/read-file.sh