CLI reference

porthole host      Start a terminal sharing session
porthole join      Join a session from your terminal, without a browser
porthole replay    Play back a recorded session
porthole template  Manage reusable session configurations
porthole probe     Collect read-only diagnostics into a shareable report
porthole update    Update porthole to the latest release
porthole version   Print version and platform information

Global flags

Available on every command.

Flag	Default	Description
`--server <url>`	build-time default	Signaling server URL. Also `$PORTHOLE_SERVER`.
`--log-level <level>`	`info`	`debug`, `info`, `warn`, or `error`. Also `$PORTHOLE_LOG_LEVEL`.

porthole host

Spawns a PTY shell and shares it with a remote viewer over a direct P2P WebRTC connection. No terminal data passes through the signaling server.

porthole host [flags]

Session

Flag	Default	Description
`--shell <name>`	`$SHELL`, else `bash`	Shell to spawn. Also `$PORTHOLE_SHELL`.
`--expire <duration>`	`0` (never)	Auto-expire after a duration, e.g. `30m`.
`--once`	`false`	Close the session after the first viewer disconnects.
`--no-input`	`false`	Do not read this terminal's keyboard, and do not mirror the shared shell here.
`--allow-root`	`false`	Share even though the agent is running as root. Also `$PORTHOLE_ALLOW_ROOT`.

Access control

Flag	Default	Description
`--readonly`	`false`	Viewers cannot type. Enforced by the agent, not the browser.
`--password <value>`	none	Require viewers to supply this password. Prefer `$PORTHOLE_PASSWORD`.
`--allow <name>`	none	Invite a named person; each gets a personal join secret. Repeatable.
`--auto-approve`	`false`	With `--readonly`, grant write access as soon as a viewer asks.
`--no-requests`	`false`	With `--readonly`, refuse viewer requests for write access.
`--request-duration <duration>`	`0` (until session end)	With `--auto-approve`, how long a grant lasts.

See Read-only, Write access, Passwords, and Named invites.

Credential masking

Flag	Default	Description
`--mask`	`false`	Redact credentials from output before it reaches the viewer. Best-effort.
`--mask-pattern <regex>`	none	Additional regex to redact. Repeatable; implies `--mask`.
`--mask-no-auto`	`false`	With `--mask`, use only `--mask-pattern` and disable the built-in rules.

See Credential masking.

Recording

Flag	Default	Description
`--record`	`false`	Record the session to an asciicast file.
`--record-output <path>`	auto-generated	Where to write it. Also `$PORTHOLE_RECORD_OUTPUT`.
`--title <text>`	none	Title stored in the file header. Implies `--record`. Also `$PORTHOLE_TITLE`.

See Recording and replay.

Session context

Flag	Default	Description
`--ctx <file>`	none	Attach session context from a YAML file.
`--ctx-title <text>`	none	Context title shown to the viewer.
`--ctx-note <text>`	none	Context note shown to the viewer.
`--ctx-env <name>`	none	Environment badge, e.g. `production`.
`--ctx-severity <level>`	none	Severity badge, e.g. `high`.
`--ctx-link <label=url>`	none	Context link. Repeatable.

See Session context.

Templates and output

Flag	Default	Description
`--template <name>`	none	Apply a saved session template.
`--save-as <name>`	none	Save this invocation's flags as a template.
`--no-qr`	`false`	Skip the QR code.
`--no-link`	`false`	Show the session code only, skip the link.

Host controls

While hosting, Ctrl+] is the local command prefix.

Keys	Does
`Ctrl`+`]` `q` or `.`	End the session
`Ctrl`+`]` `w`	Let the viewer type
`Ctrl`+`]` `r`	Stop the viewer typing, now
`Ctrl`+`]` `?`	List the commands
`Ctrl`+`]` `Ctrl`+`]`	Send a literal `Ctrl`+`]` to the shell

Ctrl+C goes to the shared shell, not to Porthole — raw mode clears ISIG, as over SSH. Use Ctrl+] q to end a session. See Host controls.

porthole join

Connects to a session and renders it in this terminal — the browser viewer without the browser. Accepts a bare code, a link, or an invite link.

porthole join <token-or-link> [flags]

Flag	Default	Description
`--write`	`false`	Ask the host for write access. Does not grant it.
`--readonly`	`true`	Watch without requesting input access. The default.
`--name <text>`	none	Display name shown to the host.
`--record <file>`	none	Record what you are shown to this asciicast file.
`--cols <n>`	auto	Pin the terminal width reported to the host.
`--rows <n>`	auto	Pin the terminal height reported to the host.

Press Ctrl+] to disconnect. See Watching in a terminal.

porthole replay

Plays back an asciicast recording. Forward-only.

porthole replay <file> [flags]

Flag	Default	Description
`--speed <n>`	`1`	Playback speed multiplier, e.g. `2` for double speed.
`--idle-limit <duration>`	`2s`	Cap on any single pause. `0` replays real timings.
`--from <duration>`	`0`	Skip ahead, replaying earlier output instantly.
`--info`	`false`	Print recording metadata and exit.

porthole template

Manages reusable session configurations, stored as one YAML file per template.

porthole template list
porthole template show <name>
porthole template delete <name>
porthole template path

See Session templates.

porthole probe

Collects read-only diagnostics into a structured report. Never invokes a shell; only allowlisted binaries may run.

porthole probe [flags]

Flag	Default	Description
`--profile <name>`	`default`	One of `default`, `web-server`, `nodejs`, `python`, `database`, `kubernetes`, `docker`.
`--dry-run`	`false`	List the commands that would run, without executing them.
`--output <path>`, `-o`	none	Write the report to a file.
`--include <cmd>`	none	Additional command to run. Repeatable.
`--json`	`false`	Print the full report as JSON to stdout.
`--no-mask`	`false`	Do not redact credentials from the captured output.

See Diagnostics.

porthole update

Downloads and installs the latest release. The new binary is verified against the release manifest's SHA-256 digest before it replaces the running executable.

porthole update [flags]

Flag	Default	Description
`--check`	`false`	Report whether a newer version exists, without installing.
`--force`	`false`	Reinstall even if already up to date, or installed via a package manager.

porthole version

porthole version

Prints the version and platform, e.g. porthole v0.1.0 (linux/amd64).

Environment variables

Full list, including the configuration directory, in Environment and configuration.

On this page