tnl.dev :: docs

tnl commands.

Find tnl commands, flags, and output behavior.

project and tunnel commands

Run the installed binary as tnl, pnpm exec tnl, npx tnl, or bunx tnl. Run tnl COMMAND --help for generated flag help. Your app's normal development command starts the app; its integration registers the listener with tnl.

CommandUse
tnl init [--no-install]Set up project configuration and framework integration.
tnl checkValidate project configuration and print the selected path offline.
tnl generate / tnl generate --checkGenerate portable types and workload metadata, or check drift.
tnl apply [--output human|json]Evaluate project configuration and reconcile a normalized revision with control.
tnl publish [SERVICE-OR-TARGET]Publish a configured local service or running target.
tnl publish --demoStart a disposable built-in HTTP demo.
tnl status [--scope local|server|both] [--all] [--output human|json]Read local snapshots, fresh server facts, or both (default).
tnl wait [--service NAME-OR-INVOCATION-ID]Wait for fresh readiness checks of local services and standalone SDK publications.
tnl watch [--after CURSOR] [--output human|ndjson]Follow ordered local lifecycle events.
tnl auth status / tnl auth login [--team NAME] / tnl auth logoutInspect sign-in, run the single control-owned device approval flow, or sign out.
tnl auth register NAME --visit RESOURCE_ID --output-file FILERegister an application signing key with explicit visit, publish, or allocation grants.
tnl telemetry status / off / onInspect or change the local telemetry preference.
tnl versionPrint the raw version line.

publicURL (public_url in static files) declares an HTTP public URL. Other configured services have managed TLS endpoints and are connector-only by default; a named group's public: true enables direct access on their allocated ports. Protocols are http, tcp, mysql, and postgres. tnl publish SERVICE uses a local target; named remote services run through publisher serve. See configuration.

Local status, wait, and watch also observe standalone SDK publications in the selected project and client state directory; they do not require a project configuration file. status --scope local includes invocation-owned registrations alongside configured services. Copy an ivk_… service key from its JSON output to select one publication with wait --service. Repeat --service to select several.

Without a selector, wait captures the configured local services and current standalone registrations when it first finds targets. With no targets yet, it waits for a standalone registration or times out; an empty snapshot never proves readiness. Every successful wait requires a fresh check from the local publisher. Remote publisher groups and stopped historical invocations are not default wait targets. watch --after resumes exclusively after the same opaque local event cursor, including standalone registration, readiness, and cleanup events.

For ad-hoc public HTTP, tnl publish 3000 accepts --open, --domain, --name, --public-url, --anonymous, repeatable --ip, --ephemeral, --require-post-quantum, --requests, --rate-requests, --rate-per, --rate-burst, and --concurrency. --requests is a total budget; --concurrency limits simultaneous work. Restricted access is the default; an IP match does not replace a visitor credential. --anonymous removes that credential requirement. HTTPS targets can use --target-ca-file and --target-tls-name for verified target trust. See post-quantum policy for the visitor handshake requirement.

The guest demo uses a secret link printed once, with one active demo, 72-hour credential expiry, and 20 cumulative minutes ready, including idle time, across runs. It does not accept a target or fixed hostname. Run tnl auth login to publish your own app.

tnl generate writes portable TypeScript declarations, a typed Python package, and metadata for declared workloads. App preparation writes browser-safe runtime metadata to .tnl/local/project.json. Generation does not sign in, call AWS, or generate infrastructure. --output-dir PATH selects another output directory; use the same path when checking. Generated paths are tool-owned and may be replaced; keep handwritten files elsewhere. --check compares without writing. See running publishers in AWS for operator-owned deployment.

connect by approved service metadata

CommandUse
tnl connect availableList accessible managed services, including offline services.
tnl connect NAMEOpen an authenticated local listener and print verified native client instructions for a private or public managed endpoint.
tnl connect NAME --stdioCarry one opaque TCP stream on stdin/stdout, private or public. Suitable for SSH ProxyCommand; not a native database mode.
tnl connect NAME --listen 127.0.0.1:PORTOverride the local listener for HTTP, PostgreSQL, MySQL, opaque TCP, or Kubernetes.
tnl connect NAME --detachRun independently of the terminal without automatic restart.
tnl connect NAME --installRun under the installed user supervisor with a saved sign-in.
tnl connect list [--output human|json]List installed connectors.
tnl connect stop NAME / tnl connect remove NAMEStop an installed connector, or remove its job and remembered port.

Foreground is the default; --foreground, --detach, and --install are mutually exclusive. --listen accepts only loopback IPs and ports 1–65535 and can be combined with --detach for every approved protocol. --protocol is only an equality check against approved metadata. --output=json reports the ready local connection and native client instructions; tnl keeps the connector running and does not launch an application client. HTTP uses the managed HTTPS hostname and allocated service port with a printed loopback override. The connector authenticates the visitor, so the application needs no tnl client certificate. Sign in before --stdio; stdout is only application bytes. See connector connection instructions.

publishers and local jobs

The prerelease single-URL Ubuntu workflow installs its supervisor and scoped publisher identity in one command:

tnl publish http://127.0.0.1:4096 --name opencode --team studio --install --system

It signs in as needed, preserves saved visitor policy unless explicitly changed, and proves readiness before reporting success. See installed publishers for private system state, reboot, Compose TNL_ENROLL_KEY, and recovery.

CommandUse
tnl publisher provision --group GROUP --instance REPLICA --output-file FILEProvision a replica-private portable group identity. Never overwrites a file.
tnl publisher enroll --group GROUP [--members 1] [--expires-in 10m]Issue bootstrap enrollment for an applied group.
tnl publisher enroll PUBLIC_URL_ID --team TEAM --name NAMEPrint one-use enrollment for an exact saved public URL.
tnl publisher serve --group GROUP [--project-key KEY] --instance REPLICAReconcile only this member's applied group assignments.
tnl publisher current [--check]Inspect the selected publisher and optionally check its grant, without exposing its key.
tnl publisher list [--team TEAM]List manageable publisher identities, grants, and control-observed active/last-seen runtime evidence.
tnl publisher revoke PUBLISHER_ID [--team TEAM]Revoke an exact publisher identity, including a retired group replica.
tnl publisher rename OLD NEWRename the configuration selector, retaining group identity and DNS namespace.
tnl publisher namespace rename GROUP LABEL --expected-revision N --request-id IDExplicitly rename managed DNS scope; reuse the same arguments after a lost reply.
tnl publisher setup --namespacePrepare a local HTTP namespace publisher.
tnl publisher provision --namespace --output-file FILEWrite a portable namespace publisher credential for another host.
tnl publisher provision --url PUBLIC_URL_ID --output-file FILEProvision a portable single-public-URL publisher. --service ID selects an exact service instead.
tnl service installInstall or refresh the user-login supervisor before using --install.
tnl service list / status JOB / start JOB / stop JOB / remove JOBManage installed local publications.
tnl detached list / tnl detached stop IDInspect or stop detached processes.

Group provision, enroll, and serve accept --project-key; outside the checkout supply it and an explicit --server. serve accepts --identity-file FILE or injected TNL_GROUP_IDENTITY, --identity-dir for durable signing/TLS keys and certificate state, and --state-dir for local SQLite/runtime state. provision retains the replica signing key; leases stay short-lived. Portable identity input cannot be combined with enrollment. First enrollment can use TNL_GROUP_ENROLL_KEY or foreground --enroll-key -; later replacements prove the saved key. Each replica needs independent identity storage. See publisher groups.

publish, connect, and publisher serve support foreground (default), detached, and installed modes. Group publishers and connectors use the user supervisor. --system is for explicit single-service publishers, not group replicas or connectors. Stopping a job does not revoke its server grant.

workload selection

Prerelease policies use root workloads (tnl.workloads in static files). The GitHub action requires workload: NAME under with; services only narrows that policy. Native runtime selection uses --workload NAME and optionally --workload-manifest PATH to use packaged .tnl/generated/workloads.json without Git/config evaluation. See workloads for provider fields and session deadlines. These runtime flags are the machine integration contract, not extra arguments to ordinary tnl connect NAME or a finalized SDK option.

team service audit

tnl audit list --team shop --since 24h
tnl audit list --team shop --service orders --since 24h --limit 100 --output json

Team managers can filter by private name, public hostname, or immutable service ID. --since accepts a positive duration or RFC3339 timestamp. --limit is 1–10000, default 100. Resume with --after and the returned cursor while retaining the same filters. See audit guarantees.

sharing, feedback, and local selection

For exact private-service and managed HTTP access:

tnl share service invite create orders --email sam@example.com --expires-in 4h
tnl share service invite accept SECRET
tnl share service list orders
tnl share service revoke orders ACCESS_ID
tnl share service token create api --expires-in 4h
tnl share service link create api --expires-in 4h

Select the configured service key or exact svc_… ID. Creation requires exactly one of --expires-in or --expires-at: invitations allow at most 30 days, managed HTTP tokens/links at most 7 days. List includes secretless HTTP grant IDs and expired/revoked history. Revoke uses an exact sivt_…, sgr_…, or shg_… ID on that service. The token command prints one visitor credential for its advertised lifetime. See service access.

CommandUse
tnl share link create [URL] [--preview]Print a browser link for one HTTP public URL or the current preview URLs.
tnl share token create URL --name NAMEPrint one URL-bound credential for the Tnl-Visitor-Token HTTP header, usable for the share lifetime.
tnl share list [URL]List manageable shares.
tnl share revoke SHARE_IDRevoke a link or token; new HTTP requests stop using it within two minutes.
tnl share team create [URL] / tnl share team revoke [URL]Grant or revoke team access for an exact URL, or this preview without URL.
tnl share invite create URL --email ADDRESS [--expires-in 2h]Print a one-time invitation secret for a verified-email HTTP visitor.
tnl share invite accept SECRETAccept an invitation after signing in with its verified email.
tnl share invite list URL / tnl share invite revoke URL INVITATION_IDInspect or revoke URL-scoped visitor invitations.
tnl feedback list / tnl feedback inspect FEEDBACK_IDRead threads and immutable reports.
tnl feedback watch [--after CURSOR]Follow resumable feedback events, NDJSON by default.
tnl feedback reply FEEDBACK_ID --message TEXTReply without changing status.
tnl feedback update FEEDBACK_ID --message TEXTPost an implementer update with current source state.
tnl feedback resolve FEEDBACK_ID [--message TEXT] / reopen FEEDBACK_ID [--message TEXT]Change thread status.
tnl webhook use NAME [--force] / tnl webhook release NAMEChoose or release a selected webhook receiver.
tnl alias use NAME [--force] / tnl alias release NAMEChoose this worktree or restore the primary checkout for an alias.
tnl inspect list / tnl inspect show NUMBERRead recent local HTTP and supported TCP activity.

Feedback readers and writes support --output=human|json; watch supports human|ndjson. Feedback, local inspection, and team audit have different scopes and cursors. See feedback, webhooks, and aliases.

Share links and tokens expire after 24 hours by default; --expires-in 7d selects a week, up to 30 days. --preview captures the current preview's HTTP public URL IDs; tokens require one URL and a name. Creation prints the secret once, while list and revoke do not reveal it. See sharing recipes.

teams, domains, and public urls

CommandUse
tnl team current / tnl team listShow selected team or available memberships.
tnl team use TEAMSave a team name or ID for commands without a project team.
tnl team create NAME [--member-slug SLUG]Create an organization team.
tnl team members [--team TEAM]List memberships and IDs.
tnl team invite create --member-slug SLUG [--role member|admin|owner] [--email ADDRESS] [--expires-in 168h]Create an invitation; prints its ID and secret once.
tnl team invite list / tnl team invite revoke INVITATION_IDInspect or revoke invitations.
tnl team join SECRETAccept an invitation and select its team.
tnl team member set-role MEMBERSHIP_ID --role member|admin|owner / tnl team member remove MEMBERSHIP_IDChange a membership.
tnl domain claim DOMAIN [--default] / status DOMAIN / list / default DOMAIN / release DOMAINManage team domains and delegation.
tnl url list [--team TEAM] / tnl url delete PUBLIC_URL_IDList or delete saved public URLs.
tnl url access show URLRead the saved visitor mode and IP filter.
tnl url access set URL restricted|anonymous [--ip ADDRESS-OR-CIDR]Replace the complete visitor policy without restarting.

See teams for roles and domains for NS delegation.

tnl auth login [--team NAME] always starts control's device approval flow. Open the approval URL, choose the team when prompted, authenticate through the configured issuer, and approve the matching code. --open opens the URL for you. Hosted sign-in uses shared GitHub/Google/Microsoft apps; company access additionally requires the selected source. Self-hosted Google/Entra uses the same control flow with explicit operator admission rules. There is no provider-native CLI device grant or login-token path. Refresh does not extend the original company proof; sign in again when it expires, then restart connect with the current session.

server administration

CommandUse
tnl admin server statusShow control, ingress, relay, and public URL state.
tnl admin relays listList relay leases, process run IDs, and revisions.
tnl admin relays drain RELAY_ID --relay-run-id RUN_ID --relay-lease-revision REVISION [--deadline 30s]Drain the exact selected relay lease.
tnl admin maintenance list / allow NAME / block NAMEInspect or change maintenance gates.

See operations for operating a tnl server.

flags and output

--config PATH selects a file before TNL_CONFIG; --no-config skips discovery. Put these root flags before the command. --no-telemetry is also a root flag. Where supported, --server (TNL_SERVER) overrides the configured or selected server, --state-dir (TNL_STATE_DIR) selects client state, and --team (TNL_TEAM) selects the invocation's team. An explicit access token with a project-selected server requires explicit server selection.

Use --output only where generated help lists it. publish and watch support NDJSON; finite readers such as status, apply, and audit list support JSON. Machine formats go to stdout. Human lifecycle output, warnings, and errors go to stderr; finite results go to stdout. Apps own their output. tnl version and one-time credentials remain raw values. See automation.

telemetry

tnl sends optional pseudonymous telemetry to https://tnl.dev/api/telemetry by default, including for demos, local app publishers, and native connectors. Reports contain bounded command outcomes, version, OS, architecture, CI status, a random installation ID and event IDs. Publication reports can include readiness, the first demo ping, and coarse OAuth/webhook outcomes. Transport reports count connection, fallback, and recovery outcomes by path (quic, tls_tcp, or direct_udp), with coarse setup/recovery duration buckets. They do not contain traffic volumes or RTT histograms.

Reports exclude public URLs, team or service IDs, IP addresses, peer candidates, targets, arguments, raw errors, tokens, OAuth codes, webhook content, request details, invocation IDs, and client timestamps. Each event retains the client metadata captured when it was collected, even if another client version sends it later. The client retains unsent events for up to seven days; the website removes reports 365 days after their first receipt, without extending retention on retries. This is separate from operator counters and team service audit history.

tnl telemetry off
tnl telemetry status
tnl telemetry on

The telemetry commands do not send telemetry. The saved choice controls collection and delivery for that client state, including background and SDK-started work. The root flag --no-telemetry or TNL_NO_TELEMETRY=1 disables one invocation and the work it starts; it does not change the saved preference. Browser privacy headers are not a substitute for these client controls.

For one SDK app registration, use await tnl.prepare({ telemetry: false }) in TypeScript or await tnl.prepare(telemetry=False) in Python. This opt-out stays with that publication; it does not disable a sibling app sharing the local tnl process. Omitting the option does not override a saved opt-out. Installed jobs capture the installing client's choice, including invocation-level opt-out, and keep it across supervisor restarts and privileged installation.

Turning telemetry off clears unsent records and cancels delivery for that client state. Turning it back on does not restore discarded records or counters collected before the opt-out.

The site uses Vercel Web Analytics for public page views. Landing-page sign-in and quickstart clicks and installation-copy events are stored separately without visitor IDs, copied text, URLs, or query parameters and removed after 365 days. CLI telemetry preferences control only CLI reports.