Connection String Options

Tunes a provider’s requests with query options on its connection string. header and tool repeat; any other option takes its last value, and ZShot ignores an option it doesn’t know. Values are URL-decoded, so %20, + and a space all read as a space; write a literal + as %2B.

Chat options apply to every provider except typesafe and the decision models of openai, cloudflare and openrouter.

Header

header=Name:Value splits on the first colon and is sent on every call, the model listing included. A value without a colon is ignored. ZShot sends the value as written, so treat it as a secret.

Tool

tool= turns on a tool the provider runs for the model, such as a web search, whose result feeds the reply with no round trip through ZShot. It takes a name, web_search, web_fetch or code_execution; a versioned Anthropic type such as web_search_20250305; or a tool block as a base64 JSON data URI, such as tool=data:application/json;base64,eyJ0eXBlIjoid2ViX3NlYXJjaF8yMDI1MDMwNSIsIm5hbWUiOiJ3ZWJfc2VhcmNoIiwibWF4X3VzZXMiOjN9. Each provider’s page lists the forms it takes, and on another chat provider the call fails. typesafe and a decision model exit with code 3.

Tool calls add model round trips, so replies take longer. Tool traffic comes from the provider, outside ZShot’s robots.txt and --navigator-allow-url controls.

max_tokens

Most providers send no cap unless one is set, and the provider’s own applies. anthropic sends 4096. A formatter reply that reaches the cap fails with “LLM output truncated at the N-token completion limit”.

Vision and Frames

vision= sets when a navigator is shown a screenshot:

stall:3 is the default for a model that reads images, true means it and false means off; each provider’s page says which of its models do. Under stall and request_only the navigator can also ask with VISION, and once shown, every step on that page carries a screenshot. A formatter takes true or false.

frames= sets the most screenshots a step shows: the page now and, before it, frames from the last 30 seconds on that page, oldest first. It defaults to 3; 1 shows the page now only.

Timeout

timeout= sets the seconds ZShot waits for each reply; 0 waits without limit. A navigator’s model defaults to --navigator-step-timeout, a stdio agent to 60, and a formatter’s model to its request’s timeout. A request’s default timeout adds these up.

Request Body Fields

body.<path>=<value> sets a field of the request body the provider receives, named as the provider names it, for a setting ZShot has no option for, such as reasoning effort. A dotted path nests objects, and a value is read as JSON when it parses and as text otherwise. Each provider’s page gives an example.

ZShot passes the field as given, and the provider’s error is the call’s error. A field ZShot already sets, such as body.model, is refused. Thinking tokens are billed as output, and --llm-usage counts them there.

Navigator Options

These place a navigator in the session when --navigator-type repeats:

Example

zshot --navigate "Search the docs for WARC" \
  --navigator-type "typesafe://?name=scout&when=routine%20pages" \
  --navigator-type "anthropic://?model=claude-opus-5-5&name=writer&writer=true&timeout=30" \
  -f search.png https://zshot-cli.com/