CLI

CLI collection executes SSH commands on a device and stores the raw output as structured data. Prelude Collector uses CLI as the fallback protocol when a device does not expose gNMI, SNMP, or NETCONF, or when the data you need is only available through show commands. After the first mention, this page refers to Prelude Collector as "the collector".

Parsing CLI output into structured fields is handled separately by TTP (Template Text Parser) templates attached to the Model. The Protocol layer is responsible for getting the bytes off the wire; TTP turns those bytes into Field values when a template is attached. A Model with no CliTemplate produces Snapshots whose values are the raw command output as a single string — useful for one-off captures, fine for small fleets, but you will want a template before you scale.

When to use

Pick CLI as a last resort. It is the most expensive protocol to operate and the first one to break on a vendor software upgrade — CLI output formats change between releases and your TTP templates have to keep up. Reasonable cases:

• The metric you need is not exposed in gNMI, NETCONF, or SNMP on the target platform.
• A small fleet of legacy devices with no API at all.
• A dynamic list of items (tunnel IDs, BFD sessions, MPLS LSPs) where per-item state has to be queried with parameterized commands.

If gNMI, NETCONF, or SNMP exposes the same data, prefer those.

Connection settings

A CLI Protocol record carries the device-side transport settings:

The collector-wide CLI timeouts apply to every CLI Protocol record and are set via COLLECTOR_CLI_* environment variables (see the Configuration reference):

For the exact field names accepted by the API, see the API reference for Protocols.

The CLI client maintains one SSH session per Protocol record. Commands are executed serially on that session — SSH is not multiplexed — so high poll frequencies across many Models on the same device queue up.

Authentication options

SSH password

The default and only currently supported authentication mode. Public key authentication is not yet supported.

Parameterized commands and discovery

CLI commands can include {param} placeholders that the collector expands at poll time using values discovered from a separate discovery command. Use this when the set of items to collect depends on device state — for example, per-MPLS-TE-tunnel statistics where the tunnel IDs change.

How it works:

1. Discovery params are configured on the Model's CLI config alongside the regular commands.
2. At subscribe time, TTP templates for each discovery param are compiled once and reused across polls.
3. At poll time, the discovery command runs first, its output is parsed with TTP, and the extracted values are mapped by param name.
4. Commands with {param} placeholders are expanded as a cross product of the discovered values.
5. The expanded command list replaces the original commands for that poll cycle.

A safety cap of 500 expanded commands per poll prevents runaway cross-products from overwhelming the device.

# Command template
show mpls traffic-eng tunnels {tunnel_id} detail

# Discovery yields tunnel IDs: [1, 2, 3]
# Expands at poll time to:
show mpls traffic-eng tunnels 1 detail
show mpls traffic-eng tunnels 2 detail
show mpls traffic-eng tunnels 3 detail

A discovery param is defined by:

For the exact request shape accepted by the API, see the API reference for Protocols.

Examples

Device + Protocol record

export BASE="https://collector.example.com"
export TOKEN="<your-api-token>"

curl -s -X POST "$BASE/api/v1/devices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "legacy-edge-07",
    "ip": "192.0.2.70",
    "active": true
  }'

curl -s -X POST "$BASE/api/v1/protocols" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": 7,
    "type": "cli",
    "address": "192.0.2.70:22",
    "username": "prelude",
    "password": "<your-device-password>"
  }'

Bruno: 02 Devices / Create device, 03 Protocols / Create gNMI protocol

Subscription

device_id: 7
model: cli-interface-counters
interval: 120
enabled: true

Use coarse intervals for CLI — every poll is one or more SSH command exchanges plus a regex pass.

Limitations

• Authentication is SSH password only. Public-key auth is not yet supported.
• Host key verification is not enforced. Use only on a trusted management VLAN.
• Output formats change between vendor software releases. Plan to maintain TTP templates per OS major version.
• Each Protocol record holds one SSH session. All Models on that Protocol serialize their commands, so high poll frequencies on many Models translate directly into per-command latency.
• Discovery cross-products are capped at 500 expanded commands per poll cycle. If you need more, split the work across several Subscriptions.
• CLI delivers Snapshot rows that are raw command output until a TTP template structures them. A Model without a template will produce free-form strings.

Troubleshooting

Test Connection from the device UI

Open the device's Protocols tab in the web UI and click Test Connection on the CLI Protocol row. The collector opens an SSH session using the credentials stored on the Protocol record and reports success, failure, or the SSH error returned. Use this first whenever a Subscription stops producing Snapshots — it proves SSH auth and reachability before you start chasing TTP templates.

One-shot command test

CLI uses a separate endpoint from the test-path shared by gNMI, SNMP, and NETCONF. test-cli runs a list of show commands on an existing Device and returns the raw output:

curl -s -X POST "$BASE/api/v1/protocols/test-cli" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "device-id": 7,
    "commands": ["show version", "show interfaces brief"]
  }'

Bruno: 03 Protocols / Test CLI command

The response contains the per-command output, a has-data flag, and any device-side errors. Use it to verify a command produces the output you expect before writing the TTP template.

A safety blocklist rejects destructive commands (reload, write erase, clear, etc.) and the endpoint caps each request at 20 commands.

See also

• Collection protocols
• Choosing a protocol
• Polling intervals
• API: Protocols