cli

pushtodisplay

Push To Display 的命令行界面和 MCP 服务，可从终端或 AI Agent 向显示屏实时发送更新。

获取应用

将任意屏幕变成实时显示屏——在 iOS 和 Android 上获取 Push to Display。

安装

使用 npx 直接运行（无需安装）：

npx pushtodisplay --help

或进行全局安装：

npm install -g pushtodisplay

需要 Node.js 18+。有关指南、用例和 API 详情，请参阅 PushToDisplay 文档。

快速入门

# 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

身份验证

使用你的 Push To Display 帐户登录——与移动应用中使用的帐户相同。

浏览器登录（默认）

pushtodisplay auth login

此操作会打开浏览器。登录后，CLI 会自动获取你的凭据。

设备代码登录（无头模式）

适用于没有浏览器的机器，例如 SSH 会话、容器或远程服务：

pushtodisplay auth login --device-code

CLI 会输出一个 URL 和一次性代码。在任意设备上打开该 URL，输入代码并批准登录。

凭据会存储在操作系统钥匙串中（macOS Keychain、Linux libsecret、Windows Credential Manager）。如果钥匙串不可用，则会回退到 ~/.config/pushtodisplay/。

# Check auth status
pushtodisplay auth status

# Machine-readable status for scripts/agents (exit 0 = authenticated)
pushtodisplay auth status --json

# Log out (clear stored credentials)
pushtodisplay auth logout

auth status 会报告有效身份验证状态：即使访问令牌已过期，只要有效的刷新令牌可以自动续期，仍会报告为已验证（此时会显示 will refresh automatically 提示，而非原始令牌过期信息）。 已验证时退出码为 0，未验证时为 1，因此可安全地用它控制脚本是否运行。

{
  "authenticated": true,
  "method": "oauth",
  "accessTokenExpired": true,
  "canRefresh": true,
  "sessionExpiresAt": "2026-06-01T00:00:00.000Z"
}

命令

send

向显示屏发送更新。

# 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

如果未提供 -b 标志，服务端会使用你的默认显示屏。

样式标志

标志	可选值	说明
-s, --size	small、medium、large	文本大小
-w, --weight	regular、semibold、bold	字体粗细
-c, --color	十六进制颜色（#RRGGBB）	文本颜色
--background	十六进制颜色（#RRGGBB）	背景颜色

面板标志

标志	可选值	说明
-p, --panel	1–4	目标面板编号
--full-panel	—	填满整个面板
--density	compact、standard、spacious	内容间距
--align-x	start、center、end	水平对齐
--align-y	start、center、end	垂直对齐

其他标志

标志	说明
-b, --board	显示屏 ID
--block <json>	JSON 格式的样式块（可重复）
--stdin	从 stdin 读取完整 JSON 请求

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

创建选项：

标志	说明
-n, --name	显示屏名称（必填）
-d, --description	显示屏说明
-l, --layout	布局 ID

devices

pushtodisplay devices list    # List active device-board streams

config

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

JSON 输出

在任意命令后添加 --json，即可输出机器可读的内容：

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

配置

配置按以下顺序解析：环境变量 → 配置文件 → 默认值。

环境变量	描述	默认值
PTD_API_URL	API 端点	https://api.pushtodisplay.com
PTD_SERVICE_URL	服务端点	https://services.pushtodisplay.com
PTD_IDP_URL	身份提供商	https://idp.pushtodisplay.com
PTD_CONFIG_DIR	配置目录	~/.config/pushtodisplay

MCP 服务

此 CLI 内置了 Model Context Protocol 服务，让 AI Agent（Claude、Cursor、VS Code Copilot 等）能够直接访问你的显示看板。

MCP 服务会继承你的 CLI 会话——如果你已运行 pushtodisplay auth login，它会自动进行身份验证。

设置

Claude Code

claude mcp add pushtodisplay -- npx pushtodisplay mcp

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

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

Cursor

打开“设置” → “MCP Servers” → “添加服务器”，或编辑 .cursor/mcp.json：

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

VS Code（GitHub Copilot）

添加到 .vscode/mcp.json：

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

其他 MCP 客户端

任何支持 stdio 传输的 MCP 客户端都可以使用 Push To Display。服务命令如下：

npx pushtodisplay mcp

可用的 MCP 工具

工具	描述
pushtodisplay_send_update	向看板发送内容
pushtodisplay_list_boards	列出所有看板
pushtodisplay_get_board	获取看板详情
pushtodisplay_create_board	创建新看板
pushtodisplay_update_board	更新看板名称、描述或布局
pushtodisplay_set_default_board	将看板设为默认看板
pushtodisplay_delete_board	永久删除看板
pushtodisplay_list_devices	列出活动设备连接

命令一览

命令	描述
auth login	登录（浏览器或设备代码）
auth logout	移除已存储的凭据
auth status	显示当前身份验证状态
send [text...]	发送显示内容更新
boards list	列出你的看板
boards get <id>	获取看板详情
boards create	创建新看板
boards delete <id>	删除看板
devices list	列出活动设备连接
config	显示当前配置
mcp	启动 MCP 服务

API 密钥身份验证

对于无法进行交互式登录的 CI/CD 管道和脚本，可以使用 API 密钥进行身份验证。可通过移动应用或网络门户创建密钥。API 密钥以 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

注意： API 密钥身份验证仅支持 send 命令。若要完整访问看板、设备和配置管理，请使用 auth login。

屏幕截图

4-panel layout — 一目了然地查看区域状态

多面板展示 CI/CD 流水线和基础设施日志

按颜色标示严重程度的事件时间线

许可证

MIT