# Configuration

Source: https://zshot-cli.com/reference/configuration/
Markdown: https://zshot-cli.com/reference/configuration/index.md
Section: [Reference](https://zshot-cli.com/reference/)

The ZShot configuration file ( `zshot.toml` ) is used to store licensing information. `zshot --license-key <KEY>` with no URL writes it for you, activating the key and saving it in one step. To write it yourself, store the key in the following format:

```
license = "MY-ZSHOT-LICENSE-KEY"
```

This file should be readable by the same user ZShot runs as. Additionally, if the file is writable, ZShot will write back license caching information to the file to prevent frequent re-licensing checks with the ZShot licensing server.

You can specify a specific configuration file via the [`--config`](/reference/flags/common/config) flag, which will override the default lookup.

## Lookup order

ZShot resolves the license key in priority order: the [`--license-key`](/reference/flags/common/license-key) argument, then the `ZSHOT_LICENSE` environment variable, then the `license` value from the first `zshot.toml` it finds. Without [`--config`](/reference/flags/common/config), it searches:

1. `zshot.toml` in the current working directory
2. `$XDG_CONFIG_HOME/zshot.toml`, defaulting to `~/.config/zshot.toml`
3. on macOS, `zshot.toml` next to the `.app` bundle
4. `zshot.toml` in the directory containing the `zshot` binary

When the resolved file is writable, ZShot caches the signed license back to it; if no config exists, it creates one at `$XDG_CONFIG_HOME/zshot.toml`, else `~/.config/zshot.toml`.

If you do not want to store your license key in a configuration file, you can also provide it via a command line argument [`--license-key`](/reference/flags/common/license-key) or via the environment variable `ZSHOT_LICENSE`.

## Expired or invalid licenses

An expired license is refreshed automatically with the licensing server. For 24 hours after expiry a failed refresh keeps licensed features working with a warning. After that, or when the server rejects the license, ZShot logs an error and runs with Free tier features; flags that require a license exit with code 3.

## 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**
  - [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/)
  - [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