elm
A cli tool for extracting LogicMonitor data via the API
This tool simplifies running basic read-only queries against the
LogicMonitor API, formatting the output in various formats, including
CSV, HTML, JSON, XML, Markdown, and more.
elm is intentionally read-only. It only performs GET requests and
cannot create, modify, or delete anything in your LogicMonitor
account. This makes it safe to hand to anyone: the worst outcome is a
slow query or confusing output, never an accidental change to your
platform.
What can I use it for?
- Pull any LM list endpoint — devices, alerts, collectors, SDTs, websites, audit logs, and more
- Answer questions fast: which devices are in downtime right now? which alerts are unacked? what's missing a datasource?
- Output in 20+ formats — CSV for a spreadsheet, JSON for a script, Markdown or HTML for a report — by changing one flag (
-f)
# a readable table in your terminal (one of 20+ output formats)
$ elm -f pipe DeviceList -f name,displayName,preferredCollectorGroupName
| name | displayName | preferredCollectorGroupName |
|:---------------|:------------|:----------------------------|
| acme-web01.lan | acme-web01 | Production Collectors |
| acme-db01.lan | acme-db01 | Production Collectors |
| 10.0.0.5 | acme-fw01 | Production Collectors |
# the same query as CSV for a spreadsheet - just change -f
$ elm -f csv DeviceList -f name,displayName
name,displayName
acme-web01.lan,acme-web01
acme-db01.lan,acme-db01
10.0.0.5,acme-fw01
Features
- Retrieve data from LogicMonitor via the API
- Output in more than 20 formats: csv, json, jsonl, html, xml, markdown, tsv, and more
- Generate ready-to-run
curl and wget commands for any query, with auth headers included
- Read-only: GET requests only, no risk of accidental changes
Installation
Quick Start
In a hurry? Just do this:
git clone https://github.com/rdmarsh/elm.git
cd elm
make
make install
make install copies the binary to ~/bin. If ~/bin is not in your PATH, add it:
echo 'export PATH="${HOME}/bin:${PATH}"' >> ~/.bash_profile
source ~/.bash_profile
API credentials can be placed in an ini file:
cd ~/.config/logicmonitor/credentials
cp config.example.ini config.ini
vi config.ini
elm enforces secure permissions on the credentials directory (700) and
config file (600) on every run. If the permissions are too open, elm
will warn and fix them automatically. If it cannot fix them, it will
abort.
Use elm --list (or elm -l) to see available credential profiles.
To use a non-default profile: elm --profile NAME COMMAND. To run a command
on several portals at once: elm -p NAME,NAME COMMAND (see
Several portals at once).
You may need to restart your terminal session.
Now you can run elm from anywhere on the cli.
Note: on macOS, the first run may take longer than normal due to Gatekeeper
verification. This does not affect Linux.
You can also run tests:
make testoffline # needs no credentials
make testbasic
make testverb # requires LM connection
Pre-requisites
Ensure the following software is installed (you can check some of these
are present by running make init)
makejqawkgit -- to initially clone the repopython3, a version make accepts: from PYTHON_MIN up to the newest
tested, PYTHON_MAX (both near the top of the Makefile). If your default
python3 is newer, make stops and says so; pick another with
make clean && make PYTHON=python3.NN. Once venv/ exists, plain make
uses its Python.curl -- only needed for make swagger (refreshing the LogicMonitor spec).
The build itself never downloads anything, so curl is not required to
build, install or run elm.
Clone the Repo
To clone the repository, use:
git clone https://github.com/rdmarsh/elm.git
cd elm
Building
After cloning, run:
make
This will:
- Initialise needed dirs
- Create json definition files from the committed swagger snapshots
- Create the python files from jinja templates
- Create config dir
- Copy example config file
- Install the required python packages
Initial Configuration
You will need the following items to run the program after building:
- A LogicMonitor API id and key associated with your account
- (optional) a config file with the API info (default to
~/.config/logicmonitor/credentials/config.ini)
- If you don't have this, run
make cfg and follow the directions
- Pre-requisite software listed above
elm-logo.svg is the project mark (an elm leaf: lopsided at the base and
toothed, as elm leaves are). It is the page icon for Samara (samara)
and can be reused for docs or slides.
See config.example.ini for a documented example config file, and
ai.example.ini for a suggested restricted profile for AI assistants.
Restricting a profile to some commands
A profile can allow only the commands it is meant for. Add allowed_commands to
its .ini:
# ~/.config/logicmonitor/credentials/metricsusage.ini
access_id = '...'
access_key = '...'
account_name = 'example'
allowed_commands = ['MetricsUsage'] # or e.g. ['DeviceList', 'Alert*']
Anyone using that profile, whether a person, a script or an AI assistant, can
then run only those commands. Anything else stops before a request is sent,
with exit code 3, the command that was attempted and the line to add if it
should be allowed, so a typo or a wrong guess inside automation cannot wander
off to other endpoints:
$ elm -p metricsusage AdminList -s0
Error: AdminList is not allowed. Profile 'metricsusage' allows only: MetricsUsage (allowed_commands in ~/.config/logicmonitor/credentials/metricsusage.ini).
No request was sent.
...
elm -p NAME --help lists only the allowed commands, --info and --help are
refused for the others, and elm --list shows (allows: ...) next to
restricted profiles. Patterns are shell-style (Device*) and case-sensitive;
AlertList does not also match AlertListByDeviceId.
In the .ini | Allowed |
|---|
no allowed_commands line | every command |
allowed_commands = ['MetricsUsage', 'Device*'] | only those |
allowed_commands = 'MetricsUsage' | only that one |
allowed_commands = [] | nothing (a locked profile) |
None, '', an empty name, a number, or anything unparseable | elm stops with an error rather than guessing |
The list has to stay on one line: the .ini format elm uses has no multi-line
values.
ai.example.ini is a suggested profile for AI assistants:
44 commands for everyday questions about devices, alerts, SDTs, collectors and
websites, leaving out anything that exposes users, API tokens, contact details,
integration secrets or device configurations, with the reasons in comments.
Copy it to ~/.config/logicmonitor/credentials/ai.ini and adjust. elm --list
ignores any *.example.ini copied into that directory.
This is a guard rail, not a security boundary: someone with a shell can use a
different profile. What limits access is the API token's role in LogicMonitor,
so give a restricted profile a token whose role matches.
Install in PATH
Run make install to build the binary and copy it to ~/bin. If ~/bin is
not in your PATH, see the steps under Quick Start above.
Development
After cloning, install the git hooks:
make hooks
This sets up a pre-commit hook that automatically regenerates the README
table of contents when README.md is staged for a commit.
Make any changes to the Makefile or templates in the _jnja/ directory.
Files in _cmds and _defs may be overwritten during builds.
After changing any CLI options in _jnja/elm.py.j2, run the full build
cycle followed by make docs to keep the elm --help output in the
Usage section in sync:
make clean && make && make install && make docs
Swagger specs and generated commands
Two swagger specs are committed at the repo root. Both are raw swagger
documents — same shape, a top-level paths object:
| File | What it is |
|---|
swagger.documented.json | Snapshot of LogicMonitor's official published spec |
swagger.undocumented.json | Hand-maintained endpoints missing from the official spec, plus re-declarations of endpoints the official spec gets wrong |
Don't confuse these with the commands.*.json files the build derives from
them: those are the stripped form, keeping only the fields elm needs
(command name, path, summary, tag, options).
swagger.documented.json ─┐
├─→ _defs/commands.*.json ─→ _defs/<Command>.json ─→ _cmds/<Command>.py
swagger.undocumented.json ─┘ ↑
elm-notes.yaml + swaggers ─→ mkinfo.py (adds the --info text)
As of the current snapshots that is 174 documented + 19 undocumented = 193
commands, rendering to 180 modules. The gap is deliberate: 13 command names
appear in both specs, and the undocumented one wins because it is written
second. That is how the undocumented file patches the official spec — for
example ActionChainsList and ActionRulesList are re-declared there to add
the size/offset/filter parameters LogicMonitor's spec omits.
make never downloads anything. _defs/swagger.json is just a copy of the
committed snapshot, so builds are reproducible and work offline.
elm targets LM REST API v3 only (sent as X-Version: 3); building with
make apiversion= set to anything but 3 fails with an error.
Refreshing the official spec
make swagger
That downloads the spec, checks it really is a swagger document, and
pretty-prints it over the snapshot. Review and rebuild:
git diff --stat swagger.documented.json
make clean && make && make install
An empty diff means upstream has not changed since the snapshot was taken.
If the download fails, LogicMonitor is serving the spec from behind a
Cloudflare bot challenge again — it returns an HTML interstitial instead of
JSON, and only a real browser can complete the check (a browser User-Agent
does not help; it is a JavaScript challenge). This blocked make swagger
between 2026-08-16 and some point before 2026-09-11. Should it return, fetch
https://www.logicmonitor.com/swagger-ui-master/api-v3/dist/swagger.json in a
browser, save the JSON, and install it with:
make swaggerfile FILE=~/Downloads/swagger.json
make swaggerfile is the second half of make swagger without the download,
and it needs no network at all. It validates and pretty-prints the file into
place, refusing anything that is not the spec you meant rather than
overwriting the snapshot with it: a saved Cloudflare interstitial (not JSON —
and it says so), JSON with no paths, a spec that is not API v3, or a file
that has lost more than a quarter of its endpoints, which is what a truncated
or partial save looks like. It prints the endpoint-count delta
(paths: 220 -> 221 added 1, removed 0) before writing, and replaces the
snapshot only once every check passes.
The snapshot is stored pretty-printed so that diff is readable. Upstream
serves it minified onto a single line, so committing it verbatim would make
every refresh one unreadable ~800 KB diff. Pretty-printed, git diff shows
precisely which endpoints and parameters LogicMonitor changed — and therefore
which elm commands are about to change.
Committing the result needs LEAK_SCAN_SKIP=1. LogicMonitor's spec documents
a private (RFC 1918) address range as the example value for the netscan
subnet field, and the pre-commit leak scan cannot tell that from a real
internal range. The snapshot must stay a verbatim copy of upstream — edit it to
please the scanner and you have defeated the point of diffing it.
Quick code testing loop
While testing, a useful loop:
make clean && make && make install && echo done
Tools
The tools/ directory holds standalone helper scripts built on top of elm —
handy utilities, reports, and checks that came out of real-world use. They are
out of scope of the elm program itself: not part of the CLI, and not built or
installed by make. To keep this README focused on elm they are documented
separately in tools/README.md, not here.
Usage
Usage: elm [OPTIONS] COMMAND [ARGS]...
A cli interface for extracting LogicMonitor data via the api
Default config: ~/.config/logicmonitor/credentials/config.ini
Use -l/--list to show available credential profiles.
AI assistants: run 'elm --ai' for a quick-start guide.
See https://github.com/rdmarsh/elm for more information
Options:
--config FILE Read configuration from FILE.
--ai Print quick-start guide for AI assistants and exit
-l, --list List available credential profiles and exit
-p, --profile NAME Credentials profile name, shorthand for --config
~/.config/logicmonitor/credentials/<NAME>.ini.
Comma-separated names (a,b) run the command on each
-e, --explode FIELD One row per item of this list field, its keys as
FIELD.key columns. Repeat only for a list inside it
(-e a -e a.b)
-t, --localtime Show epoch times in the results as local times
(2026-10-28 16:39:54 AEDT)
-d, --diff With several profiles: show only the rows that are
not the same on all of them
-i, --access_id TEXT API token access id
-k, --access_key TEXT API token access key
-a, --account_name TEXT LogicMonitor account (company) name
-s, --proxy <HOST PORT> Socks5 proxy address and port
-f, --format FORMAT Output format: csv, tsv, json, jsonl, prettyjson,
xml, prettyxml, html, prettyhtml, gfm, pipe, jira,
latex, md, rst, tab, values, raw, txt, api, curl,
wget, sqlite [default: json]
-H, --noheader Hide the column headers [default: False]
-I, --index Show the row indices [default: False]
-o, --filename FILE Output to file name [default: -]
--head TEXT Text to prepend before the output
--foot TEXT Text to append after the output
-v, --verbose Be more verbose, -v is INFO, -vv is DEBUG
--halt-on-api-error Halt on API response errors
--cacert FILE Path to CA certificate bundle for SSL verification
-V, --version Show the version and exit.
-h, --help Show this message and exit.
Commands:
AccessGroupById Get access group by id
AccessGroupList Get access group list
ActionChainById Get action chain by id
ActionChainsList Get action chains list
ActionRuleById Get action rule
ActionRuleStatusById Get action rule status
ActionRulesList Get action rules list
AdminById Get user
AdminGroupById Get user group by id
AdminGroupList Get user group list
AdminList Get user list
AlertById Get alert
AlertList Get alert list
AlertListByDeviceGroupId Get device group alerts
AlertListByDeviceId Get alerts
AlertRuleById Get alert rule by id
AlertRuleList Get alert rule list
AllLogPartitions Retrieve a list of all log partitions
AllSDTListByDeviceId Get sdts for a device
AllSDTListByWebsiteGroupId Get a list of sdts for a website group
(response may contain extra fields depending
upon the type of sdt)
ApiTokenList Get a list of api tokens across users
ApiTokenListByAdminId Get api tokens for a user
AppliesToFunctionById Get applies to function by id
AppliesToFunctionList Get applies to function list
AssociatedDeviceListByDataSourceId
Get devices associated with a datasource
AuditLogById Get audit log by id
AuditLogList Get audit logs
AwsAccountId Get aws account id
AwsExternalId Get aws external id
CollectorAgentLogLevelByComponent
Get collector agent log level by component
CollectorAgentLogLevels Get collector agent log levels
CollectorById Get collector
CollectorDownloadTokenById Get collector download token
CollectorEvents Get collector events
CollectorGroupById Get collector group
CollectorGroupList Get collector group list
CollectorInstaller Get collector installer
CollectorList Get collector list
CollectorLogFileByName Get collector log file
CollectorLogFiles Get collector log files
CollectorStatusCheck Get collector status check
CollectorUpgradeHistory Get collector upgrade history list
CollectorVersionList Get collector version list
CollectorsByGroupId Get collectors by collector group id
ConfigSourceById Get config source by id
ConfigSourceList Get config source list
ContractInfoByCompany Get contract info by company
DashboardById Get dashboard
DashboardGroupById Get dashboard group by id
DashboardGroupList Get dashboard group list
DashboardList Get dashboard list
DataSourceOverviewGraphById Get datasource overview graph by id
DataSourceOverviewGraphList Get datasource overview graph list
DatasourceById Get datasource by id
DatasourceList Get datasource list
DebugCommandResult Get the result of a collector debug command
using sessionid
DeltaDevices Get delta devices using deltaid
DeltaIdWithDevices Get filter matched devices with new deltaid
DeviceById Get device by id
DeviceConfigSourceConfigById Get a config for a device
DeviceConfigSourceConfigList Get detailed config information for the
instance
DeviceDatasourceById Get device datasource
DeviceDatasourceDataById Get device datasource data
DeviceDatasourceInstanceAlertSettingById
Get device instance alert setting
DeviceDatasourceInstanceAlertSettingListOfDSI
Get a list of alert settings for a device
datasource instance
DeviceDatasourceInstanceAlertSettingListOfDevice
Get a list of alert settings for a device
DeviceDatasourceInstanceById Get device instance
DeviceDatasourceInstanceData Get device instance data
DeviceDatasourceInstanceGraphData
Get device instance graph data
DeviceDatasourceInstanceGroupById
Get device datasource instance group
DeviceDatasourceInstanceGroupList
Get device datasource instance group list
DeviceDatasourceInstanceGroupOverviewGraphData
Get device instance group overview graph
data
DeviceDatasourceInstanceList Get device instance list
DeviceDatasourceInstanceSDTHistory
Get device instance sdt history
DeviceDatasourceList Get device datasource list
DeviceEventsourceList Get device eventsource list
DeviceGroupById Get device group
DeviceGroupClusterAlertConfById
Get cluster alert configuration by id
DeviceGroupClusterAlertConfList
Get a list of cluster alert configurations
for a device group
DeviceGroupDatasourceAlertSetting
Get device group datasource alert setting
DeviceGroupDatasourceById Get device group datasource
DeviceGroupDatasourceList Get device group datasource list
DeviceGroupList Get device group list
DeviceGroupPropertyByName Get device group property by name
DeviceGroupPropertyList Get device group properties
DeviceGroupSDTList Get device group sdts
DeviceInstanceGraphDataOnlyByInstanceId
Get device instance data
DeviceInstanceList Get device instance list
DeviceList Get device list
DevicePropertyByName Get device property by name
DevicePropertyList Get device properties
DiagnosticRemediationAssignedSources
List assigned diagnostic and remediation
exchange modules
DiagnosticRemediationExecutionResults
Get diagnostic and remediation execution
results (canonical)
DiagnosticSourcesById Get diagnostics sources by id
DiagnosticSourcesList Get diagnostics sources list
EscalationChainById Get escalation chain by id
EscalationChainList Get escalation chain list
EventSourceById Get event source by id
EventSourceList Get event source list
ExternalApiStats Get external api stats info
FocusCostUsage Focus cost and usage shaped usage export
ImmediateDeviceListByDeviceGroupId
Get immediate devices under group
ImmediateWebsiteListByWebsiteGroupId
Get a list of websites for a group (response
may contain extra fields depending upon the
type of check { pingcheck | webcheck} being
added)
IntegrationAuditLogs Get integration audit logs list
IntegrationList Get integration list
JobMonitorById Get jobmonitor by id
JobMonitorList Get jobmonitor list
LogAlertGroupById Retrieve a logalertgroup by id
LogAlertGroupsList Retrieve all logalertgroups
LogAlerts Retrieve all logalerts
LogAlertsById Retrieve a logalerts by id
LogQueriesByGroupId Get log queries by group id
LogQueryGroupById Get log query group by id
LogQueryGroupList Get log query group list
LogQueryGroupListByGroupType Get log query groups by grouptype
LogSourceById Get log source
LogSourceList Get log source list
MetricsSummary Get metrics usage with company settings
summary
MetricsUsage Get metrics usage
NetflowEndpointList Get netflow endpoints
NetflowFlowList Get netflow flows
NetflowPortList Get netflow ports
NetscanById Get netscan by id
NetscanList Get netscan list
OIDList Get oids list
OidById Get oid by id
OpsNoteById Get opsnote by id
OpsNoteList Get opsnote list
PartitionById Retrieve details of a specific log partition
PortalInfo Get portal info
PropertyRulesById Get property rules by id
PropertyRulesList Get property rules list
RecipientGroupById Get recipient group by id
RecipientGroupList Get recipient group list
RecommendationById Get recommendation by id
RecommendationCategoriesList Get recommendation category list
RecommendationsList Get recommendation list
RemediationSourcesById Get remediation sources by id
RemediationSourcesList Get remediation sources list
ReportById Get report by id
ReportGroupById Get report group by id
ReportGroupList Get report group list
ReportList Get report list
ReportUsingTaskId Get report for task id
RetentionList Retrieve the list of log retentions
RoleById Get role by id
RoleGroupById Get role group by id
RoleGroupList Get role group list
RoleList Get role list
SDTHistoryByDeviceDataSourceId Get sdt history for the device datasource
SDTHistoryByDeviceGroupId Get sdt history for the group
SDTHistoryByDeviceId Get sdt history for the device
SDTHistoryByWebsiteGroupId Get sdt history for the website group
(response may contain extra fields depending
upon the type of sdt)
SDTHistoryByWebsiteId Get sdt history for the website (response
may contain extra fields depending upon the
type of sdt)
SDTList Get sdt list
SdtById Get sdt by id (response may contain extra
fields depending upon the type of sdt of
given id)
SiteMonitorCheckPointList Get website checkpoint list
TopTalkersGraph Get top talkers graph
TopologySourceById Get topologysource by id
TopologySourceList Get topologysource list
TrackedQueryGroupById Get tracked query group by id
TrackedQueryGroupList Get tracked query group list
UnmonitoredDeviceList Get unmonitored device list
UpdateReasonListByConfigSourceId
Get update history for a configsource
UpdateReasonListByDataSourceId Get update history for a datasource
V4Metadata Get metadata
WebsiteAlertListByWebsiteId Get alerts for a website
WebsiteById Get website by id
WebsiteCheckpointDataById Get data for a website checkpoint
WebsiteDataByGraphName Get website data by graph name
WebsiteGraphData Get website graph data
WebsiteGroupById Get website group
WebsiteGroupList Get website group list
WebsiteList Get website list
WebsitePropertyListByWebsiteId Get a list of properties for a website
WebsiteSDTListByWebsiteId Get a list of sdts for a website
WidgetById Get widget by id
WidgetDataById Get widget data (based upon widget type the
response may contain additional attributes.
please refer models corresponding to
specific widget type at the bottom of this
page to check the attributes)
WidgetList Get widget list
WidgetListByDashboardId Get widget list by dashboardid
Flag position matters. Global flags go before the command name,
per-command flags after it. Three short flags are reused on both sides with
different meanings, so position changes what the flag does:
| Flag | Before COMMAND (global) | After COMMAND (per-command) | If misplaced |
|---|
-f | --format FORMAT | --fields FIELD,... | Errors both ways (invalid choice / no valid fields selected) |
-s | --proxy <HOST PORT> | --size N | Errors, but names --proxy and complains the command name is not an integer -- -s takes two values |
-o | --filename FILE | --offset N | Silent. Exits 0, writes a file named after the offset, returns page 1 |
elm -f csv DeviceList -s 1000 -o 2000 # correct: format global, size/offset per-command
elm DeviceList -f csv -s0 # error: -f here is --fields
elm -o 2000 DeviceList # runs, with a warning: page 1 goes to a file named 2000
A misplaced flag fails with a Hint: line saying which side of the command
name it belongs on. The exception is -o with a number before the command
name: that is valid syntax for writing to a file, so elm only warns. A
pagination loop with -o on the wrong side re-fetches page 1 every iteration,
so keep -s and -o after the command name. -F, -S, -c and -C are
per-command only; -H, -I and -p are global only.
Counting records: -C is almost always the one you want. It asks the LM
API for the total number of records matching your filter, and is not limited
by -s. -c counts only the rows the current request returned, so it is
really min(-s, matches) -- with more matches than fit in a page it just
echoes your page size, and a -c result equal to -s means "at least this
many", not "exactly this many". Most list endpoints return an exact count with
-C. For AlertList and AuditLogList the LM API cannot compute an exact
total, so -C shows a lower bound like >50 with a warning; for those two
only, -c -s0 counts the rows actually fetched, which is accurate provided
the true total is under 1000.
Several portals at once
Give -p several profiles, separated by commas, to run the same query on each
portal. The rows come back as one table, with profile and account_name
columns first:
$ elm -p prod,preprod -f csv DeviceGroupList -f name,appliesTo
profile,account_name,name,appliesTo
prod,acme,Linux Servers,isLinux()
prod,acme,Old Stuff,false
prod,acme,Windows Servers,isWindows()
preprod,acmepreprod,Linux Servers,isLinux() && !isK8s()
preprod,acmepreprod,Windows Servers,isWindows()
profile is always unique, while two profiles can point at the same account
(say, two tokens with different roles), so profile is the one to select on.
In JSON both are keys on every record: jq 'select(.profile=="prod")' picks
out one portal. -c and -C give one count (or total) row per portal.
-d / --diff shows only the rows that are not identical on every
portal: what is left is what is out of step. Here Windows Servers matches, so
it is dropped. A row shown for every portal
means its values differ; a row shown for some portals is missing from the
others.
$ elm -p prod,preprod -d -f csv DeviceGroupList -f name,appliesTo
profile,account_name,name,appliesTo
prod,acme,Linux Servers,isLinux()
prod,acme,Old Stuff,false
preprod,acmepreprod,Linux Servers,isLinux() && !isK8s()
Choose the fields to compare with -f: fields such as id always differ
between portals (elm warns if -f is missing). Like diff, it exits 0 when
the portals match (printing "No differences" to stderr), 1 when they differ,
and 2 when it could not compare everything: a portal could not be read, or
there were more rows than one request fetches (1000 at most, with -s0) and
no difference was found in the rows that were. Narrow with -F in that case. Lists inside a record are compared
whole, so the same entries in a different order count as different.
-o FILE writes one file per portal, named <profile>-FILE in the same
directory, each without the profile and account_name columns: the same
file -p NAME would write. diff prod-groups.csv preprod-groups.csv then works directly.
Each profile uses its own credentials, so -i, -k, -a and --config
cannot be combined with several profiles. Every profile must allow the
command (see Restricting a profile),
or nothing is sent to any of them. If one portal fails, the others' rows are
still printed and elm exits 1 (--halt-on-api-error stops at the first
failure). With -f api, curl or wget, each portal's request follows a
# <profile> line.
examples/comparing-portals.md has recipes for
users, roles, alerting, groups, collectors and LogicModules, and a table tool
(tools/portal-matrix.py) that puts each portal in its own column.
Nested fields: -e and dotted -f
Some fields hold a list of records: a role's privileges, a portal's
contacts, a device's customProperties. In csv or a table they come out as
one unreadable cell. -e FIELD (before the command name) gives one row per
item instead, with the record's other fields repeated and the item's keys as
FIELD.key columns:
$ elm -e privileges -f csv RoleList -f name,privileges
name,privileges.objectType,privileges.objectId,privileges.objectName,privileges.operation,privileges.subOperation
helpdesk,host_group,12,Linux Servers,read,
helpdesk,setting,opsnote,opsnote,read,
empty,,,,,
A role with no privileges keeps its row, blank. -c counts the rows after
exploding (elm -e contacts PortalInfo -f contacts -c counts the contacts);
-C is still LM's total of records. A field holding a single record rather
than a list (such as installationMetadata) is flattened into FIELD.key
columns on the same row.
A dotted name in -f picks part of a nested field. elm asks LM for the
whole field and trims it afterwards, with or without -e:
elm -e privileges -f csv RoleList -f name,privileges.objectName,privileges.operation
elm COMMAND --info lists the names under each nested field (the
privileges.: line). With several portals and
-d, this compares items one by one, and leaves out sub-fields such as
privileges.objectId that hold portal-specific ids and would make every row
differ. Without -e, -d compares a list whole, so the same items in another
order count as different.
-e takes one list per run. Exploding two separate lists, such as
customProperties and systemProperties, would pair every item of one with
every item of the other, so elm refuses it: run once per list. It repeats only
for a list inside another: -e groups -e groups.members.
Command info
elm COMMAND --info describes one command without calling the API or needing
credentials:
- its path, usage and parameters
- notes from
elm-notes.yaml: tested behaviour, known API
bugs (for example filters the API silently ignores), corrected field meanings
and example commands
- every response field with its type and a one-line description from the
swagger
elm AlertList --info
elm DeviceDatasourceList --info # works without the required --deviceId
Where a note and a swagger description disagree, the note is the tested one.
The text is built into each command at make time (by mkinfo.py), so the
installed binary needs no extra files. It is written to be short, so it is also
the cheapest way to give an AI assistant what it needs about a command.
Times and dates: elm works out the epochs, so nobody has to.
With "now" at Wed 28 Oct 2026 14:30:
| You write | elm sends |
|---|
startEpoch>:now-1h | >: 28 Oct 13:30 (s m h d w M; m minutes, M months) |
startDateTime<:now+7d | <: 4 Nov 14:30 |
startEpoch:now/d | >: 28 Oct 00:00 and < 29 Oct 00:00 (today) |
startEpoch:now-1M/M | >: 1 Sep and < 1 Oct (last month; /w is a week) |
startEpoch:2026-07 | >: 1 Jul and < 1 Aug (also 2026, 2026-07-14, 2026-07-14T09:30) |
startEpoch>:now-1M/M | >: 1 Sep (from the start of the period) |
startEpoch<:now-1M/M | < 1 Oct (up to its end) |
/d /w /M and dates are periods. : means all of it; >: and < use
its start, > and <: its end, as in Elasticsearch and Grafana date maths.
Times are local, daylight saving included (set TZ for another zone). Every
form, with what it sends:
examples/filtering.md.
elm AlertList -F 'cleared:false,startEpoch>:now-1h' # started in the last hour
elm AlertList -F 'startEpoch:now-1M/M' # last calendar month
elm SDTList -F 'startDateTime<:now+7d' # SDTs starting in the next week
A few fields hold milliseconds, not seconds (SDT startDateTime, AlertList
lastUpdatedOnEpoch), and the swagger rarely says which. So when a filter has
a time in it, elm first asks LM for one value of that field: above 10^11 it
can only be milliseconds, and elm sends the time in milliseconds. That costs one
extra request per field, and none otherwise.
-t (--localtime) shows epochs in the results as local times. A field is converted when
its name ends like a time (startEpoch, createdOn) and its value is a
plausible one, seconds or milliseconds, so upTime and a 0 ("never") stay
numbers. The column keeps its name, so it matches what you put in -f:
$ elm -t -f txt AlertList -F 'cleared:false,startEpoch>:now-1h' -f startEpoch,endEpoch,monitorObjectName
monitorObjectName endEpoch startEpoch
web01 0 2026-10-28 16:53:06 AEDT
The same field list guards -F: a filter on a field the swagger does not list
for that command is refused before anything is sent, because the API would
quietly ignore it (AlertList returns every alert) or match nothing
(DeviceList). A dotted field is checked by the part before the dot.
$ elm AlertList -F sevrity:4
Error: Invalid value for '--filter' / '-F': no field 'sevrity' in AlertList (did you mean severity? elm AlertList --info lists them); LM would ignore it or match nothing, without an error
DeviceList help
Every command has its own help, and they all share this shape: the API path it
maps to, a Swagger URL that opens LogicMonitor's documentation for that exact
endpoint, and the standard flags. List commands also print the full -F
filter operator table, as below.
elm DeviceList --help
Usage: elm DeviceList [OPTIONS]
Get device list
API Path:
/device/devices
Swagger URL:
https://www.logicmonitor.com/swagger-ui-master/api-v3/dist/#/Devices/getDeviceList
Options:
--end INTEGER
--netflowFilter TEXT
--start INTEGER
--includeDeletedResources / --dont-includeDeletedResources
-f, --fields FIELD,... Only include the listed fields
-s, --size INTEGER Quantity of results returned. [0-1000
inclusive, '0' returns all results (up to
1000)] [default: 50]
-o, --offset INTEGER Display results starting from offset
[default: 0]
-F, --filter FIELD[>:,<:,>,<,!,:,~,!~]VALUE,...
Filter by field, operator and value.
Separate multiple filters with a comma.
Escape commas in field searches with a
backslash. Backslash and operators may need
escaping or quoting depending on the shell
used.
Operators:
>: - Greater than or equals
<: - Less than or equals
> - Greater than
< - Less than
!: - Does not equal
: - Equals
~ - Includes
!~ - Does not include
-S, --sort [+,-]FIELD,... Sort by field; inc (+), dec (-)
-c, --count Count rows returned by this query (limited
by -s, max 1000)
-C, --total Count all rows matching -F (LM's total; not
limited by -s)
--info Show fields, verified notes and example
commands, then exit
-h, --help Show this message and exit.
Examples
See EXAMPLES.md for the full index, or jump directly to a topic:
- General usage - flags, output formats, piping, writing to file
- Devices - OS filtering, custom/system properties, group membership
- Collectors - health reports, build versions, auto-balance, backup pairs
- Alerts and SDTs - long SDTs, oldest alerts, time-related alerts
- Datasources - finding devices without a datasource applied
- Users - export by id, status checks, offboarding
- Websites - group hierarchy queries, missing required properties
- Dashboards and reports - filtering by resource group or hostsVal
- Comparing portals - several portals side by side, which one is out of step
Errors
See ERRORS.md
Contributing
To contribute, please fork the repository and use a feature branch. Pull
requests are welcome. See CONTRIBUTING.md for more
details.
This project adheres to the Contributor Code of Conduct.
By participating, you agree to abide by its terms. See
CODE_OF_CONDUCT.md
Links
Licensing
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details
You should have received a copy of the GNU General Public License
along with this program. If not, see https://www.gnu.org/licenses/
Note: LOGICMONITOR is a trademark of LogicMonitor, Inc. and not
affiliated with this project
meta
Update the ToC on this page by running the following:
gh-md-toc --insert --no-backup --hide-footer --skip-header README.md
