Purpose
cli is the command-line interface and MCP server for Push To Display, used to push real-time updates generated by the terminal or AI agents to display boards. Together with the Push To Display app on iOS and Android, it can turn any screen into a real-time display board.
Main capabilities
- Send display updates to a board. You can specify the board with -b; if not specified, the default board is used.
- Supports creation options, allowing you to generate multi-panel layouts, such as an at-a-glance regional status, a multi-panel view with CI/CD pipelines and infrastructure logs, a color-coded incident timeline, and more.
- Add --json to any command to get machine-readable output.
- Built-in Model Context Protocol (MCP) server, letting AI clients (Claude, Cursor, VS Code Copilot, etc.) directly access boards. Any MCP client that supports stdio transport can use it; the server command is the corresponding entry point of the command line.
- Provides an overview of available MCP tools and commands.
Usage
Run directly (no installation required): use npx. Global installation: use the corresponding npm installation command. Requires Node.js 18+.
Login: use a Push To Display account (the same account as the mobile app).
- Browser login (default): opens the browser; after logging in, the CLI automatically receives the credentials.
- Device code login (headless): suitable for machines without a browser, such as SSH sessions, containers, or remote servers; 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 the operating system keychain (macOS Keychain, Linux libsecret, Windows Credential Manager). If the keychain is unavailable, it falls back to ~/.config/pushtodisplay/.
auth status reports the effective authentication status: when a valid refresh token can transparently renew it, it will still report as authenticated even if the access token has expired, and will display "will refresh automatically" instead of the raw token expiration time. The exit code is 0 when authenticated and 1 when not authenticated, so it can be used for script gating.
The MCP server inherits the CLI session: if pushtodisplay auth login has already been run, it automatically authenticates. Configuration resolution order: environment variables → configuration file → default values.
MCP client configuration examples:
- Claude: add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).
- Cursor: open Settings → MCP Servers → Add Server, or edit .cursor/mcp.json.
- VS Code: add to .vscode/mcp.json.
API key authentication: suitable for CI/CD pipelines and scripts that cannot log in interactively. Can be created from the mobile app or web portal; keys start with pt_. Note: API key authentication only supports the send command; full access to board, device, and configuration management requires auth login.
Use cases
- Push real-time status to a display board in the terminal or from an AI agent.
- Use multi-panel boards to display regional status, CI/CD pipelines, infrastructure logs, and incident timelines.
- Send updates via API key in CI/CD pipelines or scripts.
- Let AI clients such as Claude, Cursor, and VS Code Copilot directly access boards via MCP.
Limitations
- Requires Node.js 18+.
- API key authentication only supports the send command and does not support full board, device, and configuration management.
- If the system keychain is unavailable, credentials fall back to being stored in ~/.config/pushtodisplay/.
- For more usage guides, use cases, and API details, see the PushToDisplay documentation (specific links were not provided in the source material).
