Use in Scripts¶

How to consume tlm-cli output in shell scripts, CI pipelines, and Docker containers.

In plain mode the CLI emits newline-delimited JSON to stdout and plain-text warnings or errors to stderr. This makes it safe to pipe into jq or redirect to a file without Rich formatting or interactive prompts interfering.

Activate plain mode¶

Three equivalent ways to activate plain mode:

Flag¶

tlm-cli --plain pms devices list

Environment variable¶

TLM_CLI_PLAIN=1 tlm-cli pms devices list

Automatic — pipe or redirect stdout¶

# No flag needed: piping stdout triggers plain mode automatically
tlm-cli pms devices list | jq
tlm-cli pms models list > models.json

Output shape¶

List commands emit a JSON array — one object per row:

tlm-cli --plain pms models list
# [{"Name":"gateway-v2","Description":"Main gateway","Tags":"","Customers":"ACME"},...]

Show and detail commands emit a JSON object:

tlm-cli --plain pms models show "gateway-v2"
# {"Name":"gateway-v2","Description":"Main gateway","Tags":"","Customers":"ACME"}

Parse output with `jq`¶

Extract a single field from every row:

tlm-cli pms models list | jq -r '.[].Name'

Filter rows by field value:

tlm-cli pms devices list | jq '.[] | select(.Status == "online")'

Get a comma-separated list of serial numbers:

tlm-cli pms devices list | jq -r '[.[] | .["Serial Number"]] | join(",")'

Extract a field from a detail view:

tlm-cli pms models show "gateway-v2" | jq -r '.["Active Release"]'

Use in a shell script¶

#!/usr/bin/env bash
set -euo pipefail

export TLM_CLI_PLAIN=1

# Fetch all model names
models=$(tlm-cli pms models list | jq -r '.[].Name')

for model in $models; do
    echo "Processing $model..."
    tlm-cli pms models show "$model" | jq -r '.Description'
done

Use in Docker or CI¶

Set TLM_CLI_PLAIN=1 in your environment or Dockerfile:

ENV TLM_CLI_PLAIN=1

In a CI pipeline (e.g. GitLab CI):

variables:
  TLM_CLI_PLAIN: "1"

script:
  - tlm-cli cs projects list | jq '.[].Name'

Errors and warnings¶

Errors are written to stderr with an error: prefix and exit code 1:

# Show only errors (suppress JSON output)
tlm-cli pms models show "nonexistent" 2>&1 1>/dev/null
# error: model not found: nonexistent

Warnings are written to stderr with a warning: prefix and do not affect the exit code:

tlm-cli pms devices list 2>/dev/null   # suppress warnings, keep stdout JSON

Redirect stderr separately to capture both streams independently:

tlm-cli pms devices list > devices.json 2> errors.log