name: pushtodisplay description: "Send real-time display updates to boards, manage boards, and query devices using the PushToDisplay CLI or MCP server. Use when: the user wants to send content to a display board, create/manage boards, check device connections, or integrate PushToDisplay into a workflow. Trigger on: 'send to display', 'display board', 'pushtodisplay', 'push to display', 'board update', 'display update', 'dashboard display', 'signage', 'send update to board', 'panel update', 'multi-panel', 'display blocks'."

PushToDisplay

Send real-time content to display boards from the terminal or AI agents. Boards show styled text blocks on connected devices — phones, tablets, TVs, or any screen running the PushToDisplay app.

Two interfaces, same capabilities:

• CLI — pushtodisplay <command> in any terminal. Every agent can shell out.
• MCP server — structured tool calls for agents that support the Model Context Protocol.

1. Authentication

Authentication is required before any command works. There are two credential types.

Interactive login (full access)

Opens a browser. Works for all commands — send, boards, devices, config.

pushtodisplay auth login

For headless environments (SSH, containers, CI):

pushtodisplay auth login --device-code

Prints a URL and one-time code. Open the URL on any device, enter the code, approve.

Credentials are stored in the OS keychain (macOS Keychain, Linux libsecret, Windows Credential Manager). Falls back to ~/.config/pushtodisplay/ if the keychain is unavailable.

API key (send-only)

API keys start with pt_. Create one from the mobile app or web portal.

# Environment variable
export PTD_API_KEY=pt_your_key_here
pushtodisplay send "Hello"

# Or store in keychain
pushtodisplay auth login --api-key pt_your_key_here

API key auth only supports the send command. Use interactive login for boards, devices, and config management.

Check and clear

pushtodisplay auth status    # Show current auth state
pushtodisplay auth logout    # Remove stored credentials

MCP server auth

The MCP server inherits the CLI session. Run pushtodisplay auth login once, and the MCP server authenticates automatically.

2. Core Concepts

Layouts

Layouts are set when creating or updating a board, not per-message.

3. CLI Commands

Send updates

# Simple text (uses default board)
pushtodisplay send "Deploy succeeded"

# Target a specific board
pushtodisplay send -b <board-id> "Build passed"

# Styled text
pushtodisplay send -b <board-id> "ALERT" --size large --weight bold --color "#FF0000"

# Multiple text blocks (style flags apply to all blocks)
pushtodisplay send -b <board-id> "Build:" "passing" --color "#22C55E"

# Panel targeting
pushtodisplay send -b <board-id> --panel 2 "Right panel content"

# Full panel with layout options
pushtodisplay send -b <board-id> --panel 1 --full-panel --density compact --align-x center "Status OK"

# Per-block styling with JSON (repeatable)
pushtodisplay send -b <board-id> \
  --block '{"text": "API Health", "size": "large", "weight": "bold"}' \
  --block '{"text": "Uptime: 99.97%", "color": "#22C55E"}'

# Pipe full JSON from stdin
echo '{"boardId":"my-board","blocks":[{"text":"From pipe"}]}' | pushtodisplay send --stdin

If no -b flag is provided, the server uses the user's default board.

The three input modes — positional text arguments, --block JSON flags, and --stdin — are mutually exclusive. Do not combine them. When style flags are used with multiple positional text arguments, they apply to all generated blocks. For per-block styling, use --block JSON syntax instead.

Style flags: --size (small/medium/large), --weight (regular/semibold/bold), --color (#RRGGBB), --background (#RRGGBB)

Panel flags: --panel (1–4), --full-panel, --density (compact/standard/spacious), --align-x (start/center/end), --align-y (start/center/end)

Manage boards

pushtodisplay boards list                          # List all boards
pushtodisplay boards get <board-id>                # Get board details
pushtodisplay boards create -n "My Board"          # Create a board
pushtodisplay boards create -n "Dashboard" -l 3    # Create with 2×2 grid layout
pushtodisplay boards delete <board-id>             # Delete a board

Query devices

pushtodisplay devices list    # List active device-board streams

JSON output

Add --json to any command for machine-readable output:

pushtodisplay boards list --json
pushtodisplay send -b <board-id> "test" --json

4. MCP Tools

The MCP server exposes 8 tools. Start it with:

npx pushtodisplay mcp

pushtodisplay_send_update

Send content to a board. Returns { messageId, enqueuedAtUtc, userId }.

Each block in blocks:

pushtodisplay_list_boards

List all boards owned by the authenticated user. No parameters.

pushtodisplay_get_board

Get details of a specific board.

Returns: { boardId, name, description, layoutId, createdAt, updatedAt, isDefault }

pushtodisplay_create_board

Create a new board.

pushtodisplay_update_board

Update an existing board's name, description, or layout.

pushtodisplay_set_default_board

Set a board as the user's default. The default board is used when no board ID is specified in send_update.

pushtodisplay_delete_board

Permanently delete a board and all its data. Cannot be undone.

pushtodisplay_list_devices

List active device-board stream connections. No parameters.

Returns array of { boardId, deviceId }.

5. Styling Guide

Block-level styling

Each block in the blocks array can have its own size, weight, color, and background. These apply only to that block.

Top-level (entry-level) styling

Top-level fields apply to the entire update entry for the target panel:

• fullPanel — expand content to fill the panel area
• density — line spacing (compact = tight, standard = normal, spacious = loose)
• alignX / alignY — content alignment within the panel
• background — background color for the entire entry

Background scope

Top-level background and blocks[].background are independent. Block background does not inherit from or override the entry background.

Color format

All colors must be hex #RRGGBB. They are validated and normalized to uppercase before display.

6. Recipes

Multi-panel dashboard

Send to different panels of a 2×2 grid board:

# Panel 1 — top left
pushtodisplay send -b <board-id> --panel 1 \
  --block '{"text":"API","size":"large","weight":"bold"}' \
  --block '{"text":"200 OK","color":"#22C55E"}'

# Panel 2 — top right
pushtodisplay send -b <board-id> --panel 2 \
  --block '{"text":"Database","size":"large","weight":"bold"}' \
  --block '{"text":"Connected","color":"#22C55E"}'

# Panel 3 — bottom left
pushtodisplay send -b <board-id> --panel 3 \
  --block '{"text":"Queue","size":"large","weight":"bold"}' \
  --block '{"text":"12 pending","color":"#F59E0B"}'

# Panel 4 — bottom right
pushtodisplay send -b <board-id> --panel 4 \
  --block '{"text":"Errors","size":"large","weight":"bold"}' \
  --block '{"text":"0","color":"#22C55E"}'

Styled alert with background

pushtodisplay send -b <board-id> --full-panel --density compact \
  --align-x center --align-y center --background "#7F1D1D" \
  --block '{"text":"🚨 INCIDENT","size":"large","weight":"bold","color":"#FECACA"}' \
  --block '{"text":"Payment gateway timeout — P1","color":"#FCA5A5"}'

CI/CD pipeline status

pushtodisplay send -b <board-id> \
  --block '{"text":"deploy/prod #847","size":"large","weight":"bold"}' \
  --block '{"text":"✅ Build passed","color":"#22C55E"}' \
  --block '{"text":"✅ Tests passed (142/142)","color":"#22C55E"}' \
  --block '{"text":"🚀 Deployed to production","color":"#3B82F6"}'

MCP — create a board and send to it

Using MCP tools in sequence:

1. pushtodisplay_create_board → { name: "Deploy Status", layoutId: 2 } (Side by Side)
2. pushtodisplay_set_default_board → { boardId: "<id from step 1>" }
3. pushtodisplay_send_update → { blocks: [{ text: "Ready", size: "large" }] }

7. Errors and Limits

Error responses

Subscription tiers

Devices are unlimited across all tiers. A board is a named display destination — not a physical device.

Rate limiting is per-user, token-bucket based. Monthly message count resets on the billing cycle.

pushtodisplay

Command-line interface and MCP server for Push To Display — send real-time updates to display boards from your terminal or AI agents.

Install

Run directly with npx (no install needed):

npx pushtodisplay --help

Or install globally:

npm install -g pushtodisplay

Requires Node.js 18+.

Quick start

# Log in (opens browser)
pushtodisplay auth login

# Send an update (uses your default board)
pushtodisplay send "Hello, Display!"

# Send to a specific board
pushtodisplay send -b <board-id> "Deploy completed"

# List your boards
pushtodisplay boards list

Authentication

Log in with your Push To Display account — the same account you use in the mobile app.

Browser login (default)

pushtodisplay auth login

Opens your browser. Sign in and the CLI receives your credentials automatically.

Device code login (headless)

For machines without a browser — SSH sessions, containers, or remote servers:

pushtodisplay auth login --device-code

The CLI prints a URL and a one-time code. Open the URL on any device, enter the code, and approve the login.

Credentials are stored in your OS keychain (macOS Keychain, Linux libsecret, Windows Credential Manager). Falls back to ~/.config/pushtodisplay/ if the keychain is unavailable.

# Check auth status
pushtodisplay auth status

# Log out (clear stored credentials)
pushtodisplay auth logout

Commands

send

Send a display update to a board.

# Simple text
pushtodisplay send -b my-board-id "Deploy succeeded"

# Styled text
pushtodisplay send -b my-board-id "Status" --size large --weight bold --color "#00FF00"

# Multiple blocks
pushtodisplay send -b my-board-id "Build:" "passing" --color "#22C55E"

# Panel targeting with layout options
pushtodisplay send -b my-board-id --panel 2 "Right panel content"
pushtodisplay send -b my-board-id --panel 1 --full-panel --density compact --align-x center "Alert"

# Per-block styling with JSON (repeatable)
pushtodisplay send -b my-board-id \
  --block '{"text": "API Health", "size": "large", "weight": "bold"}' \
  --block '{"text": "Uptime: 99.97%", "color": "#22C55E"}'

# Pipe a full JSON payload from stdin
echo '{"boardId":"my-board-id","blocks":[{"text":"From pipe"}]}' | pushtodisplay send --stdin

If no -b flag is provided, the server uses your default board.

Style flags

Panel flags

Other flags

boards

pushtodisplay boards list              # List all boards
pushtodisplay boards get <id>          # Get board details
pushtodisplay boards create -n "Name"  # Create a board
pushtodisplay boards create -n "Dash" -l 4  # Create with a layout
pushtodisplay boards delete <id>       # Delete a board

Create options:

devices

pushtodisplay devices list    # List active device-board streams

config

pushtodisplay config              # Show current configuration
pushtodisplay config show         # Same as above

JSON output

Add --json to any command for machine-readable output:

pushtodisplay boards list --json
pushtodisplay send -b my-board "test" --json

Configuration

Configuration is resolved in order: environment variables → config file → defaults.

MCP server

The CLI includes a built-in Model Context Protocol server, giving AI agents (Claude, Cursor, VS Code Copilot, and others) direct access to your display boards.

The MCP server inherits your CLI session — if you've run pushtodisplay auth login, it authenticates automatically.

Setup

Claude Code

claude mcp add pushtodisplay -- npx pushtodisplay mcp

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "pushtodisplay": {
      "command": "npx",
      "args": ["pushtodisplay", "mcp"]
    }
  }
}

Cursor

Open Settings → MCP Servers → Add Server, or edit .cursor/mcp.json:

{
  "mcpServers": {
    "pushtodisplay": {
      "command": "npx",
      "args": ["pushtodisplay", "mcp"]
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json:

{
  "servers": {
    "pushtodisplay": {
      "command": "npx",
      "args": ["pushtodisplay", "mcp"]
    }
  }
}

Other MCP clients

Any MCP client that supports stdio transport can use Push To Display. The server command is:

npx pushtodisplay mcp

Available MCP tools

Commands at a glance

API key authentication

For CI/CD pipelines and scripts where interactive login isn't available, you can authenticate with an API key. Create one from the mobile app or the web portal. API keys start with pt_.

# Via environment variable
export PTD_API_KEY=pt_your_key_here
pushtodisplay send "From CI"

# Or store in keychain
pushtodisplay auth login --api-key pt_your_key_here

Note: API key auth only supports the send command. Use auth login for full access to boards, devices, and config management.

Screenshots

4-panel layout — regional status at a glance

Multi-panel with CI/CD pipeline and infrastructure logs

Incident timeline with color-coded severity

License

MIT