REPL & Execute Mode

REPL Mode

Line-oriented interface for scripting, piping, and environments without full terminal support.

ugent --repl

Features

• Streaming output to stdout
• Slash commands (same as TUI)
• Session resume: --continue or --resume <session-id>
• Ctrl+C / Esc to cancel the current turn
• /setup wizard with interactive prompts

Piping

echo "Summarize this file" | ugent --repl
cat error.log | ugent --repl

Scripting

# Single-shot with clean output (no diagnostics)
ugent --execute "What does this project do?"

# JSON output for programmatic use
ugent --execute "List all TODO comments" --output json

# JSON-Seq event stream
ugent --execute "Refactor the auth module" --output json-seq

# Stream to stderr while JSON goes to stdout
ugent --execute "Analyze dependencies" --output json --show-assistant

Execute Mode

Single-shot execution — sends one query, gets the answer, exits.

ugent --execute "Explain the architecture"

Flags

Flag	Description
--show-assistant	Stream assistant text to stdout in real time
--verbose	Show diagnostic output (INFO, WARN, BOOT)
--output json	Single JSON envelope with the final result
--output json-seq	JSON-Seq event stream (every event as a record)
--continue	Resume the latest session for this workspace
--resume <id>	Resume a specific session by ID

Output Modes

Default (no flags): Clean output — only the final answer and iteration count. All diagnostics suppressed.

--verbose: Restores the diagnostic stderr output that was previously the default.

--show-assistant: Streams UGENT: <text> chunks to stdout (or stderr when combined with --output json).

--output json: Returns a single JSON envelope:

{
  "result": "...",
  "session_id": "...",
  "iterations": 3,
  "tokens": { "input": 1200, "output": 800 }
}

--output json-seq: Emits every agent event as a JSON-Seq record — LLM chunks, tool calls, tool results, delegation events.

Session Resume

# Capture the session ID from JSON output
SESSION=$(ugent --execute "Start analyzing" --output json | jq -r '.session_id')

# Resume it later
ugent --execute "Continue the analysis" --resume "$SESSION"

Only kind=main sessions can be resumed. Worker and cron sessions are filtered out.

Headless Safety

When no interactive responder is available (SSH pipe, CI):

• ask_user_input fails fast with actionable guidance
• Bash commands requiring confirmation are rejected
• The agent receives clear error messages instead of hanging