Output & filtering

Every hscli command shares the same output machinery, so once you learn it for one command you know it for all of them.

Formats

Set with --output. It defaults to a table in an interactive terminal and JSON when the output is piped, so scripts get machine-readable data automatically.

Value	Use it for
table	Human-readable terminal output (default in a TTY).
json	Agents, jq, and scripting (default when piped).
yaml	Config files and diffs.
csv	Spreadsheets and BI tools.

hscli conv list --output json
hscli report conversations --start 2026-05-01 --end 2026-05-31 --output csv > report.csv

Filter with --jq

Apply a jq expression to JSON output without leaving the command:

ids of conversations tagged resolved

hscli conv list --status active --jq '.[] | select(.tags[]? == "resolved") | .id'

Project with --fields

Trim the payload to just the columns you need — faster, and easier for an agent to read:

hscli conv list --output json --fields id,subject,status

Compose with the shell

close everything tagged resolved

hscli conv list --status active \
  --jq '.[] | select(.tags[]? == "resolved") | .id' \
  | xargs -I{} hscli conv status {} --set closed

Note

--jq runs inside hscli, so you don't need jq installed — but piping to real jq, xargs, awk, etc. works exactly as you'd expect.