tnl.dev :: docs

automation.

Read JSON and NDJSON tunnel state and diagnostics.

follow a publish run

Use NDJSON for an explicit foreground publication:

tnl publish 3000 --output ndjson

Each stdout line is one JSON object with schema_version: 1, type, a monotonically increasing invocation-local cursor, and tunnel_id. A successful public HTTP run emits starting, then ready with url and publish_run_number. Warnings and errors can appear between lifecycle events. A later ready can refer to a new publish run; do not assume there is only one.

Optional fields include target, url, publish_run_number, message, code, help_url, retryable, retry_at, reason, and transport. Absent fields are omitted. Clean cancellation emits stopped with reason: "canceled". Do not parse human progress frames as machine output.

observe local apps

Start an integrated app with its normal development command. In another process:

tnl wait --output json
tnl watch --output ndjson

wait performs fresh public readiness checks; --service NAME can be repeated and --timeout defaults to 2m. Private services use native clients through tnl connect instead of a public readiness probe.

watch follows the local runtime's ordered events. Resume exclusively after its opaque local event cursor with --after CURSOR. This cursor is separate from a publish invocation cursor and from the team audit cursor. App registration and a recorded URL do not by themselves prove public readiness.

read local and server state

tnl status --scope=local --output json
tnl status --scope=server --output json
tnl status --all --scope=both --output json

The status envelope has schema_version: 1, scope, and projects. Each project has its project path and separate local and server records; an unselected scope is null. Local state includes the app snapshot and local tunnel records. Server state includes availability, check time, control URL, public URLs, and, for managers of an applied project, its applied configuration and observed member state. Check availability and reason fields rather than treating an unavailable server as an empty inventory.

--all expands local project discovery; it does not enumerate every project on the server. status reads state without making an app request. Use wait, a public HTTP client, or a private native client for a fresh end-to-end check.

reconcile and read audit history

tnl check
tnl apply --output json
tnl audit list --team shop --since 24h --limit 100 --output json

apply sends the CLI-evaluated normalized revision to control. Keep desired configuration in Git and explicitly apply changes; starting pnpm dev does not deploy remote changes. See publisher groups.

audit list requires team-manager access. Use --service for a private name, public hostname, or immutable ID and --after to resume from the returned cursor with the same filters. Management facts commit transactionally; unsampled asynchronous connection observations use bounded reporting and can be lost on a crash or outage. They are not complete durable request history. See audit guarantees.

follow preview feedback

tnl feedback list --output=json
tnl feedback inspect FEEDBACK_ID --output=json
tnl feedback watch --after CURSOR --output=ndjson

The list returns schema_version, threads, and event_cursor. Persist the last processed feedback event cursor and resume with --after; it is separate from local lifecycle and service-audit cursors. Replies and updates increase message counts; status changes advance history. inspect includes the immutable report, evidence, history, and a comparison with the current local source.

Source matching uses the Git commit, project-relative path, and changed-file blob IDs and modes when capture is complete. Branch names and staging do not affect matching. Incomplete or bounded captures cannot prove a match. Verified author identity comes from authenticated server context, not a display name supplied by the caller. See the feedback workflow.

handle diagnostics

Machine warning and error output includes a stable reason, authored message, and retry information where supported. Documented diagnostics and client errors supply code and help_url; retry_at appears when a rate-limited response supplies a retry deadline. Branch on stable reasons and codes, not message text. Treat unknown reasons and nonzero exits as failures, including argument failures before a lifecycle stream starts.

The diagnostic catalogue, diagnostic JSON catalogue, and client-error JSON catalogue describe current codes. A known case query parameter adds specific guidance; unknown cases show the base page. Never put messages or credentials in a help URL. A failed live application connection is never replayed or migrated by tnl.

Public URL responses generated by tnl identify their diagnostic in Tnl-Error-Code and negotiate HTML or plain text. Control, built-in authority, private ingress, and private relay APIs return application/problem+json with type, title, status, code, detail, and request_id. These API problems have a separate namespace; an optional Link with rel="help" is not the problem's canonical type. Include the request ID when reporting a persistent failure; do not parse titles or details.