Skip to content

cli.md

Latest commit

 

History

History
93 lines (63 loc) · 4.37 KB

cli.md

File metadata and controls

93 lines (63 loc) · 4.37 KB
Raw
description Every Account API endpoint as a command, from your terminal.

CLI

The TRMNL CLI turns our Account API into commands -- list devices, rename them, manage playlists + plugin settings, install recipes, and more. 140 commands today.

We don't ship a new CLI version when we add an endpoint. The CLI reads our OpenAPI document and builds its commands from it, so new endpoints show up on their own. It's powered by Restish, an open source HTTP client for OpenAPI services.

Install

brew install usetrmnl/tap/trmnl

No Homebrew? Download a binary for macOS, Linux or Windows from Releases, or build it with Go:

go install github.com/usetrmnl/cli/cmd/trmnl@latest

Sign in

The first command that touches your account opens trmnl.com in your browser. You'll see the same consent screen as any connected app -- pick what the CLI may do, click Allow, done.

Capability Lets the CLI Ticked by default
read Read your devices + their logs, playlists, plugin settings + private plugin files Yes
content Change your markup, plugin settings, playlists + mashups, install recipes + push images Yes
devices Change your device settings + identify a device Yes
delete Delete plugin settings + playlist items, clear a device playlist No
profile See + change your name, time zone + display settings No
apps Install + manage apps, including fleet pushes + room bookings No

You can also limit the CLI to specific devices + plugin settings on that screen. Tokens refresh on their own -- use the CLI at least once every 30 days + you stay signed in. After a longer break it asks again.

Changed your mind? Remove "TRMNL CLI" under Account > Connected agents and it loses access immediately. To sign out locally, run trmnl auth logout.

API keys (scripts + CI)

No browser? Create an API key under Account API keys, give it only the capabilities it needs, then:

export TRMNL_API_KEY=trmnl_xxxxx
trmnl list-devices

When TRMNL_API_KEY is set, the CLI uses it and never opens a browser.

{% hint style="info" %} The API keys section appears once your account has a device with the Developer edition upgrade (every BYOD license includes it). Browser sign in works for every account. {% endhint %}

Usage

trmnl --help                        # every command, grouped like our API docs
trmnl list-devices --help           # parameters + body fields for one command
trmnl list-devices
trmnl update-device 123 'name: Kitchen'

Request bodies use Restish's shorthand ('name: Kitchen, sleep_mode_enabled: true'), or pipe JSON in over stdin.

Output is JSON by default. Filter it + turn it into a table:

trmnl list-devices -f 'body.data' -o table --rsh-columns id,name,friendly_id

{% hint style="info" %} The device API (/api/display, /api/setup, /api/log) is not part of the CLI. Those endpoints are for devices, authenticated with a device's own Access-Token -- see Display API. {% endhint %}

Errors

The CLI shows our API's answer as-is. The common ones:

  • 403 naming a capability, e.g. "This API key lacks the devices capability" -- create a key with it, or remove "TRMNL CLI" from Connected agents + sign in again with that box ticked.
  • 401 Invalid API key -- TRMNL_API_KEY is wrong or revoked.
  • 429 -- you hit the rate limit. Wait a minute.

The CLI exits with a non-zero status on any error, so scripts can check $?.

Good to know

  • Config + tokens live in ~/.config/trmnl, the command cache in ~/.cache/trmnl
  • New endpoint not showing up yet? trmnl cache clear
  • Building a plugin? Use trmnlp to preview your markup locally
  • Want an AI agent to drive instead? Connect it to our MCP server

Most CLI "feature requests" are really API requests. If a command is missing or clunky, let us know what you're trying to do + we'll improve the endpoint.