Reference

Everything the thinkthen command takes and prints. Read this page before you write a pipeline, and hand it to an agent. How answers work says when an answer is yes, no, not sure, or a number.

The ten functions

Arguments and thresholds

A threshold is a cut on the quantity each function names. You set it; the tool never reports one. A cut is one number. Only decide takes a band, written LOW:HIGH. A recognized name’s printed strength is a computed product, not a probability.

With p as the probability of yes:

The high side is inclusive. A probability exactly at LOW is not sure. A cut of 0 is refused. A band low of 0 is accepted. --threshold 0.5 and no threshold name the same rule. A percent such as 90, a reversed band, an empty side, and a number that is not finite are all usage errors before any request.

The cut applies to the probability of yes on decide and each record under filter, the winning option’s probability on choose, each label’s independent yes probability under tag, each name’s printed strength under recognize, and each relation edge’s yes probability under recognize or relate. The threshold contract defines every boundary.

Global flags

Every function accepts all of these. The settings page lists every setting on every surface, with its default.

--jobs N sets the throttle. The throttle is the most requests in flight at once. The flag is not global. It runs from 1 to 32, defaults to 4, and it belongs to record mode. annotate also accepts it on one document, and relate on its one set of names. Every other function refuses it outside record mode.

TypeSafe documents a limit of 1,200 requests a minute. The records specification holds the measured rates. --jobs caps the requests in flight. It sets no limit on requests a minute. The rate depends on how fast replies come back. On short records, the default of 4 can pass that limit. In a review, the default sent 1,519 requests a minute to TypeSafe. Against a local test server with 100 ms replies, --jobs 3 sent 1,285 a minute. Set requests_per_minute on the backend, or THINKTHEN_REQUESTS_PER_MINUTE, to stay under the limit.

Function-only flags: --threshold, --true TEXT and --false TEXT (decide, filter, rank), --quiet (decide and choose, one document only), --raw (choose only, refused under CSV and TSV), --option LABEL=DESCRIPTION, --label LABEL=DESCRIPTION, --options POINTER (choose, and it needs --jsonl), --top N (rank, a whole number of 1 or more), --none (find).

Framing a stream

The four framing flags are mutually exclusive. The tool never guesses a framing from a filename.

--field POINTER

A JSON Pointer, RFC 6901. It names the part of each record the model sees. Only the pointed value leaves the machine.

• Under --jsonl, --csv, or --tsv it reads the pointer in each record.
• With no framing flag it reads the whole input as one JSON value and takes the pointer inside it. There is no separate JSON framing flag.
• On filter and rank, a pointer with no framing flag reads JSON Lines instead. A question file's on does the same.
• Under --lines it is a usage error. A text line has no members.
• It may repeat. Several pointers build an evidence object, each member keyed by the last part of its pointer. Two members that would share one key are a usage error.
• A pointer that finds nothing is an input error for that record, exit 2, before any request for it.
• $.body, #/id, a wildcard, and a negative index are refused, and the message names RFC 6901.
• A pointed value that is not a string is serialized as compact JSON and sent as text. With no --field, a JSONL, CSV, or TSV record is serialized whole.

CSV and TSV

Both require a header. Every cell becomes a JSON string, including an empty cell and text that looks like a number, a boolean, a null, an array, or an object. Header order becomes key order. A header name may hold whitespace, but it may not be blank, hold a control character, or exactly duplicate another. One UTF-8 byte order mark is ignored at the start of the first header name and nowhere else. Every data row must carry the header's field count. A header with no data rows is a successful empty dataset and sends no request. Empty input is exit 2. Every output from CSV or TSV input is JSONL.

A record is capped at 16 MiB of encoded bytes. find reads at most 16 MiB of input in all. Invalid UTF-8 in a record is exit 5. An empty document is a usage error. An empty line or JSONL stream exits 0 with no output and no request.

Limits

One whole request carries at most about 64,000 tokens, the questions included. The evidence in one request must fit in about 32,000 tokens. TypeSafe published both numbers on 2026-09-19 for its hosted service. The records specification lists them. They belong to the backend and not to the tool.

Evidence past the token limit is refused and the command exits 4. Under annotate the questions and the evidence count together. A long question set can pass the limit on evidence that fits on its own. Fewer questions per file is the answer.

What one row looks like

In record mode, a decide, choose, tag, or score row is {"input":RECORD,"value":ANSWER}, in that key order. filter, rank, and find keep returning records. Every result is compact and sits on one line.

annotate in record mode adds one top-level field per question to an object record. A line, a JSON scalar, or a JSON array keeps its parsed record under input and its named answers under value. CSV and TSV rows are objects, and they stay flat.

Exit codes

Code 8 is reserved and unused. In record mode the exit code reports the run and never one record's answer. A completed run exits 0 unless annotate exits 6 or 7, or relate exits 6. A valid answer on standard output can sit beside exit 1, 3, 6, or 7.

The environment

The Configuration page lists every variable ThinkThen reads.

With no backend named, the key comes from THINKTHEN_API_KEY. --backend, THINKTHEN_BACKEND or the configuration file's backend names a backend. A named backend reads only its own key variables, and the first one that is not blank wins:

• liquid reads LIQUIDAI_API_KEY, then LIQUID_API_KEY.
• ollama reads OLLAMA_API_KEY.
• typesafe reads TYPESAFE_API_KEY.

The command line comes first, then the environment, then the configuration file. The first of these that names a backend or an address decides. So THINKTHEN_BASE_URL in the shell outranks the configuration file's backend, and the key then comes from THINKTHEN_API_KEY. With both --backend and --url, the backend's key variables apply at that address.

With the key unset or blank, a request to localhost, 127.0.0.1 or [::1] goes out with no key and no Authorization header. At any other address, the command exits 4. The Backends page gives the rest of the key rules.

The cache

Recording and the answer cache covers the answer cache, the cache key, recording and replay, and pruning. The usage totals and thinkthen status are on the Configuration page. status --json prints one thinkthen.status/2 object. The recording specification lists its fields.

thinkthen status --json |
jq '{schema, backend}'

{
  "schema": "thinkthen.status/2",
  "backend": {
    "name": null,
    "url": "https://api.typesafe.ai/v1/systemone",
    "url_source": "built_in",
    "model": "jev-1.13.0",
    "model_source": "built_in",
    "key_variable": "THINKTHEN_API_KEY",
    "api_key_set": false
  }
}

The configuration file

The Configuration page gives its path, its fields, and the rules ThinkThen reads it by.

A list given on the command line replaces the file's whole list. The two never merge. The settings page gives the order in which values win.

Question files

A question file holds one saved question. Write @FILE in place of the question words. A question set for annotate holds many questions. The question file page carries the keys and the exit codes.

Take the tutorial · See every function · Test it before you trust it