NETLOOM(1)

NAME
netloom - shared command-line interface for plugin-backed network APIs.

SYNOPSIS
netloom [GLOBAL-OPTIONS] MODULE SERVICE ACTION [KEY=VALUE ...]
netloom load [list|show|PLUGIN]
netloom server [list|show|use PROFILE]
netloom cache [clear|update]
netloom [--help|?]
netloom --version

DESCRIPTION
netloom provides a common CLI surface for vendor-specific network API plugins. The shared runtime handles plugin selection, profile switching, cache management, output formatting, logging, and generic request options. The exact modules, services, actions, and request fields available under netloom <module> <service> <action>, however, come from the active plugin and whatever API documentation that plugin discovers from the selected server. This manual is the shared reference. Provider-specific behavior belongs in plugin manuals such as netloom-clearpass(7).

BUILT-IN COMMANDS

netloom load <plugin>
    Persist the active plugin used by later plugin-backed commands.

netloom load list
    List installed or configured plugins.

netloom load show
    Show the currently selected plugin.

netloom server list
    List configured profiles for the active plugin.

netloom server show
    Show the current profile and the config files that affect it.

netloom server use <profile>
    Select the active profile inside the active plugin.

netloom cache update
    Refresh the local API catalog for the active plugin.

netloom cache clear
    Remove the cached API catalog for the active plugin.

COMMAND MODEL
The general plugin-backed form is:

    netloom <module> <service> <action> [--key=value ...]
Common action names include:

list
    List a collection. Often equivalent to get --all when the plugin exposes both.

get Retrieve one resource or, with --all, a collection.

add Create a resource.

update
    Patch an existing resource.

replace
    Replace an existing resource.

delete
    Delete an existing resource.

copy
    Copy matching resources from one profile to another when supported by the active plugin.

diff
    Compare matching resources between two profiles when supported by the active plugin. Modules, services, actions, selectors, and request metadata are discovered dynamically and may differ by plugin, server version, and enabled API surface.

PLUGINS
Plugins provide vendor-specific authentication, discovery, payload handling, normalization, and documentation while reusing the shared netloom runtime. At least one plugin must be selected before running plugin-backed commands:

    netloom load clearpass
For provider-specific examples, cache behavior, and authentication details, use the relevant plugin manual in addition to dynamic help.

GLOBAL OPTIONS

--log-level=LEVEL
    Set the runtime log level. Typical values are debug, info, warning, error, and critical.

--console
    Also print response output to the terminal.

--out=FILE
    Write output to an explicit file instead of using a generated default path.

--data-format=FORMAT
    Choose output format. Supported values are json, csv, and raw.

--csv-fieldnames=FIELDS
    Comma-separated field order for CSV output.

--file=FILE
    Load JSON or CSV input for write or bulk-style actions.

--api-token=TOKEN
    Use an existing bearer token instead of logging in through the plugin.

--token-file=FILE
    Read a bearer token from a file.

--catalog-view=visible|full
    Choose whether help, completion, and action discovery use the default visible catalog or the full retained discovered catalog.

--limit=N
    Set page size when supported by the endpoint.

--offset=N
    Set a collection offset when supported by the endpoint.

--sort=FIELD
    Set server-side sort when supported by the endpoint.

--filter=JSON|FIELD:OP:VALUE
    Set a server-side filter when supported by the endpoint.

--calculate-count=true|false
    Request a total-count style response when supported by the endpoint.

--encrypt=enable|disable
    Control masking of secret values in saved or logged output.

--decrypt
    Disable output masking and show secrets in output.

--help, ?
    Show context-aware help.

--version
    Show version.

FILTER EXPRESSIONS
When a plugin supports server-side filtering, netloom accepts either shorthand expressions or raw JSON expressions. Shorthand syntax uses:

    FIELD:OP:VALUE
Common operators include:

    equals
    not-equals
    contains
    in
    not-in
    gt
    gte
    lt
    lte
    exists
Common shorthand examples:

    --filter=name:equals:TEST
    --filter=name:contains:guest
    --filter=id:in:1,2,3
    --filter=enabled:exists:true
Equivalent JSON patterns commonly include:

    {"key":{"$eq":"value"}}
    {"key":{"$ne":"value"}}
    {"key":{"$contains":"value"}}
    {"key":{"$in":["value1","value2"]}}
    {"key":{"$nin":["value1","value2"]}}
    {"key":{"$gt":"value"}}
    {"key":{"$gte":"value"}}
    {"key":{"$lt":"value"}}
    {"key":{"$lte":"value"}}
    {"key":{"$regex":"regex"}}
    {"key":{"$exists":true}}
    {"key":{"$exists":false}}
    {"$and":[filter1,filter2]}
    {"$or":[filter1,filter2]}
    {"$not":{filter}}
For advanced cases, pass raw JSON such as:

    --filter='{"name":{"$contains":"guest"}}'
    --filter='{"$and":[{"status":{"$eq":"Known"}},{"enabled":{"$exists":true}}]}'
Shell quoting matters because JSON expressions are passed as strings.

CATALOG VIEWS
Some plugins retain more discovered metadata than they expose by default. When that happens, --catalog-view=visible shows the normal operator-facing subset, while --catalog-view=full shows the full retained discovery data. This affects dynamic help, completion, and command validation rather than just presentation. Typical troubleshooting flow:

    netloom --catalog-view=full ?
    netloom --catalog-view=full <module> <service> ?

OUTPUT
By default, netloom writes response files under its state and output directories. Default generated filenames include timestamps so repeated commands do not overwrite earlier artifacts. Supported output formats are:

json
    Pretty-printed JSON output.

csv CSV output for list-style data.

raw Raw text or binary output, commonly used for export and download endpoints. For binary responses, netloom may automatically select raw output and preserve the filename provided by the server.

ENVIRONMENT

NETLOOM_ACTIVE_PROFILE
    Default active profile for the selected plugin.

NETLOOM_VERIFY_SSL
    Enable or disable TLS certificate verification.

NETLOOM_TIMEOUT
    HTTP timeout in seconds.

NETLOOM_LOG_LEVEL
    Default log level.

NETLOOM_DATA_FORMAT
    Default output format.

NETLOOM_CONSOLE
    Enable console output by default.

NETLOOM_ENCRYPT_SECRETS
    Mask secret values by default.

NETLOOM_CACHE_DIR
    Override the cache directory.

NETLOOM_STATE_DIR
    Override the state directory.

NETLOOM_OUT_DIR
    Override the response output directory.

NETLOOM_APP_LOG_DIR
    Override the application log directory.

NETLOOM_CONFIG_DIR
    Override the base configuration directory. Plugin manuals may define additional provider-specific variables.

FILES

~/.config/netloom/config.env
    Stores the active plugin selection.

~/.config/netloom/plugins/<plugin>/
    Plugin-specific configuration root.

~/.cache/netloom/
    Default cache directory on Linux when XDG-style defaults are used.

~/.local/state/netloom/
    Default state directory on Linux when XDG-style defaults are used.

~/.local/state/netloom/responses/
    Default response output directory.

~/.local/state/netloom/logs/
    Default log directory.

COMPLETION AND HELP
Completion quality depends on the local API catalog. If module or service names look incomplete, refresh the cache:

    netloom cache update
Dynamic help is available at several levels:

    netloom ?
    netloom <module> <service> ?
    netloom <module> <service> <action> ?

BASH COMPLETION
The repository includes a Bash completion script at:

    scripts/netloom-completion.bash
Run it once for the current shell session:

    source /path/to/netloom/scripts/netloom-completion.bash
One simple persistent setup is:

    mkdir -p ~/.bash_completion.d
    cp /path/to/netloom/scripts/netloom-completion.bash ~/.bash_completion.d
Then load files from that directory in ~/.bashrc or the equivalent shell startup file:

    if [ -d "$HOME/.bash_completion.d" ]; then
      for f in "$HOME"/.bash_completion.d/*; do
        [ -r "$f" ] && source "$f"
      done
    fi
Completion quality depends on the local cache. If discovered modules or services look incomplete, run:

    netloom cache update

EXAMPLES
Select a plugin and refresh discovery metadata:

    netloom load clearpass
    netloom cache update
Switch the active profile:

    netloom server use dev
List resources through the active plugin:

    netloom identities endpoint list --limit=10
Inspect one object directly in the terminal:

    netloom policyelements network-device get --id=1001 --console
Use dynamic help for a discovered action:

    netloom policyelements network-device add ?

EXIT STATUS

0   Success.

non-zero
    Failure, invalid arguments, authentication failure, network failure, or API error.

SEE ALSO
netloom-clearpass(7), python(1), curl(1)