Commands¶

Knosh provides seven built-in subcommands, plus any file-defined commands you add. Run any command with --help for a quick reference.

Action Commands¶

These commands cause Knosh to do some work on your behalf.

General Commands¶

These commands either configure Knosh or provide information to you about your Knosh environment.

File-Defined Commands¶

You can add your own subcommands by dropping Markdown files into the commands directory (~/.config/knosh/commands/ by default). Each file's body is the prompt; YAML frontmatter selects the agent and provides an optional description.

See File-Defined Commands for the full authoring guide.

Action Command Common Options¶

All of the action commands share a set of options for controlling agent execution and logging.

Execution¶

--agentId <id>

The agent to use, identified by its filename (without the .md extension) in the agents directory. Use list-agents to see available agents.

Resolution order (first match wins): 1. --agentId supplied on the command line 2. The agent: value in the command file's frontmatter (file-defined commands only) 3. defaultAgentId in knosh.json

If none of the above provides an agent, the command fails with an error. For prompt and kdocs, only sources 1 and 3 apply.

--max-iterations <n>

Maximum number of LLM API calls the agent may make in a single run. Default: 50. Increase for complex multi-step tasks.

--temperature <value>

Sampling temperature, usually in the range 0.0 to 1.0. Overrides the value in the agent's configuration file. When omitted, the agent's configured value is used — except for kdocs, which defaults to 0.2.

Retries¶

--max-retries <n>

Number of times to retry after a transient failure. Default: 0 (no retries).

--retry-delay-ms <ms>

Milliseconds to wait between retries. With --exponential-backoff, this is the initial delay. Default: 0.

--exponential-backoff

Double the retry delay on each attempt instead of using a fixed delay.

Logging¶

--log-dir <path>

Directory to write log files. Each run appends to a YYYY-MM-DD.log file in that directory. Logging to a file is disabled when this option is omitted.

--log-level <level>

Minimum severity level to emit: 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 the agent response in full. By default, text longer than 200 characters is replaced with a character count.

--log-full-tool-calls

Log tool call arguments and results in full. By default, large text fields are replaced with a character count.