Cli

📺 Push To Display CLI

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

🚀 Quick Start

📦 Installation

Run directly with npx (no install needed):

npx pushtodisplay --help

Or install globally:

npm install -g pushtodisplay

📋 Requirements

• Node.js 18+
• See the PushToDisplay documentation for guides, use cases, and API details.

⚡ First Commands

# 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.

💾 Credential Storage

Credentials are stored in your OS keychain:

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

💡 Tip: 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.

💡 Automatic authentication: 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

⚠️ Important 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