Command Line Outout
Passing output from the CLI to other processes
Dependencies
Before you can use the Beamable CLI, you need to complete the Getting-Started Guide. That means having Dotnet 8 installed, and getting the Beam CLI.
You can confirm you have everything installed checking the versions of the tools.
dotnet --version
beam version # beam --version also works.
Logging
By default, the Beam CLI uses an informational level of logging. Usually, only the final output of a command will be printed to the console. However, for diagnostic purposes, you can change the log level of the CLI using the --log
switch.
The log levels are as follows,
Level | Description |
---|---|
VERBOSE | a diagnostic level of logs that includes pseudo developer commentary |
DEBUG | a diagnostic level of logs that prints out additional context |
INFO | the default log level, where only the expected output of the command is logged |
WARNING | ignores default output, and only prints out a warning of something went wrong |
ERROR | ignores everything unless an error occurs |
FATAL | ignores everything unless the process fatally crashes |
In order to set the log level, the full level name may be used (case insensitive), or simply the first letter of the level. For example, to use verbose logs, the following expression may be used.
beam config --logs v
Raw Output Mode
By default, the Beam CLI prints output in a variety of ways. Some commands will print JSON to the Standard Output Buffer (StdOut), and other commands will print conversational messages. However, all commands can be forced to print in a structured JSON format.
The --raw
flag will always print messages in JSON. The --raw
message contains additional information than what may be printed for commands that already use JSON. For example, the beam config
command prints JSON,
beam config
{
"host": "https://api.beamable.com",
"cid": "123",
"pid": "DE_123",
"configPath": "/Users/Test/MyProject/.beamable"
}
However, when the --raw
flag is given, the output becomes,
beam config --raw
{"ts":1716908373832,"type":"stream","data":{"host":"https://api.beamable.com","cid":"123","pid":"DE_123","configPath":"/Users/Test/MyProject/.beamable"}}
There are 3 top level parameters.
Field | Description |
---|---|
ts | A UNIX timestamp in seconds, documenting when the output was logged. |
type | A string declaring the type of output. Most commands will output one type of data to the "stream" type. However, some commands may output multiple schemas of data, and the type field may be used to distinguish between them. |
data | Contains the actual JSON payload |
Piping
When a Beam CLI command is piped into another process, the --raw
flag is force enabled. For example, if beam config
is piped into a file, then the contents of the file will be the --raw
output.
beam config > output.txt
cat output.txt
{"ts":1716908709811,"type":"stream","data":{"host":"https://api.beamable.com","cid":"123","pid":"DE_123","configPath":"/Users/Test/MyProject/.beamable"}}
A common workflow is to use the JQ tool to navigate the piped --raw
output. Below are some common examples.
In order to pipe the data
to a file, we could write,
beam config | jq '.data' > output.txt
cat output.txt
{
"host": "https://api.beamable.com",
"cid": "123",
"pid": "DE_123",
"configPath": "/Users/Test/MyProject/.beamable"
}
In order to only print the cid
value to console, we could write,
beam config | jq '.data.cid'
"123"
Sometimes it is important to get the unescaped JSON, so the fromjson
component of JQ can be used. For example, if we wanted the cid
value, but without quotes,
beam config | jq '.data.cid | fromjson'
123
Piping and Logging
When the --raw
flag is used, or a command is piped to a file, then the Standard Output Buffer will only receive the --raw
output data. If the --logs
flag is set, then logs will be sent to the Standard Error Buffer, such that will appear in the console. However, it can be tricky to emit the process logs to a file.
In order to do so, the Standard Error Buffer must be piped to a file. For example, the following expression will put the process logs into a file.
beam config --logs v 2> test.txt
The contents of the test.txt
file contain the process logs, not the --raw
output.
cat test.txt
Trying to get option=ConfigDirOption from Env Vars! Value Found=
Using standard unix docker uri=[unix:/var/run/docker.sock]
GET call: /basic/beamo/manifest/current
...
Error Logging
The Beam CLI usually creates a temporary log file and emits verbose logs to the file for diagnostic purposes. This can be disabled if the environment variable, BEAM_CLI_NO_FILE_LOG
is set to anything.
When an error occurs, the output log should include a line similar to,
Logs at
/var/folders/ys/949qmfy15r7bl8x36s6wmm000000gn/T/beamCliLog.txt
Updated 4 months ago