Configuration

ThinkThen reads flags, environment variables, question files and one configuration file. It never writes the configuration file.

Which value wins

The typed value wins, then the environment, then the question file, then the configuration file, then the built-in default. A setting skips the tiers it has no home in.

The Settings page gives the order for each setting, and every default.

config/thinkthen/config.json, a configuration file

{
  "schema": "thinkthen.config/1",
  "backend": "liquid"
}

The file names liquid. THINKTHEN_BACKEND outranks the file and names ollama.

export XDG_CONFIG_HOME="$PWD/config"

thinkthen status --json |
jq .backend.name

export THINKTHEN_BACKEND=ollama
thinkthen status --json |
jq .backend.name

Output

"liquid"
"ollama"

exit 0

The environment

Variable	What it does
`THINKTHEN_API_KEY`	The key when no backend is named.
`THINKTHEN_BASE_URL`	The server address. --url outranks it.
`THINKTHEN_BACKEND`	A built-in backend, or an entry of the configuration file. --backend outranks it.
`LIQUIDAI_API_KEY`, then `LIQUID_API_KEY`	The key of the liquid backend.
`OLLAMA_API_KEY`	The key of the ollama backend.
`TYPESAFE_API_KEY`	The key of the typesafe backend.
`THINKTHEN_CACHE`	Another folder for the answer cache. It turns the cache on, and it never moves the usage totals.
`THINKTHEN_BATCH`	The most records one request carries.
`THINKTHEN_CA_BUNDLE`	An absolute PEM file of certificates that replaces the built-in roots.
`THINKTHEN_REQUESTS_PER_MINUTE`	The most requests one process starts each minute. It outranks the configuration file.
`THINKTHEN_MAX_ESTIMATED_INPUT_TOKENS_TOTAL`	The most estimated input tokens one process admits on the asking commands and on check.
`THINKTHEN_MAX_REQUEST_BYTES`	The most bytes one batched request holds.
`XDG_CONFIG_HOME`	The folder above the configuration file, on Linux. It counts only when absolute.
`XDG_CACHE_HOME`	The folder above the answer cache, on Linux. It counts only when absolute.
`XDG_STATE_HOME`	The folder above the usage totals, on Linux. It counts only when absolute.
`HOME`	The folder every location falls back to. It counts only when absolute.
`ALL_PROXY`, `HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`	Read in upper and lower case. A proxy carries https requests. Under http every proxy is ignored.

A blank variable counts as unset. SSL_CERT_FILE is not read.

Where the files live

File	System	Path
Configuration file	Linux	`$XDG_CONFIG_HOME/thinkthen/config.json`, else `$HOME/.config/thinkthen/config.json`
Configuration file	macOS	`$HOME/Library/Application Support/thinkthen/config.json`
Answer cache	Linux	`$XDG_CACHE_HOME/thinkthen`, else `$HOME/.cache/thinkthen`
Answer cache	macOS	`$HOME/Library/Caches/thinkthen`
Usage totals	Linux	`$XDG_STATE_HOME/thinkthen`, else `$HOME/.local/state/thinkthen`
Usage totals	macOS	`$HOME/Library/Application Support/thinkthen/usage`

ThinkThen has no home-folder variable of its own. HOME and the three XDG variables decide every location.

With no XDG variable, all three paths sit under HOME.

export HOME=/home/reader
unset XDG_CONFIG_HOME XDG_CACHE_HOME XDG_STATE_HOME

thinkthen status --json |
jq '{configuration: .configuration.path,
  cache: .cache.path,
  usage: .usage.path}'

Output

{
  "configuration": "/home/reader/.config/thinkthen/config.json",
  "cache": "/home/reader/.cache/thinkthen",
  "usage": "/home/reader/.local/state/thinkthen"
}

exit 0

On Linux, set XDG_CONFIG_HOME, XDG_CACHE_HOME or XDG_STATE_HOME to move the files. Each counts only when it is an absolute path. A relative path is ignored, and the location falls back to HOME. macOS ignores the XDG variables.

Absolute XDG variables move the configuration file, the cache, and the usage totals.

export HOME=/home/reader
export XDG_CONFIG_HOME=/home/reader/settings
export XDG_CACHE_HOME=/home/reader/scratch
export XDG_STATE_HOME=/home/reader/state

thinkthen status --json |
jq '{configuration: .configuration.path,
  cache: .cache.path,
  usage: .usage.path}'

Output

{
  "configuration": "/home/reader/settings/thinkthen/config.json",
  "cache": "/home/reader/scratch/thinkthen",
  "usage": "/home/reader/state/thinkthen"
}

exit 0

A relative XDG_CONFIG_HOME does not count. The path falls back to HOME.

export HOME=/home/reader
export XDG_CONFIG_HOME=settings

thinkthen status --json |
jq .configuration.path

Output

"/home/reader/.config/thinkthen/config.json"

exit 0

THINKTHEN_CACHE moves only the answer cache. The usage totals stay in the state folder.

The configuration file

The file is optional. It holds one JSON object with "schema": "thinkthen.config/1". ThinkThen never creates it and never edits it.

url and model name the default address and model.
backend names the default backend, and backends adds named servers or paces the built-ins. The System One page shows an entry.
cache turns the answer cache on or off. cache_bytes sets the size cache prune trims to.
usd_per_million_input and usd_per_million_output together price the reported tokens. The price is your own estimate, never a bill.

Any other field is refused. The file never holds a key. key_env in a backends entry names the variable that holds one.

Whoever can write the file decides where the key and the evidence go. On Linux and macOS ThinkThen warns when another user owns the file, or when every user may write it. A group-write bit alone draws no warning. A file that draws the warning and holds backends is refused with exit 5. Keep the file writable by its owner alone.

The usage totals

The usage folder holds one file for each UTC month. It counts requests sent, retries, input tokens, output tokens and answers from the answer cache. An answer from a replay or record folder never counts as a cache answer. It holds no request, no reply, no address, no model, no price and no key. Clearing the cache never resets it, and --no-cache never turns it off. It counts what this machine saw, and the backend's bill is the real cost.

See it all

thinkthen status prints the resolved configuration path, backend, address, model and key variable, and where each value came from. It also prints whether a key is set, the cache path and size, the usage path, and the usage this month and in all. It opens no connection. status --json prints the same facts as one thinkthen.status/2 object. The recording specification lists its fields.

Every setting and its default · Backends · Reference

On GitHub: github.com/botassembly/thinkthen