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. The build gates — lint, test, coverage, generate, schema, migrate, identity-schema, package, release-diff, governance, admission and verify — call the same engine as the matching tesseraql: Maven goal (tesseraql:package-app for package, tesseraql:verify-evidence for verify, tesseraql:report for test --report), so a CLI loop and a CI pipeline do the same work. Every other subcommand is the CLI’s alone, and tesseraql:release-evidence is CI’s alone.

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

The deployment roster

The deployment distribution — the container image and the Windows zip — runs tesseraql-host, whose root command names only the verbs below. Every other command on this page belongs to the developer CLI, and tesseraql-host answers it with an unmatched-argument error rather than running it.

Each verb is the same command the developer CLI declares, so its options and behaviour are documented in its own section below.

Verb	What it does
host	Serve every installed app from one port, each in its own runtime.
deploy	Deploy one application into a stack’s install root; a running host replaces its runtime without a restart.
routes	List the routes discovered in the app.
token	Obtain a bearer token: mint one from an app’s HS256 secret (–app), or sign in to a running application and exchange (–url).
migrate	Apply/info/validate/repair the app’s db/migration scripts.
job	List, run, or rerun batch jobs in-process (exit 0 completed, 1 failed, 3 calendar-filtered).
identity-schema	Apply the managed IAM schema and optionally seed an administrator.
verify	Verify release evidence against the app sources.
admission	Run the admission profile over an app tree.
duckdb	Provision and inspect the analytics engine’s offline extension cache.

Exit codes

Every command, on both binaries, answers with one of these; tesseraql --help prints the same list. The rule: 2 means nothing ran, 1 means the command ran and failed.

Code	Meaning
0	The command did what was asked.
1	The command ran and failed — a database it could not reach (one operator message, no stack trace), a job that ended FAILED, or an unexpected error with its stack trace.
2	Nothing ran: the request could not be run at all — a missing or unparseable flag, a directory that is not an application, a declaration the command cannot act on, a modules.lock that does not match — one line on stderr saying what to change, or the framework’s own coded sentence (TQL-…) naming the declaration.
3	The command ran and a policy gate said no — job run’s business-day calendar filtered the date out or its overlap policy skipped the firing; test --fail-on-regression ran the suites green and found SQL coverage below the previous run’s.

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.
--offline	—	Resolve modules only from the local repository, never over the network. Pair with –repo to resolve from a bag produced by ‘tesseraql modules fetch’.
--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; 0 binds a free one). The address is printed and written to each application’s work/dev.origin.
--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.
--offline	—	Resolve modules only from the local repository, never over the network. Pair with –repo to resolve from a bag produced by ‘tesseraql modules fetch’.
--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 candidate the host has not applied, or restore the previous version as active.

Argument	Required?	Description
<name>	yes	The application to roll back.
--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 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.
--offline	—	Resolve modules only from the local repository, never over the network. Pair with –repo to resolve from a bag produced by ‘tesseraql modules fetch’.
--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.
--offline	—	Resolve modules only from the local repository, never over the network. Pair with –repo to resolve from a bag produced by ‘tesseraql modules fetch’.
--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.
--offline	—	Resolve modules only from the local repository, never over the network. Pair with –repo to resolve from a bag produced by ‘tesseraql modules fetch’.

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.
--offline	—	Resolve modules only from the local repository, never over the network. Pair with –repo to resolve from a bag produced by ‘tesseraql modules fetch’.

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.
--offline	—	Resolve modules only from the local repository, never over the network. Pair with –repo to resolve from a bag produced by ‘tesseraql modules fetch’.
--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. With –app, none given mints the application-use grant (tql.app.use.) so the token can enter the application it is minted for.
--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 3 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.
--offline	—	Resolve modules only from the local repository, never over the network. Pair with –repo to resolve from a bag produced by ‘tesseraql modules fetch’.

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.
--offline	—	Resolve modules only from the local repository, never over the network. Pair with –repo to resolve from a bag produced by ‘tesseraql modules fetch’.

bench

Drive an application’s declared routes with load and report percentiles and refusals by code.

Argument	Required?	Description
--app <app>	yes	Path to the app home; the routes and their inputs come from its manifest.
--url <base-url>	yes	Base URL of the running application, including the base path if it has one (/ on a stack).
--route <id>	—	A GET route to drive, filled from its declared inputs’ defaults; repeatable. A write needs a scenario.
--scenario <file>	—	A kind: bench scenario (bench/.yml): the requests, their weights and the run’s shape.
--concurrency <n>	—	Workers in the closed loop; with –rate, the bound on requests in flight (default 10, or the scenario’s).
--duration <duration>	—	How long to run, e.g. 30s or 2m (default 30s, or the scenario’s).
--ramp-up <duration>	—	Start the workers spread across this span (default none, or the scenario’s).
--rate <per-second>	—	Open loop: offer this many requests per second instead of the closed loop’s workers.
--token-file <file>	—	A file holding the bearer token (else TESSERAQL_TOKEN); a token holding ops.metrics.view also reads the scrape before and after the run.
--login <id>	—	Sign in as this login and exchange for a token, as token –url does; the password comes from TESSERAQL_PASSWORD or a prompt.
--format <format>	—	Output format: text, json (default: text). Default: text.
--expect <checks>	—	Thresholds, comma-separated (p95<250ms, refused<1%, errors<=0, throughput>500); one not met exits 3.
--no-scrape	—	Do not read /_tesseraql/metrics before and after the run.
--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 modules only from the local repository, never over the network. Pair with –repo to resolve from a bag produced by ‘tesseraql modules fetch’.
--modules <dir>	—	Directory of optional plugin module jars (e.g. the pdf/excel file-format codecs), composed with the application’s declared tesseraql.modules.

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.
--offline	—	Resolve modules only from the local repository, never over the network. Pair with –repo to resolve from a bag produced by ‘tesseraql modules fetch’.
--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.
--offline	—	Resolve modules only from the local repository, never over the network. Pair with –repo to resolve from a bag produced by ‘tesseraql modules fetch’.

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.
--offline	—	Resolve modules only from the local repository, never over the network. Pair with –repo to resolve from a bag produced by ‘tesseraql modules fetch’.

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.
--offline	—	Resolve modules only from the local repository, never over the network. Pair with –repo to resolve from a bag produced by ‘tesseraql modules fetch’.
--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.
--offline	—	Resolve modules only from the local repository, never over the network. Pair with –repo to resolve from a bag produced by ‘tesseraql modules fetch’.
--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.
--offline	—	Resolve modules only from the local repository, never over the network. Pair with –repo to resolve from a bag produced by ‘tesseraql modules fetch’.

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.
--offline	—	Resolve modules only from the local repository, never over the network. Pair with –repo to resolve from a bag produced by ‘tesseraql modules fetch’.

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.
--offline	—	Resolve modules only from the local repository, never over the network. Pair with –repo to resolve from a bag produced by ‘tesseraql modules fetch’.

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 dev --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.
--offline	—	Resolve modules only from the local repository, never over the network. Pair with –repo to resolve from a bag produced by ‘tesseraql modules fetch’.
--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.
--offline	—	Resolve modules only from the local repository, never over the network. Pair with –repo to resolve from a bag produced by ‘tesseraql modules fetch’.
--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.
--offline	—	Resolve modules only from the local repository, never over the network. Pair with –repo to resolve from a bag produced by ‘tesseraql modules fetch’.
--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 modules only from the local repository, never over the network. Pair with –repo to resolve from a bag produced by ‘tesseraql modules fetch’.

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 modules only from the local repository, never over the network. Pair with –repo to resolve from a bag produced by ‘tesseraql modules fetch’.

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.
--offline	—	Resolve modules only from the local repository, never over the network. Pair with –repo to resolve from a bag produced by ‘tesseraql modules fetch’.

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.
--offline	—	Resolve modules only from the local repository, never over the network. Pair with –repo to resolve from a bag produced by ‘tesseraql modules fetch’.

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.
--offline	—	Resolve modules only from the local repository, never over the network. Pair with –repo to resolve from a bag produced by ‘tesseraql modules fetch’.
--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.
--offline	—	Resolve modules only from the local repository, never over the network. Pair with –repo to resolve from a bag produced by ‘tesseraql modules fetch’.

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.
--offline	—	Resolve modules only from the local repository, never over the network. Pair with –repo to resolve from a bag produced by ‘tesseraql modules fetch’.
--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.
--allow-origin <origin>	—	A browser origin (scheme://host[:port]) the HTTP transport answers besides loopback; repeatable. A request from any other Origin is refused (http transport).