# Connection String Options

Source: https://zshot-cli.com/reference/llm_connections/options/
Markdown: https://zshot-cli.com/reference/llm_connections/options/index.md
Section: [Reference](https://zshot-cli.com/reference/) › [LLM Connections](https://zshot-cli.com/reference/llm_connections/)

Tunes a provider's requests with query options on its [connection string](/reference/llm_connections). `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`](/reference/llm_connections/typesafe) and the decision models of [`openai`](/reference/llm_connections/openai#decisions), [`cloudflare`](/reference/llm_connections/cloudflare) and [`openrouter`](/reference/llm_connections/openrouter).

| Option | Applies to | Effect |
| --- | --- | --- |
| `model` | All | The model. Omitted, the provider's default model |
| [`header`](#header) | All | A request header, as `Name:Value` |
| [`tool`](#tool) | `anthropic`, `openai`, `openrouter` | A tool the provider runs for the model |
| [`max_tokens`](#max_tokens) | Chat | The most tokens a reply runs to |
| `temperature` | Chat | Sampling temperature. Sent only when set |
| `top_p` | Chat | Nucleus sampling cutoff. Sent only when set |
| [`vision`](#vision-and-frames) | Chat | When the model is shown a screenshot |
| [`frames`](#vision-and-frames) | Navigators that read images | The most screenshots a step shows |
| [`timeout`](#timeout) | All | Seconds to wait for each reply |
| [`body.<path>`](#request-body-fields) | Chat | A field of the provider's request body |
| `protocol` | `openai`, `cloudflare`, `openrouter` | The API the model speaks, on its provider's page |
| `gateway` | `cloudflare` | The AI Gateway calls go through |
| `insecure` | A string with a `host` | `true` connects over http, `false` over https |
| [`name`, `when`, `escalate`, `writer`](#navigator-options) | Navigators | The navigator's part in the session |

## 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`](/reference/flags/navigator/navigator-allow-url) controls.

## max_tokens

Most providers send no cap unless one is set, and the provider's own applies. [`anthropic`](/reference/llm_connections/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:

| Value | Shown |
| --- | --- |
| `always` | Every step |
| `stall`, `stall:N` | After N steps on one page, 3 for `stall` |
| `request_only` | When the navigator asks with `VISION` |
| `off` | Never |

`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`](/reference/flags/navigator/navigator-step-timeout), a [`stdio`](/reference/llm_connections/stdio) agent to 60, and a formatter's model to its request's timeout. A request's [default timeout](/reference/timeouts) 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`](/reference/flags/diagnostics/llm-usage) counts them there.

## Navigator Options

These place a [navigator](/reference/navigator/navigators) in the session when [`--navigator-type`](/reference/flags/navigator/navigator-type) repeats:

| Option | Effect |
| --- | --- |
| `name=` | The name it is escalated to by. Defaults to the protocol; two navigators with one name exit with code 3 |
| `when=` | When to choose it, shown to the navigator that escalates |
| `escalate=false` | Keeps it from being escalated to |
| `escalate=true` | On [`--llm-format-model`](/reference/flags/document/llm-format-model), adds the formatter to the navigators |
| `writer=true` | Writes the text the others choose to write. One per session; a provider that writes no text, such as `typesafe`, exits with code 3 |

## Example

**CLI**

```sh
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/
```

## Related

Flags:

- [`--llm-format-model`](https://zshot-cli.com/reference/flags/document/llm-format-model/)
- [`--navigator-type`](https://zshot-cli.com/reference/flags/navigator/navigator-type/)
- [`--navigator-step-timeout`](https://zshot-cli.com/reference/flags/navigator/navigator-step-timeout/)
- [`--llm-usage`](https://zshot-cli.com/reference/flags/diagnostics/llm-usage/)

Topics:

- [Navigators](https://zshot-cli.com/reference/navigator/navigators/)
- [Timeouts](https://zshot-cli.com/reference/timeouts/)

## Navigation

- [Examples](https://zshot-cli.com/examples/)
- [Download](https://zshot-cli.com/download/)
- [Purchase](https://zshot-cli.com/purchase/)
- [Reference](https://zshot-cli.com/reference/)
  - [Formats](https://zshot-cli.com/reference/formats/)
  - [Flags](https://zshot-cli.com/reference/flags/)
  - [Agents](https://zshot-cli.com/reference/agents/)
  - [Configuration](https://zshot-cli.com/reference/configuration/)
  - [Crawling](https://zshot-cli.com/reference/crawling/)
  - [Docker](https://zshot-cli.com/reference/docker/)
  - [Exit Codes](https://zshot-cli.com/reference/exit_codes/)
  - [Linux](https://zshot-cli.com/reference/linux/)
  - [LLM Connections](https://zshot-cli.com/reference/llm_connections/)
    - **Connection String Options**
    - [Roles](https://zshot-cli.com/reference/llm_connections/roles/)
    - [Anthropic](https://zshot-cli.com/reference/llm_connections/anthropic/)
    - [OpenAI](https://zshot-cli.com/reference/llm_connections/openai/)
    - [Google](https://zshot-cli.com/reference/llm_connections/google/)
    - [Ollama](https://zshot-cli.com/reference/llm_connections/ollama/)
    - [Mistral](https://zshot-cli.com/reference/llm_connections/mistral/)
    - [DeepSeek](https://zshot-cli.com/reference/llm_connections/deepseek/)
    - [Mercury](https://zshot-cli.com/reference/llm_connections/mercury/)
    - [Groq](https://zshot-cli.com/reference/llm_connections/groq/)
    - [HuggingFace](https://zshot-cli.com/reference/llm_connections/huggingface/)
    - [TypeSafe](https://zshot-cli.com/reference/llm_connections/typesafe/)
    - [Cloudflare](https://zshot-cli.com/reference/llm_connections/cloudflare/)
    - [OpenRouter](https://zshot-cli.com/reference/llm_connections/openrouter/)
    - [stdio](https://zshot-cli.com/reference/llm_connections/stdio/)
  - [LLM Formatting](https://zshot-cli.com/reference/llm_formatting/)
  - [Local Inputs](https://zshot-cli.com/reference/inputs/)
  - [Navigator](https://zshot-cli.com/reference/navigator/)
  - [Security](https://zshot-cli.com/reference/security/)
  - [Server](https://zshot-cli.com/reference/server/)
  - [Shell completions](https://zshot-cli.com/reference/shell_completions/)
  - [Storage](https://zshot-cli.com/reference/storage/)
  - [Timeouts](https://zshot-cli.com/reference/timeouts/)
  - [Web Bot Auth](https://zshot-cli.com/reference/web_bot_auth/)
- [Support](https://zshot-cli.com/support/)
- [Changelog](https://zshot-cli.com/changelog/)

Site index: https://zshot-cli.com/llms.txt