From f50a5bd440619e99642e5f26a193ab812d7de9b3 Mon Sep 17 00:00:00 2001 From: Paul Buetow Date: Sun, 17 Aug 2025 08:59:53 +0300 Subject: docs(cli): document hexai CLI usage and behaviors - Inputs from stdin/arg, concatenation rules - Stderr styling, immediate provider/model, final stats line - Default concise style; 'explain' keyword for verbose answers - Examples and exit codes --- README.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index 837292c..f7f919b 100644 --- a/README.md +++ b/README.md @@ -57,6 +57,40 @@ Notes: Notes for `hexai` (CLI): - Prints LLM output to stdout. - Prints provider/model immediately to stderr, and a summary to stderr at the end (time, input bytes, output bytes, provider/model). +- Default response style: short answers. If the prompt asks for commands, outputs only the commands with no explanation. Include the word `explain` anywhere in the prompt to request a verbose explanation. + +### Hexai CLI behavior + +- Inputs: reads from stdin, from a single argument, or both. + - If both are provided, Hexai concatenates them with a blank line in between. +- Output routing: + - Stdout: the LLM response only (no decorations). + - Stderr: metadata and progress in grey on black (styled via ANSI): + - Provider/model printed immediately when the request starts. + - A final stats line on a new line: `done provider=… model=… time=… in_bytes=… out_bytes=…`. +- Default style: concise answers. + - If the prompt asks for commands, outputs only the commands with no commentary. + - Add the word `explain` in your prompt to request a verbose explanation. +- Exit codes: `0` success, `1` provider/config error, `2` no input. + +Examples: + +``` +# From stdin only +cat SOMEFILE.txt | hexai + +# From arg only +hexai 'summarize: list 3 bullets' + +# From both (stdin first, then arg) +cat SOMEFILE.txt | hexai 'explain the tradeoffs' + +# Commands-only output (no explanation) +hexai 'install ripgrep on macOS' + +# Verbose explanation +hexai 'install ripgrep on macOS and explain' +``` Notes: - Token estimation for truncation uses a simple 4 chars/token heuristic. -- cgit v1.2.3