Options reference

This page is the canonical reference for all xport flags, verified against the CLI itself (xport --help and each subcommand’s --help). Mode pages like xport <port> link back here instead of repeating the tables.

Persistent flags

These flags work in every share mode (xport <port>, xport <file>, xport <folder>, echo … | xport, xport receive) — they are defined once on the root command and inherited by all subcommands.

Flag	Env var	Config key	Default	Description
--name	XPORT_TUNNEL_NAME	tunnel.name	random ID	Custom name for the public URL, e.g. demo → demo.xport.sh. On the hosted relay (oauth mode) custom names require an account — anonymous free-tier clients always get random names
--domain	XPORT_TUNNEL_DOMAIN	tunnel.domain	(none)	Serve the share on a verified custom domain instead of *.xport.sh (flag for --domain, requires account + DNS setup — see BYOD)
--policy-file	XPORT_TUNNEL_POLICY_FILE	tunnel.policy_file	(none)	Attach a traffic policy file (CEL rules + actions) enforced by the relay on every public request
--expires	XPORT_TUNNEL_EXPIRES	tunnel.expires	relay default (tier cap: 4 h anonymous, 24 h free, 30 d pro/team)	Session lifetime, e.g. 30m, 2h
--password	XPORT_TUNNEL_PASSWORD	tunnel.password	(none)	Protect the public URL with HTTP Basic auth (username ignored)
--qr	XPORT_TUNNEL_QR	tunnel.qr	false	Print a terminal QR code for the public URL
--copy	XPORT_TUNNEL_COPY	tunnel.copy	false	Copy the public URL to the system clipboard (silently skipped in --json mode)
--detach	—	—	false	Start the share in the background and return immediately — flag-only, no env var or config key
--secret	—	—	false	Share piped stdin as a secret page instead of a plain paste
--once	—	—	false	Delete the secret from memory after it is opened once (implies --secret)
--burn	—	—	false	Delete the content after the first download/view (implies --secret for stdin)
--json	XPORT_JSON=1	—	false	Print exactly one machine-readable JSON envelope — flag or env, no config key

Two more built-ins exist on every command: -h, --help for help and -v, --version for the version string (e.g. xport version 0.1.0).

Precedence

Session settings resolve as: CLI flag > config file (tunnel.*) > relay default. Environment variables bind to config keys (XPORT_TUNNEL_PASSWORD → tunnel.password), so they sit at the same level as the config file. --json and --detach have no config key — --json additionally honours the XPORT_JSON env var, --detach is flag-only.

Per-command flags and arguments

Only flags specific to each command are listed — all persistent flags above apply on top.

Command	Arguments	Specific flags
xport <port>	Port number to expose, e.g. 3000	—
xport tcp <host:port|port>	Raw TCP service (database, Kafka, gRPC, SSH). A bare port means localhost	--password/--policy-file/--domain rejected (HTTP-only) — xport tcp
xport <file> / xport <folder>	Path; the CLI dispatches on file vs. directory automatically	—
xport share <path>	Explicit share of a file or folder (same behaviour as the dispatch above)	—
xport receive	Optional target directory (default: current directory, created if missing)	--message, --accept, --maxfilesize — file requests
xport list	—	— (--json returns the share array)
xport stop	Share ID, e.g. k7fz2	--group <name> stops a whole project profile at once
xport start	One or more endpoint names (config.yaml endpoints:)	--all starts every defined endpoint — named endpoints
xport update	—	--check — only check, never download
xport info	—	—

Receive-local flags

These only exist on xport receive (not persistent; other modes do not accept them). Precedence: CLI flag > config file (receive.*) > unset.

Flag	Env var	Config key	Default	Description
--message	XPORT_RECEIVE_MESSAGE	receive.message	(none)	Request text shown prominently on the upload page (HTML-escaped)
--accept	XPORT_RECEIVE_ACCEPT	receive.accept	(none)	Comma-separated extensions/MIME types for the file input’s accept attribute (client-side convenience)
--maxfilesize	XPORT_RECEIVE_MAX_FILESIZE	receive.max_filesize	(unlimited)	Hard per-file upload limit, e.g. 10MB; oversized files are rejected with 413

Sizes are plain bytes (1048576) or a B/KB/MB/GB suffix (case-insensitive, decimal 1000-based: 1 KB = 1000 bytes).

--json output

--json (or XPORT_JSON=1) prints exactly one JSON object on stdout — no banner, no colors, no prompts — and errors use the same channel with a non-zero exit code:

{"ok":true,"mode":"file","id":"k7fz2","url":"https://k7fz2.xport.sh/report.pdf","expires":"2026-10-24T12:00:00Z","password":false,"local_path":"./report.pdf"}

{"ok":false,"error":"no such share: nonexistent"}

• A running share reports ok/mode/id/url/expires/password, plus port (tunnel) or local_path (file/folder) where applicable.
• xport list --json returns {"ok":true,"shares":[…]} with an alive boolean per entry.
• xport stop --json returns ok/id/stopped/signaled.
• Passwords never appear in any JSON output.

--detach notes

• The parent process starts a detached copy of itself, waits for the share to appear in the share registry (up to 10 s), then prints the URL, ID, expiry, and log file path and returns.
• Combined with --json, the envelope carries pid and log (the log file path) so scripts can manage the background process.
• The detached child always logs human-readable output to <state-dir>/logs/<id>.log (~/.local/state/xport/logs/, honouring XDG_STATE_HOME) — so --qr with --detach draws the QR code into the log file, not your terminal.
• Stop detached shares with xport stop <id>.

Config file quick reference

Full reference: Configuration file. Keys beyond the tunnel.* defaults: relay.url, relay.region, relay.token, update.feed_url, logging.level.

macOS path

On macOS the config file lives at ~/Library/Application Support/xport/config.yaml — not ~/.config/xport/config.yaml (which is the Linux path). xport info prints the exact path it uses.