Apps on your display

A display shows its playlist: a list of entries it plays one after another. An entry is an app from the store, with the settings you gave it, or a picture. The examples use $DEVICE for the display's id, as Set up a display explains.

Browse the store

ledable store home
ledable store search weather
ledable store app <app_id>

• store home prints the store's front page: the top apps of each category, the collections and the latest apps.
• store search finds listed apps whose name, description and tags contain all your words. --category narrows it to one category (clock, weather, finance, news, sports, productivity, developer, entertainment, science, travel), and --tag to one tag.
• store app prints an app's store page: its description, current version, publisher, README, screenshots, and under network.allowed_hosts the hosts the app fetches data from.

These three work without signing in. Every app is named by its app_id, such as the one store search prints for each result.

To see what an app draws before you install it, download its store preview:

ledable store preview <app_id> preview.webp --device "$DEVICE"

store preview writes the preview as a WebP image, in the display's language and time zone. The display is optional here; without it, the preview is in English and UTC.

Someone may send you a share link to an app that is not in the store yet. Pass it to store app, store manifest or store preview with --share <link> to look at the version it shares.

Install an app

ledable store install <app_id> --device "$DEVICE"

store install adds the app at the end of the display's playlist, the way the app's install page does, and prints what it stored:

{
  "state": "stored",
  "device_id": "…",
  "app_id": "…",
  "version": "…"
}

Without a version, it installs the version the store lists now. Write <app_id>@<version> to install a particular one.

Every setting starts from the default the app declares. When a setting must be filled in and has no value, the install stops and names it: Still needed: Location.

Give settings

store manifest prints the settings of an app's version under fields: each field's key, its type, its name, its default and, for a choice, its options.

ledable store manifest <app_id>

Write the values you want in a JSON file, keyed by the field keys, and pass it with --values. A key you leave out keeps its default, and null restores the default.

{
  "units": "metric",
  "show_wind": "true",
  "location": "{\"lat\":52.52,\"lng\":13.405,\"desc\":\"Berlin\"}"
}

ledable store install <app_id> --device "$DEVICE" --values weather.json

Every value is a string, written the same way the app stores it:

A value that does not fit its field is refused before anything is stored.

Tokens and passwords

Some apps ask for a credential, such as a personal API token: a field of type credential. Do not put it in the values file. Name the field with --credential, once per field, and type the value at the hidden prompt; in a script, pipe one line of stdin per field, in the order you named them.

ledable store install <app_id> --device "$DEVICE" --credential token

The platform keeps the value, and the playlist holds only a reference to it.

Linked accounts

Some apps show data from your account at another service, such as GitHub, Todoist, YouTube or Spotify. Their settings have a field of type authhub_github, authhub_todoist, authhub_youtube or authhub_spotify. Link the account once, then give it to each app that asks for it:

ledable auth-hub link github
ledable auth-hub list

auth-hub link opens your browser, where you allow LEDABLE to use the account at the service, and waits until you have. It then prints the linked account, including its handle_token. With --no-browser it prints the address instead; open it in a browser on the same computer, because the browser hands the authorisation back to the CLI there.

To use the account in an app, put its handle_token from auth-hub list in the values file, as the value of the app's account field.

auth-hub remove forgets a linked account. The service still lists LEDABLE as authorised until you revoke it there.

Update apps

When the store has a newer version of an app, move the display's entries of it there:

ledable store update <app_id> --device "$DEVICE"

store update moves every entry of the app to the version the store lists now and keeps their settings. It prints the version and the entries it moved, with state unchanged when they were already there. If the new version needs a setting an entry does not have, it stops with Still needed: ….

Arrange the playlist

ledable playlist list --device "$DEVICE"

playlist list prints the display's playlist. Each entry under config.apps has an instance_id, its name, and url_app for a store app or data_app for a picture. An entry that is switched off has no enabled field, and one that follows the display's default time has no display_duration_millis.

The other playlist commands name an entry by its instance_id:

ledable playlist disable <instance_id> --device "$DEVICE"
ledable playlist move <instance_id> 0 --device "$DEVICE"
ledable playlist duration <instance_id> 20 --device "$DEVICE"

• playlist enable and playlist disable switch an entry on and off; a display skips entries that are off.
• playlist move moves an entry to a position, counted from 0.
• playlist rename renames an entry.
• playlist duration sets how many seconds an entry shows; 0 makes it follow the display's default.
• playlist configure changes a store app's settings, with the same --values and --credential as store install; a setting the file leaves out keeps its current value.
• playlist remove removes an entry. A picture that no other entry shows is deleted with it.

If someone changed the playlist elsewhere in the meantime, for example in the phone app, the command fails and leaves the playlist as it is; run it again. playlist page runs the app's playlist page, for several changes in one go; Scripting shows how.

Changes are stored on LEDABLE's servers, and the CLI tells the display to fetch them before it exits. A display that is off picks them up when it next starts; to have it fetch them again, run devices pull.

Control playback

These act on a display that is online:

ledable playback next --device "$DEVICE"
ledable playback previous --device "$DEVICE"
ledable playback toggle --device "$DEVICE"

playback next and playback previous step through the playlist and end once the display shows the entry they stepped to. Each prints the player, one line each time it changes; here one line is indented for reading:

{
  "state": {
    "playing": true,
    "mode": "…",
    "highlighted": "…",
    "title": "…",
    "awaiting_device": null
  }
}

title is the name of the entry on the display, and awaiting_device the entry the player is waiting for the display to show. playback toggle pauses or resumes the playlist and ends once the command is sent, since older firmware does not report a pause. playback control keeps the player open and takes next, previous and toggle as lines on stdin.