Read, render, and write your Vestaboard from the terminal — with a board preview and character-code table no other Vestaboard tool ships.
Wraps the Vestaboard Cloud Read/Write API (read the current message, send text or character-code messages, control transitions) plus the VBML text formatter on its own host. The novel 'message preview' renders the live board as readable text, and 'characters' prints the code table so you can build character-array payloads by hand.
Learn more at Vestaboard.
Created by @cathrynlavery (Cathryn Lavery).
Authentication
Create a Cloud API token in the API tab on web.vestaboard.com (or the mobile app under Settings → Advanced Settings), then run 'vestaboard-pp-cli auth set-token '. The token is sent only to cloud.vestaboard.com; the VBML formatter on vbml.vestaboard.com takes no credentials.
Quick Start
# check config and connectivity before sending anything
vestaboard-pp-cli doctor --dry-run
# see the board's current contents as readable text
vestaboard-pp-cli message preview
# format text into a character-code grid (no auth, second host)
vestaboard-pp-cli vbml --message "HELLO" --json
# put a message on the board (1 msg / 15s rate limit)
vestaboard-pp-cli message send --body-json '{"text":"hello"}'
Unique Features
These capabilities aren't available in any other tool for this API.
Make the board legible
-
message preview — See what's on your Vestaboard right now as readable text instead of a raw integer grid.
Reach for this before composing or sending — it is the only way to know the board's current contents without decoding codes by hand.
vestaboard-pp-cli message preview --json
-
characters — Print the full Vestaboard character-code table (code to glyph) for hand-building a character-array message.
Use this when constructing a 'message send' character payload so you map glyphs to the right integer codes.
vestaboard-pp-cli characters --json
Recipes
Read the board as text
vestaboard-pp-cli message preview
Decodes the live layout into a bordered block of glyphs you can read.
Inspect the raw layout with field selection
vestaboard-pp-cli message get --agent --select currentMessage.id,currentMessage.layout
Pulls just the id and raw character grid for an agent without the surrounding envelope.
Format then send a message
vestaboard-pp-cli vbml --message "GM" --json
Convert text to a character-code grid on the VBML host, then pass it to 'message send --body-json'.
Set a transition
vestaboard-pp-cli transition set --transition wave --transition-speed gentle
Change the flip animation style and speed.
Usage
Run vestaboard-pp-cli --help for the full command reference and flag list.
Commands
message
The message currently shown on the Vestaboard.
vestaboard-pp-cli message get - Read the message currently displayed on the board. The layout is a JSON-encoded 2D array of character codes whose dimensions depend on the board type.vestaboard-pp-cli message send - Send a new message to the board. Provide --text (plain text / VBML) or --characters (a JSON 2D array of character codes). Rate limited to 1 message per 15 seconds.
transition
Transition animation settings for the board (Flagship and Note devices).
vestaboard-pp-cli transition get - Get the current transition style and speed.vestaboard-pp-cli transition set - Set the transition style and speed. Both fields are required.
vbml
Vestaboard Markup Language (VBML) text formatting service.
vestaboard-pp-cli vbml - Convert a text string into a 2D array of Vestaboard character codes.
Output Formats
# Human-readable table (default in terminal, JSON when piped)
vestaboard-pp-cli message get
# JSON for scripting and agents
vestaboard-pp-cli message get --json
# Filter to specific fields
vestaboard-pp-cli message get --json --select id,name,status
# Dry run — show the request without sending
vestaboard-pp-cli message get --dry-run
# Agent mode — JSON + compact + no prompts in one flag
vestaboard-pp-cli message get --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
vestaboard-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/vestaboard-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
VESTABOARD_API_KEY | per_call | No | Set to your API credential. |
agentcookie (optional)
If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, vestaboard-pp-cli doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.
Troubleshooting
Authentication errors (exit code 4)
- Run
vestaboard-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $VESTABOARD_API_KEY
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- Messages are dropped or 429-rate-limited — The board accepts at most 1 message per 15 seconds; space out 'message send' calls.
- 'message preview' renders a blank or wrong grid — Board size varies by device (Flagship 6x22, Note 3x15); preview renders whatever the API returns. Re-run 'message get --json' to inspect the raw layout.
- 'message send' returns success but quiet hours suppress it — Add "forced": true to the body-json to override configured quiet hours.
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press