pushtodisplay/cli

Command-line interface and MCP server for Push To Display — send real-time updates to display boards from your terminal or AI agents.
Get the app
Turn any screen into a live display board — get Push to Display on iOS and Android.
Install
Run directly with npx (no install needed):
Or install globally:
Requires Node.js 18+. See the PushToDisplay documentation for guides, use cases, and API details.
Quick start
Authentication
Log in with your Push To Display account — the same account you use in the mobile app.
Browser login (default)
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:
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.
auth status reports **effective** auth: an expired access token is still
reported as authenticated when a valid refresh token can renew it transparently
(a will refresh automatically note is shown instead of the raw token expiry).
It exits 0 when authenticated and 1 when not, so it is safe to gate
scripts on it.
Commands
send
Send a display update to a board.
If no -b flag is provided, the server uses your default board.
Style flags
| Flag | Values | Description |
| -------------- | ----------------------------- | ---------------- |
| -s, --size | small, medium, large | Text size |
| -w, --weight | regular, semibold, bold | Font weight |
| -c, --color | Hex color (#RRGGBB) | Text color |
| --background | Hex color (#RRGGBB) | Background color |
Panel flags
| Flag | Values | Description |
| -------------- | --------------------------------- | -------------------------- |
| -p, --panel | 1–4 | Target panel number |
| --full-panel | — | Fill the entire panel area |
| --density | compact, standard, spacious | Content spacing |
| --align-x | start, center, end | Horizontal alignment |
| --align-y | start, center, end | Vertical alignment |
Other flags
| Flag | Description |
| ---------------- | --------------------------------- |
| -b, --board | Board ID |
| --block | Styled block as JSON (repeatable) |
| --stdin | Read full JSON request from stdin |
boards
Create options:
| Flag | Description |
| ------------------- | --------------------- |
| -n, --name | Board name (required) |
| -d, --description | Board description |
| -l, --layout | Layout ID |
devices
config
JSON output
Add --json to any command for machine-readable output:
Configuration
Configuration is resolved in order: environment variables → config file → defaults.
| Env var | Description | Default |
| ----------------- | ----------------- | ------------------------------------ |
| PTD_API_URL | API endpoint | https://api.pushtodisplay.com |
| PTD_SERVICE_URL | Service endpoint | https://services.pushtodisplay.com |
| PTD_IDP_URL | Identity provider | https://idp.pushtodisplay.com |
| PTD_CONFIG_DIR | Config directory | ~/.config/pushtodisplay |