Boomack CLI Client

A CLI client for Boomack

Requires: NodeJS ≥ 20

Getting Started

You need to have a Boomack server running, to send media items for display.

Install the Boomack CLI Client with the following command:

npm install -g boomack-cli

Most simple usage: send a string as plain text to the default slot inside the default panel:

boom 'Hello World!'

Basic Options

• --help
• --api <API base URL of the server> E. g. http://my-server.com:3001/
• --token <API authentication token>
• --config <filename of config file> (can be used multiple times)
• --dry Do not send, but print the request
• --curl Do not send, but print the request as cURL commandline
• --silent Do not show info messages

Commands

boom display (default)

Display an hyper-media item in a slot of a Boomack panel.

Options

• -l, --location, --target <panel ID>/<slot ID>
• -s, --string <text content>
• -f, --file ( <filename> | STDIN for STDIN )
• -u, --url <URL to display as media item>
• -w, --watch
  If --file is used, watches for changes of the file and re-sends the display request on every change.
• -t, --type <MIME type>
• -c, --cache ( auto | memory | file )
• -e, --embed
• -x, --extend ( start | end )
• --append same as -extend end
• --prepend same as --extend start
• -o, --options ( <key>=<value> | <YAML/JSON> | <filename> | STDIN )*
  Can be used multiple times.
• --raw Takes content and sends it directly as display request. Ignores all options but --file, --url, and --string.
• --no-file-url
  Prevents passing a file://... URL in case a file is displayed and the server is localhost

If the options --string, --file, and --url are used together, only one of them is used: --file is overruling --url and --string is overruling --file and --url.

Auto Detection of Content and Type

If none of the three options --string, --file, and --url is given, the content is detected automatically by the following rules.

If a non-option argument exists, its value is used as the content to display; Otherwise, the content is read from STDIN as if -f - was used.

1. if it starts with http:// or https:// it is used as URL and the resource from the URL is displayed
2. if it is a valid data URL data:[<mediatype>][;base64],<data>, its content is displayed
3. if it is a valid file path and the file exists, the content of the file is displayed

If --type is not given and MIME type is detected from the path/URL or content:

1. if a file path or an URL is given, the filename is used to detect the MIME type
2. if a URL is given and the path does not contain a known filename (extension), a HEAD request is issued against the URL to determine the content type of the response
3. if the content of a string starts with < and ends with >, it is displayed as text/html
4. otherwise it is displayed as plain text or download

If the filename is used to detect the MIME type, the configuration property client.types is used to map from filename patterns / extensions to MIME types.

boom play

Execute a Playbook.

boom play [ Options ] [<filename>]

If no filename is given, the playbook is read from STDIN.

Playbook Options

• -l, --location, --target <panel ID>/<slot ID> Default panel and slot, if it has not been specified in Display Request or Playbook
• -c, --cancel-on-error Stop the execution at the first occurring error
• -b, --base-path <path> A filesystem path for resolving relative paths in the playbook
• --no-file-url Prevents passing a file://... URL in case a file is displayed and the server is localhost

boom eval

Evaluate JavaScript code in a panel.

This evaluation is volatile, which means it is executed in all Browsers, which currently show the target panel. But the code is not persisted in any way.

boom eval [ --target <panel ID> ] (<code> | <filename> | STDIN)

boom panel

Manage panels and change the layout of a panel.

Used without specified sub-command uses implicitly ls as sub-command.

Sub-Commands

• boom panel ls
  List the IDs of all existing panels
• boom panel get [ <panel ID> ]
  Retrieve the layout of a panel with all slots
• boom panel add <panel ID> [ <YAML/JSON> | <filename> | STDIN ]
  Add a new panel with a given layout
• boom panel update/layout <panel ID> ( <YAML/JSON> | <filename> | STDIN )
  Update the layout of an existing panel
• boom panel clear [ <panel ID> ]
  Clear all slots in the panel
• boom panel delete <panel ID>
  Delete an existing panel
• boom panel export [ <panel ID> ] [ Options ]
  Export a panel as HTML file to the filesystem of the server

Export Options

• -t, --theme <theme name>
• -z, --zoom <zoom factor>
• -p, --path <relative path> A relative path inside the export directory in the filesystem of the Boomack server.
• -n, --name <filename without extension> The target filename for the exported HTML file. Only for panel and slot.
• --no-header Suppress the panel header.
• --no-logo Suppress the logo from the header.
• --no-toolbars Suppress the toolbars from the slots.
• --no-tools Suppress the tools from the slot toolbars.

boom slot

Clear or export individual slots.

Sub-Commands

• boom slot clear <panel ID>/<slot ID>
  Clear all content including the history from a slot.
• boom slot export <panel ID>/<slot ID> [ Options ]
  Export a slot as HTML file to the filesystem of the server.

Export Options

• -t, --theme <theme name>
• -z, --zoom <zoom factor>
• -p, --path <relative path>
  A relative path inside the export directory in the filesystem of the Boomack server.
• -n, --name <filename without extension>
  The target filename for the exported HTML file. Only for panel and slot.
• --no-toolbar Suppress the toolbar from the slot.
• --no-tools Suppress the tools from the slot's toolbar.

boom preset

Manage prepared options.

Used without specified sub-command uses implicitly ls as sub-command.

Sub-Commands

• boom preset ls
  List the IDs of all existing presets
• boom preset get <preset ID>
  Get the definition of an existing preset
• boom preset add <preset ID> ( <key=value>* | <YAML/JSON> | <filename> | STDIN )
  Add a new preset
• boom preset update <preset ID> ( <key=value>* | <YAML/JSON> | <filename> | STDIN )
  Update an existing preset
• boom preset delete <preset ID>
  Delete an existing preset

boom type

Manage media types.

Used without specified sub-command uses implicitly ls as sub-command.

Sub-Commands

• boom type ls
  List the IDs of all existing media types
• boom type get <media type ID>
  Get the definition of an existing media type
• boom type add <media type ID> ( <key=value>* | <YAML/JSON> | <filename> | STDIN ) [ -p | --presets <preset ID>* ] [--text]
  Add a new media type
• boom type update <media type ID> ( <key=value>* | <YAML/JSON> | <filename> | STDIN ) [ -p | --presets <preset ID>* ] [--text]
  Update an existing media type
• boom type delete <media type ID>
  Delete an existing media type

boom action

Manage actions.

Used without specified sub-command uses implicitly ls as sub-command.

Sub-Commands

• boom action ls
  List the IDs of all existing actions
• boom action get <media type ID>
  Get the definition of an existing action
• boom action add <action ID> ( <YAML/JSON> | <filename> | STDIN ) [ Options ]
  Add a new action
• boom action update <action ID> ( <YAML/JSON> | <filename> | STDIN ) [ Options ]
  Update an existing action
• boom action delete <action ID> [ Options ]
  Delete an existing action

boom export

Export individual slots, one, or multiple panels as static HTML to the server filesystem.

Used without specified sub-command uses implicitly all as sub-command.

Sub-Commands

• boom export all
  Export all panels as HTML files to the filesystem of the server
• boom export panel [id]
  Export one panel as HTML file to the filesystem of the server
• boom export slot <panel ID>/<slot ID>
  Export one slot as HTML file to the filesystem of the server

Export Options

• -t, --theme <theme name>
• -z, --zoom <zoom factor>
• -p, --path <relative path> A relative path inside the export directory in the filesystem of the Boomack server.
• -n, --name <filename without extension> The target filename for the exported HTML file. Only for panel and slot.
• --no-header Suppress the panel header.
• --no-logo Suppress the logo from the panel header.
• --no-toolbars Suppress the toolbars from all slots of a panel.
• --no-toolbar Suppress the toolbar from a single slot.
• --no-tools Suppress the tools from a slot's toolbar.

Configuration

The configuration of the Boomack Client CLI consists of the following parts:

• Boomack Server API URL
• API Authentication Token
• Request Options
  • Timeout
  • Retry Attempts
  • Response Format
• Filename to Media Type Mapping

The configuration is merged from a couple of different sources, listed from highest to lowest priority:

1. Command line switches
2. Environment variables
3. Explicit configuration files
4. Implicit configuration files
5. Default configuration

Command Line Switches

The following command line switches impact the configuration:

• --api <API base URL of the server>
• --token <API authentication token>
• --format (text | json | html)

Environment Variables

The following environment variables are supported:

• BOOMACK_SERVER_URL: API base URL of the server
• BOOMACK_SERVER_HOST: The hostname or IP address of the server
• BOOMACK_SERVER_PORT: The port of the server
• BOOMACK_CLIENT_TOKEN: API authentication token
• BOOMACK_CLIENT_TIMEOUT: Timeout for the API requests in milliseconds
• BOOMACK_CLIENT_RETRY: Number of retries for an API request
• BOOMACK_CLIENT_FORMAT: The response format (text/plain, application/json, text/html)

|>INFO<| Hint: The variable BOOMACK_SERVER_URL has priority over the variables BOOMACK_SERVER_HOST and BOOMACK_SERVER_PORT.

Configuration Files

Configuration files for the Boomack Client CLI are picked up implicitly from some places, and can additionally be specified explicitly with the command line switch --config <filename>.

The following implicit configuration files are considered in that order:

• boomack[.json|.yaml|.yml] in the current working directory
• .boomack[.json|.yaml|.yml] in the user profile
• boomack-server[.json|.yaml|yml] in the current working directory
• .boomack-server[.json|.yaml|.yml] in the user profile

The config files in the current working directory and the user profile can have no filename extension or one of the following: .json, .yaml, .yml. And they are looked up in that order. Meaning, if a file boomack in the current working directory exists, another file with name boomack.yaml will be ignored.

|>SUCCESS<| Note: The configuration files of the Boomack Server and the Boomack Client CLI are compatible in that regard, that the client can read host and port for the API URL from the server configuration, and the server ignores everything under the property client. As a result a boomack-server[.json|.yaml|.yml] config file in the current working directory can configure both, server and client.

Default Configuration

The default client configuration looks like this:

===| TABS |=== :::| YAML |:::

server:
  host: localhost
  port: 3000
  url: null  # if set, takes precedence over host and port
client:
  token: null
  timeout: 10000  # in milliseconds
  retry: 0
  format: text/plain  # text/plain, application/json, text/html
  types:  # mapping from filename patterns to media types
    '*.txt': 'text/plain'
    '*.md': 'text/markdown'
    '*.csv': text/csv'
    '*.tsv': 'text/tsv'
    '*.vega': 'application/x-vega-spec'
    '*.vegalite': 'application/x-vega-lite-spec'
    'Dockerfile': 'text/x-dockerfile'
    'makefile': 'text/x-makefile'
    ...

:::| JSON |:::

{
  "server": {
    "host": "localhost",
    "port": 3000,
    "url": null
  },
  "client": {
    "token": null,
    "timeout": 10000,
    "retry": 0,
    "format": "text",
    "types": {
      "*.txt": "text/plain",
      "*.md": "text/markdown",
      "*.csv": "text/csv'",
      "*.tsv": "text/tsv",
      "*.vega": "application/x-vega-spec",
      "*.vegalite": "application/x-vega-lite-spec",
      "Dockerfile": "text/x-dockerfile",
      "makefile": "text/x-makefile",
      ...
    }
  }
}

===|------|===

|>INFO<| Hint: If the server URL is not given on any level of the configuration, the server host and port are used with the http:// protocol to build the API base URL.