# shellshare

> Live terminal broadcasting: share a terminal session via a web link with a
> single command. No signup, no configuration. Viewers watch read-only in
> their browser. Free and open source (Apache-2.0).

Canonical site: https://shellshare.net
Source code: https://github.com/vitorbaptista/shellshare

## Quick start

Run one of these in a terminal:

    npx -y shellshare
    curl -sLo shellshare https://get.shellshare.net/ && chmod +x shellshare && ./shellshare

It prints `Sharing terminal in https://shellshare.net/r/<room>` — anyone who
opens that link watches the terminal live. Exit the shell (Ctrl+D) to stop.
Binaries: Linux x64, macOS x64/arm64, Windows x64, via
https://get.shellshare.net/?os=linux|mac|mac-arm|windows (auto-detected
without the parameter).

## For scripts and AI agents

Add `--json` for a machine-readable contract on stdout (newline-delimited
JSON events):

- First line, before any terminal output:
  {"event":"sharing","room":"<room>","server":"https://shellshare.net","url":"https://shellshare.net/r/<room>"}
- Last line: {"event":"end","exit_code":0}
- Errors: `ERROR: ...` on stderr, non-zero exit code.

Recipes:

    # Share one command live; exits with the command's exit code
    # (signal-killed commands report exit code 1)
    shellshare exec --json -- npm test

    # Stream a log or any pipe (reads stdin until EOF)
    tail -f build.log | shellshare --stdin --json

    # Stable room name + password (same link every run)
    shellshare exec --json -r my-room -W my-password -- make deploy

## Key facts

- One-way: viewers can never send input to the broadcasting terminal.
- Share links are unguessable (18 random alphanumerics) but public: anyone
  with the link can watch. Don't broadcast secrets.
- Live-only: broadcasts are not recorded. Rooms are deleted when the
  broadcast ends or after a period of inactivity.
- Late joiners see recent history, not a blank page.
- Network drops are handled: output is buffered and replayed on reconnect.
- `--theme` sets viewer colors (asciinema themes: dracula, gruvbox-dark,
  monokai, nord, seti, solarized-dark, solarized-light, tango, asciinema).
- Self-hosting: the same binary contains the server. `shellshare server`
  hosts it; `shellshare serve` shares through an embedded local server so
  nothing leaves the machine; `shellshare serve --tunnel` adds a public
  https://*.trycloudflare.com link via cloudflared.

## Docs

- Agent/scripting guide: https://github.com/vitorbaptista/shellshare/blob/main/AGENTS.md
- README: https://github.com/vitorbaptista/shellshare/blob/main/README.md
- npm package: https://www.npmjs.com/package/shellshare