{
  "markdown": "# pushtodisplay\n\nCommand-line interface and [MCP server](https://modelcontextprotocol.io) for [Push To Display](https://pushtodisplay.com) — send real-time updates to display boards from your terminal or AI agents.\n\n![Push to Display — 4-panel regional status board](https://raw.githubusercontent.com/pushtodisplay/cli/main/assets/display-4-panel-status.png)\n\n## Install\n\nRun directly with `npx` (no install needed):\n\n```bash\nnpx pushtodisplay --help\n```\n\nOr install globally:\n\n```bash\nnpm install -g pushtodisplay\n```\n\nRequires Node.js 18+. See the [PushToDisplay documentation](https://pushtodisplay.com/docs) for guides, use cases, and API details.\n\n## Quick start\n\n```bash\n# Log in (opens browser)\npushtodisplay auth login\n\n# Send an update (uses your default board)\npushtodisplay send \"Hello, Display!\"\n\n# Send to a specific board\npushtodisplay send -b <board-id> \"Deploy completed\"\n\n# List your boards\npushtodisplay boards list\n```\n\n## Authentication\n\nLog in with your Push To Display account — the same account you use in the mobile app.\n\n### Browser login (default)\n\n```bash\npushtodisplay auth login\n```\n\nOpens your browser. Sign in and the CLI receives your credentials automatically.\n\n### Device code login (headless)\n\nFor machines without a browser — SSH sessions, containers, or remote servers:\n\n```bash\npushtodisplay auth login --device-code\n```\n\nThe CLI prints a URL and a one-time code. Open the URL on any device, enter the code, and approve the login.\n\nCredentials are stored in your OS keychain (macOS Keychain, Linux libsecret, Windows Credential Manager). Falls back to `~/.config/pushtodisplay/` if the keychain is unavailable.\n\n```bash\n# Check auth status\npushtodisplay auth status\n\n# Machine-readable status for scripts/agents (exit 0 = authenticated)\npushtodisplay auth status --json\n\n# Log out (clear stored credentials)\npushtodisplay auth logout\n```\n\n`auth status` reports **effective** auth: an expired access token is still\nreported as authenticated when a valid refresh token can renew it transparently\n(a `will refresh automatically` note is shown instead of the raw token expiry).\nIt exits `0` when authenticated and `1` when not, so it is safe to gate\nscripts on it.\n\n```json\n{\n  \"authenticated\": true,\n  \"method\": \"oauth\",\n  \"accessTokenExpired\": true,\n  \"canRefresh\": true,\n  \"sessionExpiresAt\": \"2026-06-01T00:00:00.000Z\"\n}\n```\n\n## Commands\n\n### `send`\n\nSend a display update to a board.\n\n```bash\n# Simple text\npushtodisplay send -b my-board-id \"Deploy succeeded\"\n\n# Styled text\npushtodisplay send -b my-board-id \"Status\" --size large --weight bold --color \"#00FF00\"\n\n# Multiple blocks\npushtodisplay send -b my-board-id \"Build:\" \"passing\" --color \"#22C55E\"\n\n# Panel targeting with layout options\npushtodisplay send -b my-board-id --panel 2 \"Right panel content\"\npushtodisplay send -b my-board-id --panel 1 --full-panel --density compact --align-x center \"Alert\"\n\n# Per-block styling with JSON (repeatable)\npushtodisplay send -b my-board-id \\\n  --block '{\"text\": \"API Health\", \"size\": \"large\", \"weight\": \"bold\"}' \\\n  --block '{\"text\": \"Uptime: 99.97%\", \"color\": \"#22C55E\"}'\n\n# Pipe a full JSON payload from stdin\necho '{\"boardId\":\"my-board-id\",\"blocks\":[{\"text\":\"From pipe\"}]}' | pushtodisplay send --stdin\n```\n\nIf no `-b` flag is provided, the server uses your default board.\n\n#### Style flags\n\n| Flag           | Values                        | Description      |\n| -------------- | ----------------------------- | ---------------- |\n| `-s, --size`   | `small`, `medium`, `large`    | Text size        |\n| `-w, --weight` | `regular`, `semibold`, `bold` | Font weight      |\n| `-c, --color`  | Hex color (`#RRGGBB`)         | Text color       |\n| `--background` | Hex color (`#RRGGBB`)         | Background color |\n\n#### Panel flags\n\n| Flag           | Values                            | Description                |\n| -------------- | --------------------------------- | -------------------------- |\n| `-p, --panel`  | `1`–`4`                           | Target panel number        |\n| `--full-panel` | —                                 | Fill the entire panel area |\n| `--density`    | `compact`, `standard`, `spacious` | Content spacing            |\n| `--align-x`    | `start`, `center`, `end`          | Horizontal alignment       |\n| `--align-y`    | `start`, `center`, `end`          | Vertical alignment         |\n\n#### Other flags\n\n| Flag             | Description                       |\n| ---------------- | --------------------------------- |\n| `-b, --board`    | Board ID                          |\n| `--block <json>` | Styled block as JSON (repeatable) |\n| `--stdin`        | Read full JSON request from stdin |\n\n### `boards`\n\n```bash\npushtodisplay boards list              # List all boards\npushtodisplay boards get <id>          # Get board details\npushtodisplay boards create -n \"Name\"  # Create a board\npushtodisplay boards create -n \"Dash\" -l 4  # Create with a layout\npushtodisplay boards delete <id>       # Delete a board\n```\n\nCreate options:\n\n| Flag                | Description           |\n| ------------------- | --------------------- |\n| `-n, --name`        | Board name (required) |\n| `-d, --description` | Board description     |\n| `-l, --layout`      | Layout ID             |\n\n### `devices`\n\n```bash\npushtodisplay devices list    # List active device-board streams\n```\n\n### `config`\n\n```bash\npushtodisplay config              # Show current configuration\npushtodisplay config show         # Same as above\n```\n\n## JSON output\n\nAdd `--json` to any command for machine-readable output:\n\n```bash\npushtodisplay boards list --json\npushtodisplay send -b my-board \"test\" --json\n```\n\n## Configuration\n\nConfiguration is resolved in order: environment variables → config file → defaults.\n\n| Env var           | Description       | Default                              |\n| ----------------- | ----------------- | ------------------------------------ |\n| `PTD_API_URL`     | API endpoint      | `https://api.pushtodisplay.com`      |\n| `PTD_SERVICE_URL` | Service endpoint  | `https://services.pushtodisplay.com` |\n| `PTD_IDP_URL`     | Identity provider | `https://idp.pushtodisplay.com`      |\n| `PTD_CONFIG_DIR`  | Config directory  | `~/.config/pushtodisplay`            |\n\n## MCP server\n\nThe CLI includes a built-in [Model Context Protocol](https://modelcontextprotocol.io) server, giving AI agents (Claude, Cursor, VS Code Copilot, and others) direct access to your display boards.\n\nThe MCP server inherits your CLI session — if you've run `pushtodisplay auth login`, it authenticates automatically.\n\n### Setup\n\n#### Claude Code\n\n```bash\nclaude mcp add pushtodisplay -- npx pushtodisplay mcp\n```\n\n#### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"pushtodisplay\": {\n      \"command\": \"npx\",\n      \"args\": [\"pushtodisplay\", \"mcp\"]\n    }\n  }\n}\n```\n\n#### Cursor\n\nOpen Settings → MCP Servers → Add Server, or edit `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"pushtodisplay\": {\n      \"command\": \"npx\",\n      \"args\": [\"pushtodisplay\", \"mcp\"]\n    }\n  }\n}\n```\n\n#### VS Code (GitHub Copilot)\n\nAdd to `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"pushtodisplay\": {\n      \"command\": \"npx\",\n      \"args\": [\"pushtodisplay\", \"mcp\"]\n    }\n  }\n}\n```\n\n#### Other MCP clients\n\nAny MCP client that supports stdio transport can use Push To Display. The server command is:\n\n```bash\nnpx pushtodisplay mcp\n```\n\n### Available MCP tools\n\n| Tool                              | Description                                   |\n| --------------------------------- | --------------------------------------------- |\n| `pushtodisplay_send_update`       | Send content to a board                       |\n| `pushtodisplay_list_boards`       | List all boards                               |\n| `pushtodisplay_get_board`         | Get details of a board                        |\n| `pushtodisplay_create_board`      | Create a new board                            |\n| `pushtodisplay_update_board`      | Update a board's name, description, or layout |\n| `pushtodisplay_set_default_board` | Set a board as your default                   |\n| `pushtodisplay_delete_board`      | Delete a board permanently                    |\n| `pushtodisplay_list_devices`      | List active device connections                |\n\n## Commands at a glance\n\n| Command              | Description                     |\n| -------------------- | ------------------------------- |\n| `auth login`         | Log in (browser or device code) |\n| `auth logout`        | Remove stored credentials       |\n| `auth status`        | Show current auth status        |\n| `send [text...]`     | Send a display update           |\n| `boards list`        | List your boards                |\n| `boards get <id>`    | Get board details               |\n| `boards create`      | Create a new board              |\n| `boards delete <id>` | Delete a board                  |\n| `devices list`       | List active device connections  |\n| `config`             | Show current configuration      |\n| `mcp`                | Start the MCP server            |\n\n## API key authentication\n\nFor 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](https://pushtodisplay.com/admin). API keys start with `pt_`.\n\n```bash\n# Via environment variable\nexport PTD_API_KEY=pt_your_key_here\npushtodisplay send \"From CI\"\n\n# Or store in keychain\npushtodisplay auth login --api-key pt_your_key_here\n```\n\n> **Note:** API key auth only supports the `send` command. Use `auth login` for full access to boards, devices, and config management.\n\n## Screenshots\n\n![4-panel layout — regional status board](https://raw.githubusercontent.com/pushtodisplay/cli/main/assets/display-4-panel-status.png)\n_4-panel layout — regional status at a glance_\n\n![2-panel layout with CI/CD logs](https://raw.githubusercontent.com/pushtodisplay/cli/main/assets/display-2-panel-logs.png)\n_Multi-panel with CI/CD pipeline and infrastructure logs_\n\n![Incident timeline display](https://raw.githubusercontent.com/pushtodisplay/cli/main/assets/display-incident-timeline.png)\n_Incident timeline with color-coded severity_\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 10330,
  "sha": "7b29d2aa9740db085fc13712ae72941bae946ab8b218a6e9cc03adc532d525a8",
  "repo_slug": "pushtodisplay/cli",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_pushtodisplay_cli_48d754d6/readme"
}