Output System

Output System

Tooli's output system provides dual-mode output: human-friendly Rich formatting for terminals, and structured JSON for agents and scripts.

Output Modes

Mode	Flag	Description
AUTO	--output auto	Default. Uses Rich for TTY, JSON for pipes
JSON	--json / --output json	JSON envelope to stdout
JSONL	--jsonl / --output jsonl	One JSON object per line for lists
TEXT	--text / --output text	Plain str() output, no color
PLAIN	--plain / --output plain	Alias for TEXT

When multiple output flags are provided, the last one wins.

JSON Envelope

All JSON/JSONL output is wrapped in a standard envelope:

Success

{
  "ok": true,
  "result": { "files": ["a.txt", "b.txt"], "count": 2 },
  "meta": {
    "tool": "file-tools.find-files",
    "version": "4.1.0",
    "duration_ms": 42,
    "warnings": [],
    "caller_id": "claude-code",
    "caller_version": "1.5.3",
    "session_id": "sess-abc123"
  }
}

Error

{
  "ok": false,
  "error": {
    "code": "E3001",
    "category": "state",
    "message": "Resource not found",
    "is_retryable": false,
    "suggestion": {
      "action": "check",
      "fix": "Verify the resource ID exists",
      "example": "mytool list-resources",
      "applicability": "always"
    },
    "details": {}
  },
  "meta": {
    "tool": "file-tools.get-resource",
    "version": "1.0.0",
    "duration_ms": 15,
    "warnings": []
  }
}

JSONL Mode

For commands returning lists, JSONL emits one envelope per item:

{"ok": true, "result": {"name": "a.txt"}, "meta": {...}}
{"ok": true, "result": {"name": "b.txt"}, "meta": {...}}

Global Flags

Flag	Short	Description
--output	-o	Set output mode explicitly
--json		Alias for --output json
--jsonl		Alias for --output jsonl
--text		Alias for --output text
--plain		Alias for --output plain
--quiet	-q	Suppress Rich formatting in human mode
--verbose	-v	Increase verbosity (stackable: -vvv)
--dry-run		Preview actions without executing
--yes		Skip interactive confirmation prompts
--timeout		Command execution timeout in seconds
--schema		Print JSON Schema and exit
--help-agent		Token-optimized help output
--response-format		concise (default) or detailed
--no-color		Disable Rich markup (also respects NO_COLOR env var)

Caller-Aware Output (v4.1)

When TOOLI_CALLER is set in the environment, the envelope meta section includes caller_id, caller_version, and session_id fields. This enables correlation across multiple CLI calls within an agent session. See the Agent Integration Guide for details.

Resolution Order

1. Explicit --output or alias flag
2. TOOLI_OUTPUT environment variable
3. TOOLI_CALLER detection (agents default to JSON)
4. TTY detection: TTY → AUTO (Rich), non-TTY → JSON

Return Value Routing

Commands return Python values. TooliCommand captures the return value and routes it through the output system:

• None → no output (preserves standard Typer behavior)
• dict / str / int → wrapped in envelope for JSON modes, printed directly for text modes
• list[dict] → individual items for JSONL, full list for JSON