Environment Variables
Status: Client variables are verified from cargo-teaql 2.0.8 source and
Maven plugin 1.1.1 help. Rust variables are verified from the generated
workspace integration, teaql-tool-core 1.0.0, and teaql-runtime 4.1.1
source. The two Rust parsers are separate configuration layers.
| Metadata | Value |
|---|---|
| Authority | Installed client source/help, generated Rust runtime source, and downloaded crate source. |
| Scope | Cargo/Maven client configuration plus Rust runtime logging and schema modes. |
| Verified version | cargo-teaql 2.0.8, Maven plugin 1.1.1, and teaql-rs 4.1.1 on 2026-07-13. |
| Verification | Start the target runtime with the variable set and inspect startup validation and behavior. |
| Update trigger | Environment parser, logging level, output target, schema mode, or default change. |
Client Variables
| Variable | Cargo configuration key | Purpose | Verified default/status |
|---|---|---|---|
TEAQL_ENDPOINT_PREFIX | endpoint_prefix | Service endpoint prefix. | https://api.teaql.io/latest/ |
TEAQL_SERVICE_URL | Legacy alias for endpoint prefix. | Backward compatibility. | Deprecated; use TEAQL_ENDPOINT_PREFIX. |
TEAQL_API_KEY | api_key | Override service credentials. | Built-in free-tier key when omitted. Never print or commit an override. |
TEAQL_BUILD_DIR | build_dir | Generation/output directory. | build in Cargo 2.0.8; Maven uses teaql.output and defaults to generated-lib. |
TEAQL_TIMEOUT_SECONDS | timeout_seconds | Request timeout in seconds. | 1200 in Cargo 2.0.8. |
Cargo client precedence is command-line flag → environment variable →
~/.teaql/config.yml → built-in default. The Maven plugin exposes equivalent
overrides through teaql.endpointPrefix, teaql.serviceUrl, teaql.apiKey,
teaql.output, and teaql.timeoutSeconds; its exact merge precedence is
reported by the effective configuration output.
TEAQL_LICENSE_FILE appears in the Cargo README but is not read by the
cargo-teaql 2.0.8 configuration source. Do not rely on it as an active client
setting without newer source evidence.
Generated Rust Workspace Variables
Current generated workspaces call
teaql_tool_core::audit_config_from_env(...). These variables are therefore
the primary configuration contract for newly generated applications.
| Variable | Purpose | Accepted values | Default |
|---|---|---|---|
TEAQL_AUDIT | Entity/audit detail. | _silent, _summary, _full | _full |
TEAQL_SQL | SQL detail. | _silent, _summary, _full | _silent |
TEAQL_SQL_TABLES | Restrict SQL output to generated table names. | Comma-separated table names | No filter; all known tables |
TEAQL_TOOL | Context-tool detail. | _silent, _summary, _full | _silent |
TEAQL_TOOL_FOCUS | Promote selected tool modules to full detail. | Comma-separated module names | No focused modules |
TEAQL_SINK | Select audit output destination. | _stdout, _file, _both | _both |
TEAQL_SCHEMA | Select the schema startup mode. | _verify, _dryrun, _execute | _verify |
TEAQL_TOOL_FOCUS accepts these module identifiers:
http,file,cmd,email,kv,crypto,jwt,time,id,text,decimal,money,json,regex,
codec,list,map,diff,url,validate,color,unit,daterange,desensitize,filter,
tree,system
The parser fails startup for an unknown focused module or an unknown table in
TEAQL_SQL_TABLES. It also rejects unknown environment-variable names that
begin with TEAQL_AUDIT, TEAQL_SQL, TEAQL_TOOL, TEAQL_SINK, or
TEAQL_SCHEMA; this catches misspellings instead of silently ignoring them.
The schema enum describes verify, dry-run, and execute modes. However, the
currently generated runtime calls ensure_schema() for all three branches.
Do not assume _dryrun is non-mutating until the generated runtime behavior is
fixed and verified against the selected database provider.
teaql-runtime Formatter Compatibility Layer
teaql-runtime 4.1.1 also contains an older log-formatter parser. These names
do not replace the generated-workspace variables above; use them only when the
application explicitly initializes that formatter path.
| Variable | Purpose | Accepted values/default |
|---|---|---|
TEAQL_LOG_FORMAT | Select formatter shape. | Human by default; json or debug selects the debug formatter. |
TEAQL_AUDIT_LOG | Formatter entity/audit level. | _silent, _summary, _full, _full_with_payload; default _full. |
TEAQL_SQL_LOG | Formatter SQL level. | Same levels; default _summary. |
TEAQL_TOOL_LOG | Formatter tool level. | Same levels; default _full. |
TEAQL_AUDIT_LOG_ENTITIES | Restrict entity output. | Comma-separated entity names. |
TEAQL_SQL_LOG_TABLES | Restrict SQL output. | Comma-separated table names. |
TEAQL_TOOL_LOG_FOCUS | Restrict tool output. | Comma-separated module names. |
TEAQL_LOG_ENDPOINT | Select formatter output. | Empty is ignored; stdout writes to standard output; another value is a file path. |
Invalid formatter level values fall back to that variable's default rather
than failing startup. If TEAQL_LOG_ENDPOINT is absent, the formatter uses
TEAQL_DOMAIN.log, or the executable name plus .log when the domain is not
set. TEAQL_TRACE_MODE=off is guarded by an explicit waiver acknowledgement;
without that acknowledgement, tracing remains enabled.
The Java teaql-runtime-log 1.525-RELEASE module implements the same formatter
names and additionally supports TEAQL_LOG_MAX_SIZE (default 50MB) and
TEAQL_LOG_MAX_FILES (default 7). On Java, a TEAQL_* system property wins
over the environment variable, and values are cached at class initialization.
See Configuration Properties for the Java
module boundary and exact size syntax.
Examples
TEAQL_SQL=_full TEAQL_SQL_TABLES=task cargo run
TEAQL_SCHEMA=_dryrun cargo run
TEAQL_AUDIT=_summary TEAQL_TOOL=_summary TEAQL_SINK=_stdout cargo test
_full_with_payload belongs only to the formatter compatibility layer. Avoid
it in production until payload sensitivity, masking, and retention have been
reviewed.
Runtime Precedence and Reload
Both Rust parsers read process environment during initialization. Dynamic reload is not established. Treat these as startup settings; programmatic configuration may still override how an application wires its subscribers and sinks.