knosh prompt¶

Run a prompt through a named agent and print the response to stdout.

Synopsis¶

knosh prompt [--agentId <id>] [options] [PROMPT...]
knosh prompt [--agentId <id>] --promptFile <path> [options]
echo "..." | knosh prompt [--agentId <id>] [options]

Because prompt is the default command, the prompt keyword can be omitted:

knosh [--agentId <id>] [options] [PROMPT...]
echo "..." | knosh [--agentId <id>] [options]

Description¶

prompt sends a prompt to the specified agent and streams the response to standard output. The agent is identified by its filename (without the .md extension) in the agents directory; use list-agents to see what is available.

prompt is the default command: when the first argument is not a recognized subcommand name or a root-level flag (--help, --version), Knosh automatically routes the invocation to prompt. Running knosh with no arguments still prints root help.

Supplying the prompt¶

The prompt text can come from three sources — use whichever fits your workflow:

Trailing argument

Pass the prompt directly on the command line. Multiple words are joined with spaces.

knosh prompt --agentId my-agent "Summarize the changes in the last commit."

File (--promptFile)

Read the prompt from a file. Pass - to read from stdin explicitly.

knosh prompt --agentId my-agent --promptFile prompt.txt
cat prompt.txt | knosh prompt --agentId my-agent --promptFile -

Piped stdin

Pipe text directly into knosh prompt without any flag.

git diff HEAD~1 | knosh prompt --agentId my-agent

When stdin is a terminal (not a pipe), Knosh prints a hint explaining how to signal end-of-input.

Options¶

--agentId <id>

The agent to use. Must match an agent filename (without .md) in the agents directory. Optional when defaultAgentId is set in knosh.json; required otherwise.

--promptFile <path>

Path to a file to use as the prompt, or - to read from stdin.

Execution¶

--max-iterations <n>

Maximum number of LLM API calls allowed per run. Default: 50.

--temperature <value>

Sampling temperature in [0.0, 1.0]. Overrides the agent's configured value.

Retries¶

--max-retries <n>

Number of times to retry after a transient failure. Default: 0.

--retry-delay-ms <ms>

Milliseconds to wait before each retry. Default: 0.

--exponential-backoff

Double the retry delay on each attempt.

Logging¶

--log-dir <path>

Directory to write log files. Each run appends to a YYYY-MM-DD.log file.

--log-level <level>

Minimum log severity: TRACE, DEBUG, INFO, WARN, ERROR. Default: WARN.

--log-format <format>

Log line format: compact (default), default, json, pretty.

--log-full-prompts

Log prompt input and response in full instead of replacing long text with a character count.

--log-full-tool-calls

Log tool call arguments and results in full.

Examples¶

Ask a quick question:

knosh prompt --agentId my-agent "What model is this, and what can you do for me?"

Summarize a file:

knosh prompt --agentId my-agent --promptFile analysis.txt

Pipe output from another command:

git log --oneline -20 | knosh prompt --agentId my-agent "Write a release summary for these commits."

Enable debug logging to a directory:

knosh prompt --agentId my-agent --log-dir logs --log-level DEBUG "Explain this error."

Live status and benchmarking¶

When stderr is an interactive terminal, prompt shows a live status line while the agent runs — a Braille spinner that cycles through starting…, calling model…, and running tool: <name> as the run progresses. The status line is written to stderr and erased when the response is ready, so it never interferes with the response on stdout (which remains safe to pipe or redirect).

Add --benchmark to print a metrics summary to stderr after the run completes:

knosh prompt --agentId my-agent --benchmark "Summarize the latest changes."

42,318 in / 1,205 out tokens · 6 LLM calls · 3 tool calls · 12.4 seconds

The summary is printed only when --benchmark is set and stderr is an interactive terminal. Token counts are omitted when the model provider does not report usage metadata.