Commands

This page lists every current Controli command and flag.

Host a tunnel session

controli host tunnel --workspace main --public-url https://cli.example.com

Starts the configured workspace shell and serves the browser terminal locally for a named Cloudflare Tunnel. This is the recommended transport for long sessions.

Flag	Required	Default	Purpose
--workspace <name>	Yes		Workspace key from ~/.controli/state.json.
--public-url <url>	Yes		Public Cloudflare Tunnel hostname.
--listen <addr>	No	127.0.0.1:8765	Local HTTP service address for cloudflared.
--room <name>	No	Workspace name	Room label shown to the guest.
--relay-url <url>	No	Configured relay or default relay	Worker URL used only for 7-digit invite lookup.
--name <name>	No	guest	Guest label stored in the invite.
--minutes <n>	No	1440	Session lifetime in minutes. Use 0 for no fixed Controli expiry.
--shell <path>	No	Workspace shell or default shell	Shell to start for this session.
--persist	No	true	Keep macOS/Linux shells in a persistent tmux session when available.
--persist-name <name>	No	controli-<workspace>	Stable tmux session name for reattaching.
--print-only	No	false	Print a code without starting the shell.
--long-code	No	false	Print the full self-contained code instead of a 7-digit code.
--password <value>	No	generated	Join password required with the 7-digit code.
--mode full	No	full	Guest can type after host approval.
--mode view	No		Guest can watch only.
--mode approve	No		Host approves each input chunk.
--approve=false	No	true	Skip the first host approval prompt.
--audit-log <path>	No	~/.controli/audit/<session>.jsonl	Custom audit log path.
--audit-log off	No		Disable audit logging.
--audit-input	No	false	Store typed input text in audit records.
--status-interval 30s	No	disabled	Print session counters while hosting.
--downloads	No	false	Allow browser-terminal downloads from <workspace>/controli-drive.
--download-code <value>	No	CONTROLI_DOWNLOAD_CODE	Let guests authorize downloads with this secret code; wrong or blank codes fall back to host approval.
--s4d-code <value>	No	CONTROLI_S4D_CODE	Alias for --download-code.
--download-approve=false	No	true	Deprecated; use --download-code or host approval.

Examples:

controli host tunnel --workspace main --public-url https://cli.example.com --minutes 0
controli host tunnel --workspace main --public-url https://cli.example.com --persist-name main
controli host tunnel --workspace main --public-url https://cli.example.com --mode view
controli host tunnel --workspace main --public-url https://cli.example.com --listen 127.0.0.1:9000
controli host tunnel --workspace main --public-url https://cli.example.com --approve=false

Host a relay fallback session

controli host share --workspace main

Starts the configured workspace shell, registers a 7-digit invite code plus a join password, and sends terminal traffic through the Durable Object relay. Use this for short sessions or fallback testing; long relay sessions can exhaust Cloudflare's free Durable Objects duration.

Flag	Required	Default	Purpose
--workspace <name>	Yes		Workspace key from ~/.controli/state.json.
--room <name>	No	Workspace name	Room label shown to the guest.
--relay-url <url>	No	Configured relay	Override the relay for this share.
--name <name>	No	guest	Guest label stored in the invite.
--minutes <n>	No	120	Session lifetime in minutes. Use 0 for no fixed Controli expiry.
--shell <path>	No	Workspace shell or default shell	Shell to start for this session.
--persist	No	true	Keep macOS/Linux shells in a persistent tmux session when available.
--persist-name <name>	No	controli-<workspace>	Stable tmux session name for reattaching.
--print-only	No	false	Print a code without starting the shell.
--long-code	No	false	Print the full self-contained code instead of a 7-digit code.
--password <value>	No	generated	Join password required with the 7-digit code.
--mode full	No	full	Guest can type after host approval.
--mode view	No		Guest can watch only.
--mode approve	No		Host approves each input chunk.
--approve=false	No	true	Skip the first host approval prompt.
--audit-log <path>	No	~/.controli/audit/<session>.jsonl	Custom audit log path.
--audit-log off	No		Disable audit logging.
--audit-input	No	false	Store typed input text in audit records.
--status-interval 30s	No	disabled	Print session counters while hosting.
--downloads	No	false	Allow browser-terminal downloads from <workspace>/controli-drive.
--download-code <value>	No	CONTROLI_DOWNLOAD_CODE	Let guests authorize downloads with this secret code; wrong or blank codes fall back to host approval.
--s4d-code <value>	No	CONTROLI_S4D_CODE	Alias for --download-code.
--download-approve=false	No	true	Deprecated; use --download-code or host approval.

Examples:

controli host share --workspace main --minutes 480 --mode full
controli host share --workspace main --mode view
controli host share --workspace main --mode approve
controli host share --workspace main --room support-a --status-interval 30s
controli host share --workspace main --downloads
controli host share --workspace main --long-code
controli host share --workspace main --print-only
controli host share --workspace main --audit-log off

Join a session

Browser join for tunnel sessions:

https://controli-relay.rgcsekaraa.workers.dev/join

The guest enters the 7-digit code and join password from the host and the browser opens the terminal.

CLI join:

controli join 1234567

Resolves the code and opens the local browser terminal by default on Windows, macOS, and Linux. Use CLI join for relay fallback sessions or diagnostics.

When the host enables --downloads, files placed under <workspace>/controli-drive can be downloaded from the browser terminal's Download button by entering a path relative to that folder. If the host configured a download code, the browser asks for it; blank or wrong codes fall back to host approval. Other folders are not downloadable.

Only one guest can be connected to a live session at a time. The same 7-digit code can be used again while the invite has not expired. Reconnects from the same guest keep existing approval; a different guest requires fresh host approval before input can reach the shell.

Flag	Default	Purpose
--relay-url <url>	Default relay	Relay to use when resolving a 7-digit code.
--password <value>	prompt	Join password required with the 7-digit code.
--web-terminal	automatic	Force the local browser terminal.
--console	false	Render directly in the current console for debugging.

Examples:

controli join 1234567
controli join 1234567 --password abcd-1234-wxyz
controli join 1234567 --console
controli join 1234567 --web-terminal
controli join 1234567 --relay-url wss://controli-relay.example.workers.dev

If no code is passed, Controli prompts for one:

controli join

Configure the relay

controli relay configure --url wss://controli-relay.example.workers.dev

Stores the relay URL in ~/.controli/state.json.

Check relay status

controli relay status

Prints the configured relay URL and checks the relay /health endpoint.

Deploy the bundled relay

controli relay deploy

Runs the Cloudflare Worker deploy command from a Controli source checkout.

Update Controli

controli update

Downloads the latest release asset for the current OS and CPU.

Flag	Default	Purpose
--repo <owner/name>	rgcsekaraa/controli	Download from a different GitHub repository.

Example:

controli update --repo rgcsekaraa/controli

On Windows, the updater downloads a .new.exe file because Windows locks the running executable.

Common workflows

Mac host, Windows guest with tunnel mode:

controli host tunnel --workspace main --public-url https://cli.example.com --minutes 0 --mode full

The Windows guest runs:

& "$env:LOCALAPPDATA\Controli\controli.exe" join 1234567

View-only support session:

controli host share --workspace main --mode view

Sensitive session with input approval:

controli host share --workspace main --mode approve --audit-input

Known relay issue with short code lookup:

controli host share --workspace main --long-code