Reference on ajq — semantic jq

Command-line interface

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

ajq [query] [flags]
ajq [command]

ajq reads input from standard input, applies one jq/semantic query, and writes results to standard output. Errors are written to standard error and produce a non-zero exit code.

query is a single argument. ajq desugars =~/!~ to sem_match(...), parses with gojq, and executes through the selected backend only when semantic operators require one.

Global flags

Flag	Short	Description
`--backend <name>`		Select the semantic backend: `anthropic`, `local`, `mock`, `ollama`, `openai`, or `openrouter`.
`--base-url <url>`		Set the HTTP base URL for backends that use one (`local`, `ollama`, `openai`, `openrouter`). For `openai`/`openrouter`, custom URLs must use HTTPS unless the host is loopback (`127.0.0.1`, `localhost`, or `[::1]`).
`--backend-concurrency <N>`		Maximum in-flight semantic requests in one provider batch. Default `1`; maximum `2` for OpenAI-compatible/Anthropic and `4` for Ollama. Must be positive when set.
`--cloud`		Select the Anthropic cloud backend; equivalent to `--backend anthropic`.
`--compact-output`	`-c`	Emit compact JSON output.
`--exit-status`	`-e`	Set the exit status based on the last output value.
`--explain`		Print the deterministic/semantic execution plan and exit without executing the query.
`--max-calls <N>`		Maximum post-dedup backend judgements before aborting; `0` means unlimited. Paid backends default to `100`; local/Ollama/mock default to unlimited.
`--model <id-or-alias>`		Semantic model id or alias for the selected backend.
`--no-cache`		Disable persistent on-disk judgement cache reads and writes for this run.
`--null-input`	`-n`	Use a single `null` input value instead of reading stdin.
`--raw-input`	`-R`	Read each input line as a string.
`--raw-output`	`-r`	Emit strings without JSON quoting.
`--stats`		Print run statistics to stderr after a successful run.
`--stream`		Run supported semantic queries inline for low-latency frame output instead of window batching. Does not change backend, model, cache identity, or `--max-calls`; pure-jq and planner-required inline queries retain their existing behavior.
`--window-bytes <N>`		Maximum source bytes per supported three-phase semantic window; positive integer, default `262144`. Has no execution effect for pure-jq or inline queries, including `--stream`.
`--version`	`-v`	Print the version and exit.
`--help`	`-h`	Print usage and exit.

See Input and output modes for framing and formatting details, Backends for backend-specific defaults, and Configuration for env/config precedence.

Input and output modes

Mon, 01 Jan 0001 00:00:00 +0000

Input framing

ajq selects an input framing based on flags and the shape of stdin.

Mode	Flag	Behavior
Auto (default)	—	Auto-detects a single JSON value or a stream of top-level / NDJSON JSON values.
Null input	`-n`, `--null-input`	Ignores stdin; supplies one `null` input frame.
Raw input	`-R`, `--raw-input`	Reads each stdin line as a string, excluding the line terminator. `.` is the line.

In the default mode, a stream of multiple top-level JSON values (whitespace- or newline-separated, i.e. NDJSON/JSON Lines) is framed independently, with no whole-stream buffering. Pure-jq and planner-required interleaved semantic queries execute and emit one frame at a time. Supported three-phase semantic queries instead group complete frames into configured byte-budgeted windows, resolve each window once, then emit their frames in original order. The window retains only its frames plus bounded framing lookahead; a record larger than the budget forms one oversized window and is never split. This still allows inputs larger than available memory.

Semantic functions

Mon, 01 Jan 0001 00:00:00 +0000

Semantic operators are registered as jq functions, so gojq parses them inside ordinary jq constructs. ajq adds only the =~ and !~ surface sugar before parsing.

Function vocabulary

Function	Form	Kind	Returns	Execution status
`sem_match`	`sem_match(value; "spec")`	predicate	boolean	Shipped
`sem_classify`	`sem_classify(value; "a"; "b"; …)`	bounded value	one label from the given labels	Shipped
`sem_extract`	`sem_extract(value; "what")`	unbounded value	string	Limited: supported only in gated/interleaved fallback contexts
`sem_score`	`sem_score(value; "spec")`	unbounded value	number	Limited: supported in `sort_by(...)` three-phase placeholder mode and in gated/interleaved fallback contexts
`sem_norm`	`sem_norm(value; "canonicalization spec")`	unbounded value	string	Limited: supported in `group_by(...)` three-phase placeholder mode and in gated/interleaved fallback contexts
`sem_redact`	`sem_redact(value; "redaction spec")`	unbounded value	string	Limited: supported only in gated/interleaved fallback contexts

The spec is a literal string in the query. Stream data is structurally fenced by the selected backend’s output constraints.

--explain output

Mon, 01 Jan 0001 00:00:00 +0000

--explain prints a stable plan report and exits without executing the query. It does not contact a provider or local model.

Pure-jq report

ajq explain v1
query: ".users[] | select(.active) | .name"
execution: pure-jq deterministic
deterministic: yes
model_calls: 0
backend_calls: 0
byte_reproducible: yes
stdin: ignored

Field	Meaning
`query`	The query as parsed.
`execution`	`pure-jq deterministic` — no semantic call sites.
`deterministic`	`yes`.
`model_calls` / `backend_calls`	`0`.
`byte_reproducible`	`yes`.
`stdin`	`ignored` — pure-jq explain does not read input.

Semantic report

ajq explain v1
query: ".[] | select(sem_match(.msg; \"urgent\")) | .msg"
execution: semantic split plan
deterministic: no
model_calls: input-dependent
backend_calls: input-dependent
byte_reproducible: cache-dependent
stdin: harvested for estimates
planned_call_sites: 1
semantic_predicates: 1
semantic_values: 0
estimates:
 estimate_status: available
 static_call_sites: 1
 input_frames: 1
 harvested_judgements: 3
 post_dedup_judgements: 2
 mock_judge_batches: 1
 over_harvest_bound: post_dedup_judgements == mock distinct judgements; may be a safe superset of execute-needed judgements
subgraphs:
 deterministic: jq outside semantic call sites
 semantic: 1 planned call site(s)
semantic_plan:
 - call_id: 1
 op: "sem_match"
 kind: "predicate"
 value_expr: ".msg"
 specs: ["urgent"]
 source_range: 13:38
 gated: n/a
 execution: 3-phase
 subgraph: semantic

Header fields

Field	Meaning
`execution`	`semantic split plan` — the query has semantic call sites.
`deterministic`	`no`.
`model_calls` / `backend_calls`	`input-dependent`.
`byte_reproducible`	`cache-dependent` — deterministic phases are byte-reproducible; semantic answers depend on backend/cache state.
`stdin`	`harvested for estimates` when valid stdin is used for an estimate. With `--stream` on a supported plan, `not harvested`: inline execution has no cross-frame harvest estimate and explain leaves stdin untouched.
`planned_call_sites`	Total semantic call sites found in the static plan.
`semantic_predicates` / `semantic_values`	Counts of predicate-kind and value-kind ops.

`estimates` block

Present when valid stdin was supplied and the mock harvest path can estimate the query.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

ajq resolves semantic-backend settings from flags, environment variables, a TOML config file, and backend defaults.

Precedence

Rank	Source	Notes
1	Command-line flags	`--backend`, `--model`, `--base-url`, `--backend-concurrency`, `--max-calls`, `--window-bytes`, and `--no-cache`.
2	Environment variables	`AJQ_BACKEND`, `AJQ_MODEL`, `AJQ_BASE_URL`, `AJQ_BACKEND_CONCURRENCY`, `AJQ_MAX_CALLS`, `AJQ_WINDOW_BYTES`.
3	TOML config	Default path or `AJQ_CONFIG`.
4	Backend defaults	For example, Anthropic’s default model and paid-backend call cap.

Flags override environment variables; environment variables override config values; config values override backend defaults.

Backends

Mon, 01 Jan 0001 00:00:00 +0000

Semantic operators require a backend. Pure jq queries do not construct a backend, spawn a daemon, or make network calls unless a semantic operator is present and a backend is selected by flags, environment, or config.

Backend summary

Backend	Select with	Model default / requirement	Base URL	Credentials	Default `max_calls`
`mock`	`--backend mock`	Built-in `ajq-default-model` identity	none	none	`0` (unlimited)
`local`	`--backend local`	`qwen2.5-1.5b` unless overridden	Managed loopback `http://127.0.0.1:8081`; explicit `--base-url` for user-trusted servers	managed bearer key (internal)	`0` (unlimited)
`ollama`	`--backend ollama`	Required `--model` / config / env	`OLLAMA_HOST` or `http://127.0.0.1:11434`	none	`0` (unlimited)
`openai`	`--backend openai`	Required `--model` / config / env	`https://api.openai.com/v1`	`OPENAI_API_KEY`	`100`
`openrouter`	`--backend openrouter`	Required `--model` / config / env	`https://openrouter.ai/api/v1`	`OPENROUTER_API_KEY`	`100`
`anthropic`	`--backend anthropic` or `--cloud`	`claude-haiku-4-5`; aliases `haiku`, `sonnet`, `opus`	provider default; no user base URL	`ANTHROPIC_API_KEY`	`100`

max_calls counts post-dedup backend judgements. 0 means unlimited. For a machine-readable static projection of these registered backends, use ajq capabilities --json; it does not resolve configured credentials or runtime asset state. In that projection Ollama has no default_base_url, because its runtime URL may come from OLLAMA_HOST before the documented loopback fallback.

Reference on ajq — semantic jq

Command-line interface

Synopsis

Global flags

Input and output modes

Input framing

Semantic functions

Function vocabulary

--explain output

Pure-jq report

Semantic report

Header fields

estimates block

Configuration

Precedence

Backends

Backend summary

`estimates` block