CLI reference

Every tesseraql subcommand, generated from the command model the binary itself parses with, so it cannot describe a flag that does not exist. tesseraql <command> --help prints the same content at the terminal.

Most commands take --app <dir>, the application home they act on. Every subcommand calls the same engine as the matching Maven goal, so a CLI loop and a CI pipeline do the same work.

dev · host · deploy · routes · new · scaffold · lint · token · test · coverage · generate · schema · symbols · release-diff · governance · admission · migrate · job · identity-schema · package · verify · modules · embedded-db · duckdb · mcp

dev

Run the development stack over the gateway until interrupted.

Argument	Required?	Description
--stack <dir>	—	Directory holding the applications to run: an install root (catalog.json) or a folder of application homes. Discovered one level up from the working directory when omitted.
--app-name <name>	—	Run only this application from the stack, at the same address it has as a stack member.
--env <profile>	—	Environment profile: merges config/env/.yml between the base config and the Studio overlay (also TESSERAQL_ENV).
--repo <dir>	—	Local artifact repository to resolve modules from — a bag produced by ‘tesseraql modules fetch’ on a connected machine (also -Dmaven.repo.local). Combine with –offline to resolve nothing over the network.
--log-format <text|json>	—	Log line format (default text; json for structured logs).
--log-level <level>	—	Log threshold: trace|debug|info|warn|error (default info).
--port <port>	—	The port the gateway fronts every app on (default 8080).
--watch	—	Watch every application’s web/, workflow/, and shared-definition trees (decisions/, rules/, scope/, domains/) and hot-reload on save - the editor-first alternative to Studio’s Apply: a route edit bounces that route, a workflow edit rebuilds its transition endpoints, a shared-definition edit rebuilds every route. Jobs, consumers, and config/ changes still need a restart.
--modules <dir>	—	Directory of optional plugin module jars (e.g. the pdf/excel file-format codecs), composed with the application’s declared tesseraql.modules.
--embedded-db <data-dir>	—	Run with an embedded PostgreSQL (no external database): one server, one database, shared by the stack - applications isolate with currentSchema in their own URLs, and the framework state rides the shared database so one sign-in carries. Pass a directory to persist data across restarts; omit it for an ephemeral run.
--embedded-db-port <port>	—	Bind the embedded PostgreSQL to a fixed TCP port (default: a random free port chosen at startup). Use it to connect a local client (e.g. psql) at a stable address. Listens on localhost only.
--embedded-db-version <version>	—	Pin the embedded PostgreSQL binary version (e.g. 17.10.0). Default: the CLI’s built-in version, or, for a persistent data directory, the version it was created with. A persistent directory records the version that ran it and re-resolves that version on later starts, so bumping the default never breaks an existing directory.

host

Serve every installed app from one port, each in its own runtime.

Argument	Required?	Description
--stack <dir>	yes	Directory holding the applications to serve: an install root (catalog.json) or a folder of application homes.
--app-name <name>	—	Serve only this application from the stack, at the same address it has as a stack member.
--env <profile>	—	Environment profile: merges config/env/.yml between the base config and the Studio overlay (also TESSERAQL_ENV).
--repo <dir>	—	Local artifact repository to resolve modules from — a bag produced by ‘tesseraql modules fetch’ on a connected machine (also -Dmaven.repo.local). Combine with –offline to resolve nothing over the network.
--port <port>	—	The port the gateway fronts every app on (default 8080).
--http2	—	Serve and forward cleartext HTTP/2 (h2c). Off by default. One switch moves both hops: a client’s connection to the gateway and the gateway’s connection to each app. An app that does not offer h2c answers the upgrade over HTTP/1.1 and is reached exactly as before.
--trusted-proxies <cidr,...>	—	Addresses whose forwarded headers come from your edge rather than from a caller, e.g. 10.0.0.0/8,192.168.1.5. When set, an application’s mTLS forwardedHeader is stripped from requests arriving from anywhere else. Empty by default, which strips nothing: the edge overwriting the header on every inbound request is the contract either way.

deploy

Deploy one application into a stack’s install root; a running host replaces its runtime without a restart.

Argument	Required?	Description
<package.tqlapp>	—	The application package to deploy. Its declared name says which member it replaces; its version must be newer than the installed one.
--stack <dir>	—	The install root to deploy into: catalog.json plus one unpacked tree per application version. Explicit, never discovered - production does not guess.
--url <origin>	—	Deploy remotely instead: the stack’s origin, whose authenticated deploy endpoint checks the caller’s tql.app.deploy. grant against the package’s declared name and writes the same intent. The bearer comes from tesseraql token via TESSERAQL_TOKEN or –token-file.
--token-file <file>	—	File holding the bearer token for –url (else TESSERAQL_TOKEN) - never a command-line argument, so it cannot leak into shell history or process listings.
--canary	—	Stage the new version beside the serving one instead of replacing it, at –weight percent of HTTP traffic (default 10). Promote or roll back when the ramp has said its piece.
--weight <percent>	—	The staged canary’s share of HTTP traffic, 0-100. Only with –canary; background work participates fully from candidate start regardless.
--sha256 <hex>	—	Verify the package’s SHA-256 before anything is written; a tampered or corrupted package is rejected.
--wait	—	Wait for the running host to report the outcome in the member’s .upgrade status file before exiting.
--wait-timeout <seconds>	—	How long –wait waits before giving up loudly (default 300).

deploy weight

Adjust the staged canary’s share of HTTP traffic.

Argument	Required?	Description
<name>	yes	The application whose canary is staged.
<percent>	yes	The new share, 0-100.
--stack <dir>	yes	The install root.

deploy promote

Activate the staged canary; the previous version stays on disk for rollback.

Argument	Required?	Description
<name>	yes	The application whose canary is staged.
--stack <dir>	yes	The install root.
--wait	—	Wait for the running host to report the outcome in the member’s .upgrade status file before exiting.
--wait-timeout <seconds>	—	How long –wait waits before giving up loudly (default 300).

deploy rollback

Discard a staged canary, or restore the previous version as active.

Argument	Required?	Description
<name>	yes	The application to roll back.
--stack <dir>	yes	The install root.

deploy status

Show each member’s active version, staged canary, and the host’s last reported outcome.

Argument	Required?	Description
<name>	—	One application; every catalogued one when omitted.
--stack <dir>	yes	The install root.

routes

List the routes discovered in the app.

Argument	Required?	Description
--app <app>	yes	Path to the external app home.
--env <profile>	—	Environment profile: merges config/env/.yml between the base config and the Studio overlay (also TESSERAQL_ENV).
--repo <dir>	—	Local artifact repository to resolve modules from — a bag produced by ‘tesseraql modules fetch’ on a connected machine (also -Dmaven.repo.local). Combine with –offline to resolve nothing over the network.
--modules <dir>	—	Directory of optional plugin module jars (e.g. the pdf/excel file-format codecs), composed with the application’s declared tesseraql.modules.

new

Generate a runnable app skeleton.

Argument	Required?	Description
<appName>	yes	The app name ([a-z][a-z0-9-]*); also the directory.
--stack <stack>	—	The stack directory to create the app in (default: .) — the directory that holds your applications.

scaffold

Generate code into an existing app.

scaffold crud

Scaffold list/detail/edit routes, 2-way SQL, pages, and tests for a table.

Argument	Required?	Description
--app <app>	yes	Path to the app home.
--table <table>	yes	The table to scaffold.
--jdbc-url <jdbcUrl>	—	JDBC URL (default: the app’s –datasource config).
--datasource <name>	—	Named datasource whose configuration backs the connection, and the key for datasource-scoped work (default: main).
--username <username>	—	Database user for –jdbc-url.
--password <password>	—	Database password for –jdbc-url.
--env <profile>	—	Environment profile: merges config/env/.yml between the base config and the Studio overlay (also TESSERAQL_ENV).
--repo <dir>	—	Local artifact repository to resolve modules from — a bag produced by ‘tesseraql modules fetch’ on a connected machine (also -Dmaven.repo.local). Combine with –offline to resolve nothing over the network.
--force	—	Overwrite edited and user-owned files.

scaffold decision

Scaffold a table-backed decision: the decisions/ declaration and the typed backing-table migration.

Argument	Required?	Description
--app <app>	yes	Path to the app home.
--name <name>	yes	The decision name (lowerCamel), e.g. shippingFee.
--inputs <inputs>	yes	Inputs as name:kind (eq, between, in, bool, orgSubtree).
--outputs <outputs>	yes	Output names.
--unique	—	hitPolicy: unique (default: first, with a priority column).
--effective	—	Dated rows: valid_from/valid_to matched against effectiveAt:.
--force	—	Overwrite edited and user-owned files.

scaffold eject-view

Eject a route’s declarative view into a hand-owned template and flip the route to template:.

Argument	Required?	Description
--app <app>	yes	Path to the app home.
--route <route>	yes	App-relative route file (e.g. web/items/get.yml).
--force	—	Overwrite an edited or user-owned template.
--env <profile>	—	Environment profile: merges config/env/.yml between the base config and the Studio overlay (also TESSERAQL_ENV).
--repo <dir>	—	Local artifact repository to resolve modules from — a bag produced by ‘tesseraql modules fetch’ on a connected machine (also -Dmaven.repo.local). Combine with –offline to resolve nothing over the network.

lint

Lint the app home, failing on errors.

Argument	Required?	Description
--app <app>	yes	Path to the external app home.
--fail-on-warning	—	Treat warnings as failures too.
--format <format>	—	Output format: text, json (default: text). Default: text.
--modules <dir>	—	Directory of optional plugin module jars (e.g. the pdf/excel file-format codecs), composed with the application’s declared tesseraql.modules.
--env <profile>	—	Environment profile: merges config/env/.yml between the base config and the Studio overlay (also TESSERAQL_ENV).
--repo <dir>	—	Local artifact repository to resolve modules from — a bag produced by ‘tesseraql modules fetch’ on a connected machine (also -Dmaven.repo.local). Combine with –offline to resolve nothing over the network.

token

Obtain a bearer token: mint one from an app’s HS256 secret (–app), or sign in to a running application and exchange (–url).

Argument	Required?	Description
--app <app>	—	Path to the app home; mints locally from its config.
--url <base-url>	—	Base URL of a running application; signs in and exchanges the session for a token. Include the base path if the application has one.
--env <profile>	—	Environment profile: merges config/env/.yml between the base config and the Studio overlay (also TESSERAQL_ENV).
--repo <dir>	—	Local artifact repository to resolve modules from — a bag produced by ‘tesseraql modules fetch’ on a connected machine (also -Dmaven.repo.local). Combine with –offline to resolve nothing over the network.
--sub <subject>	—	Subject claim (default dev).
--login <login>	—	With –app, the loginId claim (default: the subject). With –url, the login id to sign in as; required there.
--password <password>	—	With –url: the password. Omit to be prompted, or set TESSERAQL_PASSWORD — passing it here puts a credential in the process list and the shell history.
--tenant <id>	—	With –url: the tenant to sign in to, for a multi-tenant realm.
--otp <code>	—	With –url: the TOTP code, or a recovery code, when the account has an authenticator enrolled.
--role <role>	—	Role (repeatable); lands under the configured rolesClaim.
--permission <permission>	—	Permission (repeatable); lands under the configured permissionsClaim.
--claim <name=value>	—	Custom claim (repeatable). A value that parses as JSON (‘[“a”,“b”]’, ‘7’, ‘true’) is embedded structurally; anything else is a string.
--ttl <duration>	—	Lifetime, e.g. 30m, 12h, 7d (default 24h).
--app-name <name>	—	Mint for one stack member: the token’s audience is that member’s address and its claims are the member’s active view — one held role auto-activates, several stay inactive unless –as selects one (docs/token-issuance.md decision 9). Only with –url, against a stack surface.
--as <role>	—	Act as one held application role: with –url the server mints the active view (that role, the stack-wide roles, their permissions) plus an acting_role claim, refusing a role the account does not hold; with –app it stamps the acting_role claim on the local mint.

test

Run the app’s test suites; –report writes the docs overlay.

Argument	Required?	Description
--app <app>	yes	Path to the external app home.
--jdbc-url <jdbcUrl>	—	JDBC URL (default: the app’s –datasource config).
--datasource <name>	—	Named datasource whose configuration backs the connection, and the key for datasource-scoped work (default: main).
--username <username>	—	Database user for –jdbc-url.
--password <password>	—	Database password for –jdbc-url.
--realm <realm>	—	Managed realm id (default: local).
--report-dir <reportDir>	—	Report output dir (default: /work/reports).
--report	—	Also write the documentation-portal report overlay.
--run-id <runId>	—	Stable run id for the trend (default: timestamp).
--history-limit <historyLimit>	—	Runs retained in history.json; 0 keeps all (default: 20).
--sql-line-threshold <sqlLineThreshold>	—	Min SQL line coverage % recorded.
--sql-branch-threshold <sqlBranchThreshold>	—	Min SQL branch coverage % recorded.
--fail-on-regression	—	Exit non-zero if SQL coverage drops vs the previous run (needs –report).
--regression-tolerance <regressionTolerance>	—	Allowed coverage drop (percentage points) before it is a regression.
--format <format>	—	Output format: text, json (default: text). Default: text.
--case <cases>	—	Run only the named case(s), exact match; repeatable (default: all).
--modules <dir>	—	Directory of optional plugin module jars (e.g. the pdf/excel file-format codecs), composed with the application’s declared tesseraql.modules.
--env <profile>	—	Environment profile: merges config/env/.yml between the base config and the Studio overlay (also TESSERAQL_ENV).
--repo <dir>	—	Local artifact repository to resolve modules from — a bag produced by ‘tesseraql modules fetch’ on a connected machine (also -Dmaven.repo.local). Combine with –offline to resolve nothing over the network.

coverage

Run suites and enforce the SQL coverage gate.

Argument	Required?	Description
--app <app>	yes	Path to the external app home.
--jdbc-url <jdbcUrl>	—	JDBC URL (default: the app’s –datasource config).
--datasource <name>	—	Named datasource whose configuration backs the connection, and the key for datasource-scoped work (default: main).
--username <username>	—	Database user for –jdbc-url.
--password <password>	—	Database password for –jdbc-url.
--realm <realm>	—	Managed realm id (default: local).
--report-dir <reportDir>	—	Report output dir (default: /work/reports).
--sql-line-threshold <sqlLineThreshold>	—	Min SQL line coverage % (else config).
--sql-branch-threshold <sqlBranchThreshold>	—	Min SQL branch coverage % (else config).
--modules <dir>	—	Directory of optional plugin module jars (e.g. the pdf/excel file-format codecs), composed with the application’s declared tesseraql.modules.
--env <profile>	—	Environment profile: merges config/env/.yml between the base config and the Studio overlay (also TESSERAQL_ENV).
--repo <dir>	—	Local artifact repository to resolve modules from — a bag produced by ‘tesseraql modules fetch’ on a connected machine (also -Dmaven.repo.local). Combine with –offline to resolve nothing over the network.

generate

Generate OpenAPI, the htmx contract, and the docs spec.

Argument	Required?	Description
--app <app>	yes	Path to the external app home.
--env <profile>	—	Environment profile: merges config/env/.yml between the base config and the Studio overlay (also TESSERAQL_ENV).
--repo <dir>	—	Local artifact repository to resolve modules from — a bag produced by ‘tesseraql modules fetch’ on a connected machine (also -Dmaven.repo.local). Combine with –offline to resolve nothing over the network.
--out <out>	—	Output directory (default: /work/generated).

schema

Introspect the database and write the schema overlay.

Argument	Required?	Description
--app <app>	yes	Path to the external app home.
--jdbc-url <jdbcUrl>	—	JDBC URL (default: the app’s –datasource config).
--datasource <name>	—	Named datasource whose configuration backs the connection, and the key for datasource-scoped work (default: main).
--username <username>	—	Database user for –jdbc-url.
--password <password>	—	Database password for –jdbc-url.
--env <profile>	—	Environment profile: merges config/env/.yml between the base config and the Studio overlay (also TESSERAQL_ENV).
--repo <dir>	—	Local artifact repository to resolve modules from — a bag produced by ‘tesseraql modules fetch’ on a connected machine (also -Dmaven.repo.local). Combine with –offline to resolve nothing over the network.

symbols

Print the app’s declared symbols (policies, message keys, domains, rules, decisions, routes, workflows) as JSON.

Argument	Required?	Description
--app <app>	yes	Path to the external app home.
--env <profile>	—	Environment profile: merges config/env/.yml between the base config and the Studio overlay (also TESSERAQL_ENV).
--repo <dir>	—	Local artifact repository to resolve modules from — a bag produced by ‘tesseraql modules fetch’ on a connected machine (also -Dmaven.repo.local). Combine with –offline to resolve nothing over the network.

release-diff

Diff two app trees: what does deploying the candidate change.

Argument	Required?	Description
--app <app>	yes	Path to the candidate app home (what you are about to deploy).
--env <profile>	—	Environment profile: merges config/env/.yml between the base config and the Studio overlay (also TESSERAQL_ENV).
--repo <dir>	—	Local artifact repository to resolve modules from — a bag produced by ‘tesseraql modules fetch’ on a connected machine (also -Dmaven.repo.local). Combine with –offline to resolve nothing over the network.
--baseline <baseline>	yes	Path to the baseline app home (what runs today: a checkout of the deployed tag or an unpacked release).
--json	—	Emit JSON instead of Markdown.
--out <out>	—	Also write the report to this file.

governance

Assess route governance and apply the review gate.

Argument	Required?	Description
--app <app>	yes	Path to the external app home.
--env <profile>	—	Environment profile: merges config/env/.yml between the base config and the Studio overlay (also TESSERAQL_ENV).
--repo <dir>	—	Local artifact repository to resolve modules from — a bag produced by ‘tesseraql modules fetch’ on a connected machine (also -Dmaven.repo.local). Combine with –offline to resolve nothing over the network.
--fail-on-violation	—	Whether unapproved routes fail (default: true).

admission

Run the admission profile over an app tree.

Argument	Required?	Description
--app <app>	yes	Path to the app home.
--env <profile>	—	Environment profile: merges config/env/.yml between the base config and the Studio overlay (also TESSERAQL_ENV).
--repo <dir>	—	Local artifact repository to resolve modules from — a bag produced by ‘tesseraql modules fetch’ on a connected machine (also -Dmaven.repo.local). Combine with –offline to resolve nothing over the network.

migrate

Apply/info/validate/repair the app’s db/migration scripts.

Argument	Required?	Description
<operation>	—	apply (default), info, validate, or repair.
--app <app>	yes	Path to the external app home.
--jdbc-url <jdbcUrl>	—	JDBC URL (default: the app’s –datasource config).
--datasource <name>	—	Named datasource whose configuration backs the connection, and the key for datasource-scoped work (default: main).
--username <username>	—	Database user for –jdbc-url.
--password <password>	—	Database password for –jdbc-url.
--env <profile>	—	Environment profile: merges config/env/.yml between the base config and the Studio overlay (also TESSERAQL_ENV).
--repo <dir>	—	Local artifact repository to resolve modules from — a bag produced by ‘tesseraql modules fetch’ on a connected machine (also -Dmaven.repo.local). Combine with –offline to resolve nothing over the network.

job

List, run, or rerun batch jobs in-process (exit 0 completed, 1 failed, 3 calendar-filtered).

Argument	Required?	Description
<operation>	yes	list, run, rerun, or cancel.
<target>	—	The job id (run) or execution id (rerun/cancel).
--app <app>	yes	Path to the external app home.
--jdbc-url <jdbcUrl>	—	JDBC URL (default: the app’s –datasource config).
--datasource <name>	—	Named datasource whose configuration backs the connection, and the key for datasource-scoped work (default: main).
--username <username>	—	Database user for –jdbc-url.
--password <password>	—	Database password for –jdbc-url.
--param <params>	—	Job parameter as name=value; repeatable.
--business-date <businessDate>	—	The business date the run is for (ISO yyyy-MM-dd; default: today). Shorthand for –param businessDate=….
--ignore-calendar	—	Run even when the job’s business-day calendar filters the date out.
--from-failed-step	—	rerun only: record the source execution’s completed steps as SKIPPED and start at its first failure.
--modules <dir>	—	Directory of optional plugin module jars (e.g. the pdf/excel file-format codecs), composed with the application’s declared tesseraql.modules.
--env <profile>	—	Environment profile: merges config/env/.yml between the base config and the Studio overlay (also TESSERAQL_ENV).
--repo <dir>	—	Local artifact repository to resolve modules from — a bag produced by ‘tesseraql modules fetch’ on a connected machine (also -Dmaven.repo.local). Combine with –offline to resolve nothing over the network.

identity-schema

Apply the managed IAM schema and optionally seed an administrator.

Argument	Required?	Description
--app <app>	—	App home for datasource fallback (optional; else use –jdbc-url). Precedence: an explicit –jdbc-url, then the app’s configured main datasource, then a running serve --embedded-db (its work/embedded-db.jdbc marker) when the config does not resolve or answer.
--jdbc-url <jdbcUrl>	—	JDBC URL (default: the app’s –datasource config).
--datasource <name>	—	Named datasource whose configuration backs the connection, and the key for datasource-scoped work (default: main).
--username <username>	—	Database user for –jdbc-url.
--password <password>	—	Database password for –jdbc-url.
--env <profile>	—	Environment profile: merges config/env/.yml between the base config and the Studio overlay (also TESSERAQL_ENV).
--repo <dir>	—	Local artifact repository to resolve modules from — a bag produced by ‘tesseraql modules fetch’ on a connected machine (also -Dmaven.repo.local). Combine with –offline to resolve nothing over the network.
--dialect <dialect>	—	SQL dialect (default: postgres).
--admin-login <adminLogin>	—	Administrator to create or update after the schema is applied.
--admin-password-file <adminPasswordFile>	—	File holding the admin password (else TESSERAQL_ADMIN_PASSWORD).
--admin-roles <adminRoles>	—	Role codes assigned to the administrator (default: iam.admin).
--admin-permissions <adminPermissions>	—	Permission codes created and granted to the admin roles (default: the framework’s bootstrap baseline — tql.app.use., tql.ops.view., tql.ops.run., tql.app.deploy., tql.studio.edit.*, tql.iam.admin.view, tql.iam.admin.write).

package

Package the app home into a deterministic .tqlapp.

Argument	Required?	Description
--app <app>	yes	Path to the external app home.
--env <profile>	—	Environment profile: merges config/env/.yml between the base config and the Studio overlay (also TESSERAQL_ENV).
--repo <dir>	—	Local artifact repository to resolve modules from — a bag produced by ‘tesseraql modules fetch’ on a connected machine (also -Dmaven.repo.local). Combine with –offline to resolve nothing over the network.
--out <out>	—	Output archive (default: /work/.tqlapp).
--generated <generated>	—	Generated docs directory to merge (default: /work/generated/docs when present).

verify

Verify release evidence against the app sources.

Argument	Required?	Description
--app <app>	yes	Path to the external app home.
--env <profile>	—	Environment profile: merges config/env/.yml between the base config and the Studio overlay (also TESSERAQL_ENV).
--repo <dir>	—	Local artifact repository to resolve modules from — a bag produced by ‘tesseraql modules fetch’ on a connected machine (also -Dmaven.repo.local). Combine with –offline to resolve nothing over the network.
--evidence-file <evidenceFile>	yes	The release-evidence.json to verify (its sibling .sig is auto-detected).
--require-signature	—	Fail if no signature envelope is present.
--expected-key-sha256 <expectedKeySha256>	—	SHA-256 fingerprint of the public key the evidence must be signed with.

modules

Manage the opt-in tesseraql.modules set.

modules add

Add a coordinate to tesseraql.modules and refresh modules.lock.

Argument	Required?	Description
<coordinate>	yes	Module coordinate: group:artifact[:version].
--app <app>	yes	Path to the external app home.
--env <profile>	—	Environment profile: merges config/env/.yml between the base config and the Studio overlay (also TESSERAQL_ENV).
--repo <dir>	—	Local artifact repository to resolve modules from — a bag produced by ‘tesseraql modules fetch’ on a connected machine (also -Dmaven.repo.local). Combine with –offline to resolve nothing over the network.
--offline	—	Resolve only from the local repository.

modules resolve

Resolve tesseraql.modules and (re)write modules.lock.

Argument	Required?	Description
--app <app>	—	Path to the external app home.
--stack <dir>	—	Resolve every member of the stack: an install root (catalog.json) or a folder of application homes — the operator step a host’s declared-but-unresolved refusal names.
--env <profile>	—	Environment profile: merges config/env/.yml between the base config and the Studio overlay (also TESSERAQL_ENV).
--repo <dir>	—	Local artifact repository to resolve modules from — a bag produced by ‘tesseraql modules fetch’ on a connected machine (also -Dmaven.repo.local). Combine with –offline to resolve nothing over the network.
--offline	—	Resolve only from the local repository.

modules fetch

Fetch every module a stack needs into a portable bag.

Argument	Required?	Description
--app <app>	—	Path to a single external app home.
--stack <dir>	—	Collect for every member of the stack: an install root (catalog.json) or a folder of application homes.
--into <dir>	yes	The bag to fill: a local Maven repository the disconnected side reads with –repo.
--platform <classifier>	—	Embedded PostgreSQL binaries to include, by zonky classifier (e.g. linux-amd64,windows-amd64). Omit for none.
--embedded-db-version <version>	—	Binary version for –platform (default: the CLI’s built-in default). Pass the version a persistent data directory is pinned to when it differs.
--env <profile>	—	Environment profile: merges config/env/.yml between the base config and the Studio overlay (also TESSERAQL_ENV).
--repo <dir>	—	Local artifact repository to resolve modules from — a bag produced by ‘tesseraql modules fetch’ on a connected machine (also -Dmaven.repo.local). Combine with –offline to resolve nothing over the network.

modules list

List the declared tesseraql.modules.

Argument	Required?	Description
--app <app>	yes	Path to the external app home.
--env <profile>	—	Environment profile: merges config/env/.yml between the base config and the Studio overlay (also TESSERAQL_ENV).
--repo <dir>	—	Local artifact repository to resolve modules from — a bag produced by ‘tesseraql modules fetch’ on a connected machine (also -Dmaven.repo.local). Combine with –offline to resolve nothing over the network.

embedded-db

Inspect an –embedded-db data directory and its PostgreSQL version.

embedded-db info

Report the directory’s PostgreSQL version and upgrade guidance.

Argument	Required?	Description
<data-dir>	yes	The –embedded-db data directory to inspect.

duckdb

Provision and inspect the analytics engine’s offline extension cache.

duckdb install-extensions

Resolve declared engine extensions into the offline cache (or from/into a bundle).

Argument	Required?	Description
--app <app>	yes	Path to the app home.
--env <profile>	—	Environment profile: merges config/env/.yml between the base config and the Studio overlay (also TESSERAQL_ENV).
--repo <dir>	—	Local artifact repository to resolve modules from — a bag produced by ‘tesseraql modules fetch’ on a connected machine (also -Dmaven.repo.local). Combine with –offline to resolve nothing over the network.
--repository <repository>	—	Extension repository URL (a corporate mirror); default is DuckDB’s.
--bundle <bundle>	—	Also write the cache as a portable zip for air-gapped provisioning.
--from-bundle <fromBundle>	—	Populate the cache from a bundle zip instead of the network.

duckdb info

Report the engine pin, the cache location, and which declared extensions it holds.

Argument	Required?	Description
--app <app>	yes	Path to the app home.
--env <profile>	—	Environment profile: merges config/env/.yml between the base config and the Studio overlay (also TESSERAQL_ENV).
--repo <dir>	—	Local artifact repository to resolve modules from — a bag produced by ‘tesseraql modules fetch’ on a connected machine (also -Dmaven.repo.local). Combine with –offline to resolve nothing over the network.

mcp

Serve the developer MCP tools over stdio or HTTP.

Argument	Required?	Description
--stack <dir>	—	Directory holding the applications to serve: an install root (catalog.json) or a folder of application homes. Discovered one level up from the working directory when omitted.
--app-name <name>	—	Serve only this application’s tools from the stack.
--env <profile>	—	Environment profile: merges config/env/.yml between the base config and the Studio overlay (also TESSERAQL_ENV).
--repo <dir>	—	Local artifact repository to resolve modules from — a bag produced by ‘tesseraql modules fetch’ on a connected machine (also -Dmaven.repo.local). Combine with –offline to resolve nothing over the network.
--modules <dir>	—	Directory of optional plugin module jars (e.g. the pdf/excel file-format codecs), composed with the application’s declared tesseraql.modules.
--transport <transport>	—	Transport: stdio (default) or http. Default: stdio.
--read-only	—	Expose only the read tools.
--port <port>	—	HTTP port (http transport). Default: 8765.
--bind <bind>	—	HTTP bind address (http transport). Default: 127.0.0.1.
--insecure	—	Allow the HTTP transport off-loopback without authentication.