This is the documentation for the development version. There are no official binaries for it; build it from the source code in git. Download links on these pages work only after the release. For the current release, see version 7.0.

NetXMS Shell (nxshell)

nxshell is an interactive command line shell for the NetXMS server. Under one prompt it lets you move through the object tree, run server debug console commands, talk to the AI assistant, and run NXSL code on the server, and you can add your own commands written in NXSL. It can also run commands from a file or a pipe, for use in shell scripts.

nxshell connects to the server through the web API, so it needs no access to the server’s client port; the server’s web API must be enabled and reachable (see Enabling the API).

This nxshell is not the Jython-based NXShell scripting client of earlier versions, which was removed in 7.0; it only has the same name. Scripts that used the Jython-based NXShell are rewritten to use the REST API, directly or through a small wrapper (see Python Wrapper Example).

The same program installed as nxai starts directly in AI assistant mode; see How to Use the Command-Line Client.

Installing

nxshell and nxai are part of the NetXMS command line client tools:

  • On Linux, install the netxms-client package from the NetXMS repositories (see Linux Installation).

  • On Windows, select the Command Line Tools component in the NetXMS installer (see Windows Installation).

Connecting

nxshell -s https://netxms.example.com:8443 -u admin

The shell asks for the password if it is not given with -p and the input is a terminal. -s takes a URL or a host name. Without a scheme, the shell uses https://, and without a port, the default port of the scheme (443 for HTTPS), which suits a server behind a reverse proxy. To reach the server’s own web API listener, give its port, for example netxms.example.com:8443, or http://netxms.example.com:8000 for the plain HTTP listener. The environment variables NETXMS_SERVER, NETXMS_USER, and NETXMS_PASSWORD supply defaults for -s, -u, and -p. For a server with a self-signed certificate, add --no-verify-ssl.

After a successful login, the shell saves the session token in sessions.json in its configuration directory and reuses it for four hours, so you do not give the credentials on every start. The file is readable only by the current user, and nxai shares it. The saved session belongs to the server URL, not to the user: to connect as another user, use --clear-session first or --no-save-session. --no-save-session neither reads nor saves the token, and --clear-session deletes the saved session for the server and exits; the token stays valid on the server until it expires. The shell does not support two-factor authentication.

The configuration directory is $XDG_CONFIG_HOME/nxshell if XDG_CONFIG_HOME is set, otherwise ~/.config/nxshell, and %APPDATA%\nxshell on Windows. It also holds the startup file (nxshellrc) and the command history (history, last 200 commands). Command history, line editing, and Tab completion are available where the shell is built with the libedit library; the Windows version reads plain lines.

Moving Through the Object Tree

The shell has a current object, shown in the prompt. NXSL code and your own commands run in its context, and the AI assistant uses it as conversation context. At the top level (/) there is no current object; ls / lists the objects that have no parent you can access, such as Entire Network and Infrastructure Services. ls shows the ID, class, status, and name of each child object.

netxms.example.com:/> ls
       1  Network      Normal     Entire Network
       2  ServiceRoot  Normal     Infrastructure Services
netxms.example.com:/> cd Infrastructure Services/Core/router1
netxms.example.com:/Infrastructure Services/Core/router1> cd ..
netxms.example.com:/Infrastructure Services/Core> pwd
/Infrastructure Services/Core
  • Path elements are object names, matched without regard to case. A path that starts with / is absolute, otherwise it is relative to the current object; .. is the parent.

  • Spaces in names need no quotes. Write / within a name as \/ (for example cd Gi0\/1) and \ as \\.

  • cd alone goes to the top level, and cd - returns to the previous location.

  • cd #<id> selects an object by ID, and cd @<name> searches the names and aliases of all objects; an exact name wins, otherwise the shell asks which of the matches to select. Use cd #<id> also when several child objects have the same name.

  • Tab completes command names and object names in cd and ls.

To start in a given object, use -o <id> or -n <name> on the command line. -n takes the first object whose name or alias contains the text, without asking, so use -o in scripts.

Running NXSL, Console Commands, and AI Questions

Three commands send their text to a target on the server:

Command Target

nxsl <code>

Runs NXSL code in the context of the current object ($object, and $node for a node)

console <command> (or con)

Runs a server debug console command

ai <message>

Sends a message to the AI assistant

= <expression> evaluates an NXSL expression and prints the result:

netxms.example.com:/Infrastructure Services/Core/router1> = $node.ipAddr
10.0.0.1
netxms.example.com:/> console show pollers
netxms.example.com:/> ai why is router1 unreachable?

Script output is shown as it is produced; a returned value other than null is printed after it, arrays and hash maps as JSON. Each input runs as a separate script, so variables are not kept between inputs. Ctrl+C stops a running script. For a console command, Ctrl+C only stops waiting for the output; the command keeps running on the server.

Access rights:

  • NXSL code and aliases for an object need the Execute scripts access right on the object; at the top level, the Manage script library system access right (see Scripting Overview).

  • Console commands need the Access server console system access right.

  • AI assistant messages need the Use AI assistant system access right.

  • Navigation shows only the objects you have read access to.

Modes

nxsl, console, and ai without text switch the shell to that mode: every line goes to that target, and the prompt shows the mode. A line that starts with / followed by a letter or = is still a shell command, so you can navigate without leaving the mode; other lines, including NXSL comments that start with //, go to the target. /exit or Ctrl+D returns to the shell.

netxms.example.com:/> console
netxms.example.com:/ console> show flags
netxms.example.com:/ console> /cd Infrastructure Services
netxms.example.com:/Infrastructure Services console> /exit
netxms.example.com:/Infrastructure Services>

In NXSL mode, input continues on the next line until all brackets are closed. In AI assistant mode, /clear clears the chat history and /incident <id> sets an incident as conversation context (/incident alone clears it).

Adding Your Own Commands

An alias is a command written in NXSL. It runs in the context of the current object and gets its arguments as $1, $2, and so on, or as the array $ARGS:

alias up = return $node.status == 0;

alias uptime {
   println($node.name .. " is up since " .. DateTime($node.bootTime).format("%Y-%m-%d %H:%M"));
}

alias lists the aliases, alias <name> shows one, and unalias <name> removes it. The shell has four default aliases, which an alias with the same name replaces:

Alias Prints

info

Name, ID, class, status, alias, address, and comments of the current object

alarms

ID, severity, and message of the active alarms of the current object and the objects below it

dci [<filter>]

ID, description, and current value of the single-value DCIs of the current object (at the top level, of all objects you can access); the optional filter matches the description, with * and ? wildcards

interfaces

Index, operational state, and name of the interfaces of the current node

Built-in commands cannot be replaced.

An alias defined at the prompt is kept until the shell exits. To keep it, put it into the startup file nxshellrc in the configuration directory, which the shell runs at every start with the same syntax as interactive input. A failed command in the startup file is reported and does not stop the shell from starting.

Using nxshell in Scripts

Commands can come from -c options (one command each), from a file, or from standard input:

nxshell -c 'cd /Infrastructure Services/Core/router1' -c 'alarms'

nxshell -n router1 -c '= $node.interfaces.size'

nxshell maintenance.nxsh

echo 'console show queues' | nxshell > queues.txt

Commands from the startup file run first, as in an interactive session. Execution stops at the first failed command. When the output is redirected, it is plain text without colors, and status messages go to standard error, so the output can be processed by other tools; --plain forces plain output on a terminal too. Lines that start with # are comments in shell mode; after a line that switches to another mode, they go to that target like any other line.

Exit code Meaning

0

All commands completed successfully

1

A command failed (unknown command, object not found, script error, access denied) or the command line is invalid

2

Cannot connect to the server or authentication failed

The server debug console does not report command failures, so a console command counts as successful once it reaches the server. The exit code reflects only commands given with -c, in a file, or on standard input: errors in an interactive session and in the startup file do not change it.

For automation that goes beyond running commands, such as changing objects in bulk or exporting collected data, use the REST API.

Command Summary

Command Description

cd [<path> | #<id> | @<name> | -]

Change the current object

ls [<path>]

List child objects

pwd

Show the path to the current object

ai [<message>]

Send a message to the AI assistant, or switch to AI assistant mode

console [<command>], con [<command>]

Run a server debug console command, or switch to console mode

nxsl [<code>]

Run NXSL code, or switch to NXSL mode

= <expression>

Evaluate an NXSL expression and print its value

alias [<name> [= <code> | { <code> }]]

List, show, or define aliases

unalias <name>

Remove an alias

status

Show information about the current session

help

List the commands

exit, quit

Leave the current mode or exit the shell

For the command line options, see nxshell in the CLI tools reference.

Troubleshooting

Cannot connect

Check that the server’s web API is enabled and that the firewall allows its port. Give the server as a URL with scheme and port, for example nxshell -s https://netxms.example.com:8443: without them, the shell connects to port 443.

Certificate error

The server uses a certificate that the client does not trust, for example a self-signed one: use --no-verify-ssl.

Authentication fails

Check the user name and password, and delete the saved session with nxshell -s <server> --clear-session.