boomack-cli
v0.14.0
Published
CLI client for boomack
Downloads
5
Readme
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 afile://...
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.
- if it starts with
http://
orhttps://
it is used as URL and the resource from the URL is displayed - if it is a valid data URL
data:[<mediatype>][;base64],<data>
, its content is displayed - 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:
- if a file path or an URL is given, the filename is used to detect the MIME type
- 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
- if the content of a string starts with
<
and ends with>
, it is displayed astext/html
- 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 panelsget
[<panel ID>
] Retrieve the layout of a panel with all slotsadd
<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 forpanel
andslot
.--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 forpanel
andslot
.--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 presetsget
<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 typesget
<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 actionsadd
<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 forpanel
andslot
.--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:
- Command line switches
- Environment variables
- Explicit configuration files
- Implicit configuration files
- 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 serverBOOMACK_SERVER_HOST
: The hostname or IP address of the serverBOOMACK_SERVER_PORT
: The port of the serverBOOMACK_CLIENT_TOKEN
: API authentication tokenBOOMACK_CLIENT_TIMEOUT
: Timeout for the API requests in millisecondsBOOMACK_CLIENT_RETRY
: Number of retries for an API requestBOOMACK_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 profileboomack-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.