Client Tools Cheat Sheet

Use this page as a quick lookup for TeaQL client tooling. Exact flags may differ by version, so prefer the command help output for final verification before automating a new pipeline.

Status: Command map aligned with Generator Server 20260813.034821, cargo-teaql 2.0.11, and TeaQL Maven plugin 1.1.0 on 2026-08-13. Installed command help and project plugin declarations remain authoritative for client-specific flags.

Metadata	Value
Authority	Installed cargo teaql --help, project Maven plugin declaration, and mvn teaql:help.
Scope	Rust Cargo client and Java Maven plugin entry points.
Verified version	Generator Server 20260813.034821, crates.io cargo-teaql 2.0.11, and TeaQL Maven plugin 1.1.0.
Verification	Capture help output, run evaluation/generation on a minimal model, then build the generated workspace.
Update trigger	Command, goal, flag, report format, or output-layout change.

Cargo CLI

Currently documented Rust entry points:

cargo teaql --help
cargo teaql --version
cargo teaql show-config
cargo teaql services
cargo teaql evaluate --input model/main.xml
cargo teaql rust-lib-core --input model/main.xml --output generated/rust-lib-core
cargo teaql rust-app-console --input model/main.xml --output generated/rust-app-console

In cargo-teaql 2.0.11, local operations are listed as static subcommands. Remote operations and generation targets are dynamically routed. Use evaluate for model evaluation and select generation targets from services; do not use the obsolete eval shorthand or a generic generate target.

The generated rust-app-console manifest currently expects ../rust-lib-core/lib, so place those two output directories beside one another before building the application.

Cargo global options

Option	Meaning	Verified default or note in 2.0.8
--cwd <path>	Resolve relative working/output paths from this directory.	.
--input <path>	Model file or directory for evaluation or generation.	Current directory for a dynamic POST when omitted. Prefer an explicit path.
--endpoint-prefix <url>	Override the service prefix.	https://api.teaql.io/latest/
--service-url <url>	Legacy service override.	Deprecated; use --endpoint-prefix.
--api-key <value>	Override the built-in or configured API key.	Built-in free-tier key when no override is configured.
--output <path>	Override the build/output directory.	build
--timeout-seconds <n>	HTTP timeout.	1200 seconds in the 2.0.8 source.
-v, --verbose	Print resolved configuration source information.	Off.
--debug	Enable configuration diagnostics used by the current client.	Off.

Configuration precedence is CLI flag → environment variable → ~/.teaql/config.yml → built-in default. cargo teaql show-config serializes the configuration file itself. If that file contains api_key, its value may appear in the console; do not paste unredacted output into logs or tickets.

Static commands verified in top-level help are show-config, config, ping, install-links, and check. cargo teaql check [CARGO_ARGS]... invokes cargo check and maps compiler spans carrying generated source markers back to the originating KSML file.

Use the Cargo CLI when you need to:

• Generate a Rust workspace from a TeaQL model.
• Evaluate a modeling or coding task.
• Produce Markdown diagnostics when generation fails.
• Exercise provider-backed examples in a Rust project.

When a command fails, read the Markdown report before editing code.

Maven Plugin

TeaQL Maven plugin 1.1.0 uses one dynamic generation goal. Discover the server targets, evaluate the model, then pass the selected target as -Dservice:

mvn io.teaql:teaql-maven-plugin:1.1.0:help -Ddetail=true
mvn io.teaql:teaql-maven-plugin:1.1.0:list-services
mvn io.teaql:teaql-maven-plugin:1.1.0:eval -Dinput=model
mvn io.teaql:teaql-maven-plugin:1.1.0:generate \
  -Dservice=java-lib-core \
  -Dinput=model

It also exposes ping, show-config, and help. The dynamic generate goal means a new server-side target does not require a new hard-coded Maven goal. Run list-services instead of copying a target name from an older document.

Maven goals

Goal	Purpose	Key parameters
help	Display goal and parameter help.	-Ddetail=true, -Dgoal=<name>
list-services	Fetch the live dynamic target catalog.	teaql.endpointPrefix, teaql.apiKey, teaql.timeoutSeconds
eval	Evaluate a model and print Markdown diagnostics.	input, teaql.eval.failOnWarning (default false), teaql.eval.output
generate	Generate with a required dynamic service target.	service (required), input, teaql.output
ping	Run the built-in end-to-end service smoke test.	endpoint, API key, timeout overrides
show-config	Display the local TeaQL configuration path and contents.	No goal-specific parameters.

The current Cargo and Maven evaluation report bodies and their different exit framing are recorded in Reading Markdown Reports.

Common Maven properties are:

Property	Verified behavior in plugin 1.1.0
input	Model file or directory; falls back to the built-in demo model. Relative paths are resolved from the Maven project base directory, which may differ from the shell directory when -f selects another POM.
service	Required by generate; select from list-services.
teaql.output	Output directory; default generated-lib.
teaql.endpointPrefix	Service prefix override.
teaql.serviceUrl	Deprecated alias; use teaql.endpointPrefix.
teaql.apiKey	API key override.
teaql.timeoutSeconds	Request-timeout override. Help displays 0; when not overridden, effective configuration supplies the client default.

The plugin 1.1.0 help text says Maven eval is equivalent to cargo-teaql eval. That Cargo spelling is stale for cargo-teaql 2.0.11; use cargo teaql evaluate --input <path> on the Cargo side.

As with Cargo, treat show-config output as potentially sensitive when a local configuration file stores an API key.

The live service catalog checked on 2026-07-13 returned:

• agent, doc, evaluation, and mergemodel;
• java-lib-core, java-app-console, java-web-micronaut, java-web-quarkus, and java-web-spring-boot;
• rust-lib-core and rust-app-console.

The shorter mvn teaql:... form works only when the project declares the plugin or Maven settings register io.teaql as a plugin group. Use the fully qualified form for standalone inspection, and pin the selected plugin version in CI.

Use the Maven plugin when you need to:

• Generate Java packages from a TeaQL model.
• Integrate generated APIs into a Spring Boot project.
• Run evaluation or generation commands in a Java build.
• Capture Markdown diagnostics in CI output.

CI Guidance

For CI pipelines:

• Run generation before compile/test.
• Treat generation errors as build failures.
• Preserve Markdown error reports as CI artifacts.
• Keep model changes and generated API usage in the same review.
• Do not manually patch generated files to make CI pass.

Error Handling

Common failures:

Symptom	Action
Missing generated method	Read generated source and use the exact method name.
Missing query intent	Add comment and purpose before execution.
Missing audit metadata	Add audit_as / auditAs before save or update.
Invalid KSML	Fix the model, then regenerate.
Depth exceeded	Reduce nested references or use a scalar field.