About shout

Broadcast your terminal to anyone with a browser. Install the CLI, run shout, share the link.

Quick Start

1. Install the CLI

shell

npm install -g shout-run

2. Log in with GitHub

shell

shout login

3. Start broadcasting

shell

shout

Options: --title "My session" --visibility public --tags rust,cli

Pipe mode works too:

shell

./deploy.sh | shout --title "Deploy log"

Features

Real-time streaming

Terminal output reaches viewers over WebSocket with no perceptible delay.

Late-joiner catch-up

Viewers who arrive mid-session get a buffer of recent output so they're not lost.

Session replay

Ended sessions become recordings you can scrub through like a video.

Export as .cast

Download any session as an asciicast v2 file. Compatible with asciinema-player.

Embeddable player

Drop an iframe on any page. oEmbed support for platforms that auto-embed.

Privacy controls

Public or private. Private sessions leave no replay data.

SDKs

Broadcast from your own code instead of the CLI. Available for TypeScript and Python.

TypeScript

shell

npm install shout-run-sdk

typescript

import { ShoutSession } from 'shout-run-sdk';

const session = new ShoutSession({
  apiKey: 'shout_sk_...',
});

const info = await session.start();
session.write('Hello, world!\r\n');
await session.end();

Python

shell

pip install shout-run-sdk

python

from shout_sdk import ShoutSession

session = ShoutSession(api_key='shout_sk_...')

info = session.start()
session.write('Hello, world!\r\n')
session.end()

Both SDKs expose the same core methods: start(), write(), resize(), and end().

MCP Servers

Let AI agents broadcast terminal sessions through the Model Context Protocol. Add to your Claude Desktop config:

TypeScript

json

{
  "mcpServers": {
    "shout": {
      "command": "npx",
      "args": ["shout-run-mcp"],
      "env": {
        "SHOUT_API_KEY": "shout_sk_..."
      }
    }
  }
}

Python

json

{
  "mcpServers": {
    "shout": {
      "command": "shout-mcp",
      "env": {
        "SHOUT_API_KEY": "shout_sk_..."
      }
    }
  }
}

Available tools

Tool	Description
shout_start_broadcast	Start a broadcast session, returns the viewer URL
shout_write	Send terminal output to viewers (supports ANSI escape codes)
shout_end_broadcast	End the current session
shout_broadcast_status	Check session status and current viewer count
shout_delete_session	Delete a session that has ended
shout_search_sessions	Search sessions by title, tags, or status
shout_read_session	Read the plain-text transcript of a session

API Keys

SDKs and MCP servers authenticate with API keys. Create one from the CLI:

shell

shout api-key create "My Agent"

Manage keys with shout api-key list and shout api-key revoke <id>.

Embedding

Embed a session replay on any page with an iframe:

html

<iframe
  src="https://shout.run/embed/SESSION_ID"
  width="800"
  height="500"
  frameborder="0"
  allowfullscreen
></iframe>

URL parameters

Param	Default	Description
autoplay	1	Set to 0 to start paused
speed	1	Playback speed multiplier (e.g. 2 for double speed)
t	0	Start time in seconds
controls	1	Set to 0 to hide the player bar

Platforms that support oEmbed will auto-embed the player when you paste a shout.run link.

Open Source

Everything is MIT-licensed — the CLI, the worker, the web app, the SDKs, all of it. Source and contributions: github.com/pavanmadiraju91/shout-run.

Frequently Asked Questions

What is shout?

shout is an open-source terminal broadcasting tool. It lets developers stream their terminal output in real time to anyone with a browser, record sessions for replay, and embed recordings on any web page.

How does shout work?

The CLI captures your terminal output via a pseudo-terminal (PTY), encodes it into a compact binary WebSocket protocol, and streams it through a Cloudflare Worker to viewers running xterm.js in the browser. Late joiners receive a terminal state snapshot so they see the current screen immediately.

Is shout free?

Yes. shout is completely free and open-source under the MIT license. There are no paid tiers, usage fees, or premium features.

What terminals are supported?

shout works with any terminal emulator on Linux, macOS, and Windows. It captures output from your default shell (bash, zsh, fish, PowerShell, etc.) via PTY.

How long can a session last?

Sessions can last up to 4 hours. Output is rate-limited to 100 KB/s to ensure a smooth experience for viewers. There is a daily cap of 50 sessions per user.

Is my data private?

You control session visibility: public or private. Private sessions leave no replay data on the server.

Can AI agents use shout?

Yes. TypeScript and Python SDKs let you broadcast programmatically, and MCP servers (compatible with Claude, Cursor, and other MCP clients) expose tools like shout_start_broadcast, shout_write, shout_search_sessions, and shout_read_session.

How do I embed a session?

Use an iframe pointing to https://shout.run/embed/SESSION_ID. URL parameters control autoplay, playback speed, start time, and whether the player bar is visible. Platforms that support oEmbed will auto-embed the player when you paste a shout.run link.