Output Modes

The CLI supports two output modes that control how results are formatted. The correct mode is chosen automatically based on context, but you can always override it.

Human Mode

Human mode renders rich, colored output designed for interactive terminal use — tables, boxes, labels, and highlighted values.

Account:  you@example.com
Credits:  4,820 remaining
Plan:     Pro

This is the default when the CLI detects it is attached to an interactive terminal (TTY).

Agent Mode

Agent mode writes raw JSON to stdout and errors to stderr. There is no additional formatting or color.

{
  "email": "you@example.com",
  "credits": 4820,
  "plan": "pro"
}

This is the default when the CLI detects it is running in a non-interactive context — inside a script, a pipe, or an AI agent tool call.

Auto-Detection

The CLI checks whether stdout is a TTY at startup:

• TTY detected → human mode
• No TTY (pipe, script, subprocess) → agent mode

This means piping output or calling the CLI from a tool handler automatically produces clean JSON without any extra flags.

# Auto human mode (interactive terminal)
reddgrow reddit subreddits posts rust

# Auto agent mode (piped — stdout is not a TTY)
reddgrow reddit subreddits posts rust | jq '.[].title'

Forcing a Mode

Override auto-detection with the --mode flag or the REDDGROW_MODE environment variable.

Per-command flag

reddgrow reddit subreddits posts rust --mode agent
reddgrow reddit subreddits posts rust --mode human

Environment variable

export REDDGROW_MODE=agent
reddgrow reddit subreddits posts rust   # always outputs JSON

REDDGROW_MODE=agent reddgrow reddit posts search "typescript tips" | jq '.data.children[].data.title'

The --mode flag takes precedence over the environment variable.

Side-by-Side Example

Command:

reddgrow auth whoami

Human mode output:

Account:  you@example.com
Credits:  4,820 remaining
Plan:     Pro

Agent mode output:

{
  "email": "you@example.com",
  "credits": 4820,
  "plan": "pro"
}

Async reads and --no-wait

Reddit reads are async jobs. In both modes the CLI waits for the job and prints the same result. With the global --no-wait flag it prints the jobId instead (as JSON in agent mode) and exits. Use reddgrow reddit job <id> to fetch the status or result later.

reddgrow reddit subreddits posts rust --no-wait --mode agent
reddgrow reddit job <id> --mode agent

Precedence

1. --mode flag (highest)
2. REDDGROW_MODE environment variable
3. TTY auto-detection (default)