Skip to main content

The Cargo Toolchain

TeaQL utilizes a custom Cargo CLI tool, cargo-teaql, to generate Rust structs and APIs from your KSML models.

Verified latest client: cargo-teaql 2.0.11 on 2026-08-13, confirmed from crates.io and installed locally.

The installed client is the authority for the commands and flags supported on your machine. Check it before copying a command from a project created with a different TeaQL release:

cargo teaql --help
cargo teaql --version

In cargo-teaql 2.0.11, the static command list contains local operations such as show-config, config, ping, install-links, and check. Other trailing arguments are accepted as dynamic service or target names. Consequently, services, evaluate, rust-lib-core, and rust-app-console are usable even though they do not appear as named static subcommands in top-level help. Successful parsing is not proof that the configured server exposes a route; verify the request and Markdown response.

Installation​

cargo install cargo-teaql --version 2.0.11 --locked

Usage​

Query the live target catalog, then evaluate a concrete model:

cargo teaql services
cargo teaql evaluate --input model/main.xml

Generate the domain library and console application into sibling directories:

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

The currently generated console manifest refers to ../rust-lib-core/lib. Keep the output directories as siblings unless the template itself changes. Build from generated/rust-app-console with cargo test, then set the generated database URL variable and run cargo run.

Use evaluate, not the older shorthand eval. Also pass an actual target such as rust-lib-core rather than the generic word generate; in 2.0.8, an unknown single word is forwarded as a generation scope.

Evaluation and generation failures are printed as Markdown reports. Read the report from the beginning before changing the model.

Inspect effective local configuration without making a generation request:

cargo teaql show-config

This command serializes ~/.teaql/config.yml. If that file contains an api_key, the value may be printed; redact the output before sharing it. For the complete verified option/default table, see Client Tools Cheat Sheet.

Version Alignment​

Generated crates must use runtime versions compatible with the installed generator. Do not copy runtime versions from an older documentation example.

Use the versions emitted by the generator or generated workspace template, then compare them with the Compatibility Matrix. Treat generated manifests as evidence of the expected dependency set, but make model or generator changes rather than hand-editing generated source.

Verify Success​

After generation:

  1. Inspect the generated workspace and its dependency versions.
  2. Run the build or test command included by that workspace.
  3. Confirm that the expected generated entities and Q APIs exist.
  4. Keep the model as the source of truth for later regeneration.

The 2026-07-13 Golden Path used Rust/Cargo nightly 1.99.0, generated edition 2021 crates with TeaQL 4.1.1 and SQLite provider 4.1.1, passed cargo test, and started the generated console application against SQLite. This proves the observed combination, not the minimum supported Rust version.

The generated sample_data.rs currently contains query calls with purpose but no comment. Do not patch generated output. Treat this as a generator template defect and keep handwritten queries in the required comment → purpose → execute_for_xxx order.