boomack-cli

Boomack CLI Client

A CLI client for Boomack

Getting Started

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

npm install -g boomack-cli

Most simple usage: send a string as plain text to the default slot in the default display:

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

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.

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)

panel

Manage panels and change the layout of a panel.

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

Sub-Commands

• ls List the IDs of all existing panels
• get [ <panel ID> ] Retrieve the layout of a panel with all slots
• add <panel ID> [ <YAML/JSON> | <filename> | STDIN ]
• update/layout <panel ID> ( <YAML/JSON> | <filename> | STDIN )
• clear [ <panel ID> ]
• delete <panel ID>
• export [ <panel ID> ] [ Options ]

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.

slot

Clear or export individual slots.

Sub-Commands

• clear <panel ID>/<slot ID>
• export <panel ID>/<slot ID> [ Options ]

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.

preset

Manage prepared options.

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

Sub-Commands

• ls List the IDs of all existing presets
• get <preset ID>
• add <preset ID> ( <key=value>* | <YAML/JSON> | <filename> | STDIN )
• update <preset ID> ( <key=value>* | <YAML/JSON> | <filename> | STDIN )
• delete <preset ID>

type

Manage media types.

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

Sub-Commands

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

action

Manage actions.

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

Sub-Commands

• ls List the IDs of all existing actions
• add <action ID> ( <YAML/JSON> | <filename> | STDIN ) [ Options ]
• update <action ID> ( <YAML/JSON> | <filename> | STDIN ) [ Options ]
• delete <action ID> [ Options ]

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

• all
• panel [id]
• slot <panel ID>/<slot ID>

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.