Command Line Action
Command Line Action executes one-shot operating system commands from Banalytics automation and captures stdout, stderr, and exit code as the completed action result.
Run short OS commands from rules and action chains
Use Command Line Action when Event Manager rules, manual operator controls, or action groups need to call a local operating-system command, script, diagnostic utility, or vendor command-line tool.
Keep this action focused on commands that finish by themselves. For long-running services, interactive processes, stdin/stdout sessions, restarts, or protocol bridges, use Process instead.
Name the action clearly
Set Title to the purpose of the command, for example disk health check, restart relay bridge, send CLI alert, or collect network status.
Use a short command or script
Put the command in Command line. For anything with complex quoting, pipes, redirects, or multiple shell operators, create a script and run that script.
Limit the wait time
Set Wait execution timeout (sec) to the time the action should wait before collecting command output. Use commands that complete predictably.
Configuration parameters
| Parameter | Required | Description | Default |
|---|---|---|---|
Title | Yes | Display name of the action. Use a name that makes the command purpose obvious in Event Manager rules, action groups, and history. | None |
Command line | Yes | Operating-system command or commands to execute. Each non-empty line is executed as a separate command. Use absolute paths for scripts and binaries when the agent runs as a service. | None |
Wait execution timeout (sec) | Yes | How long the action waits before collecting stdout, stderr, and exit code. Valid range: 1-300 seconds. The command should finish by itself; this setting is not a replacement for a process supervisor. | 10 |
Commands are launched as agent-side processes
Each non-empty line in Command line is executed separately. The action waits for the configured timeout, reads stdout and stderr as UTF-8 text, records the exit code, and returns that information as the completed action result.
The process runs as the same operating-system user as the Banalytics Agent. File paths, permissions, available tools, PATH lookup, and environment variables are therefore service-user dependent and can differ from an interactive terminal.
One-shot action
Designed for commands that run, produce output, and exit. It is not intended to supervise daemons or interactive sessions.
Captured result
Stdout, stderr, and exit code are included in the action result, so keep output short and avoid printing secrets.
Service context
The command inherits the agent process context. Test paths and permissions as the service user, especially on production devices.
Command targets and diagnostic workflows
Command targets
Simple health check
Run a short command such as ping, curl, df, free, ipconfig, or a vendor utility to verify that the operating system, network, disk, or external device is reachable. Keep output short because it is stored in the action result.
Local maintenance action
Execute a small script that rotates logs, clears a temporary folder, refreshes a cache, or calls a local backup helper. Prefer a script file for anything longer than a trivial command.
Device control through CLI tools
Call camera, relay, GPIO, UPS, modem, or industrial gateway utilities when the vendor exposes a command-line interface and the action should be triggered by Banalytics rules.
Integration bridge
Call a local script that forwards an event to another system over HTTP, MQTT, a message queue, or a proprietary CLI. Put protocol-specific complexity into the script and keep this action responsible only for launching it.
Diagnostics and command shape
Manual diagnostics
Create a temporary action for operator-run diagnostics, for example collecting version, disk, or network status. Remove sensitive diagnostics after troubleshooting.
Multi-step command list
Put several commands on separate lines when each step can be executed independently and the result of the previous command is not required by the next command through shell state.
Operational notes
It is not an interactive shell parser
Command line is split by line breaks first, then each line is split by spaces and launched directly. It is not parsed like an interactive shell command.
Use scripts for shell features
Pipes, redirects, glob expansion, environment variable expansion, &&, ||, and quoted arguments with spaces are not handled by the action itself. For complex commands, create a script and run that script, or explicitly invoke the platform shell.
Service user permissions apply
The command runs as the same operating-system user as the Banalytics Agent. Use absolute paths and verify that the service user can read files, execute scripts, and access required devices.
Timeout does not make a daemon safe
Wait execution timeout (sec) controls how long the action waits before collecting output, but long-running daemons still do not fit this action well. Use commands that finish by themselves.
Output can become history
Stdout and stderr are included in the action result. Avoid printing passwords, tokens, private keys, or large logs because the result can be stored in event history and shown to operators.
Prefer structured integrations for large output
Exit code and captured output are returned as text. Downstream logic should not rely on fragile parsing of large command output when a structured integration or Java action would be safer.
Treat commands as trusted code
A dangerous command can modify files, stop services, leak data, or affect the host operating system with the permissions of the agent process.