Mikrotik RouterOS CLI (and Node.js library)

MikroTik RouterOS CLI and Node.js library — execute commands via SSH or Telnet.

Execute RouterOS commands from your terminal, scripts, or AI agents.

Supports three connection methods:

• Direct SSH — encrypted alternative to Telnet, same commands and output (port 22)
• Direct Telnet — connect straight to the MikroTik device IP (port 23)
• Woobm USB serial console — connect via a Woobm USB-to-serial adapter (typically at 192.168.4.1, Telnet only)

Requirements

• A MikroTik device with SSH (port 22) or Telnet (port 23) enabled,
• or a Woobm USB dongle connected to MikroTik USB and to your computer via Wi-Fi.

Installation

Global CLI (recommended for terminal use):

npm install -g routeros-cli

Causes roscli command to be available globally.

Show help:

roscli --help

Run without installing (npx):

export MIKROTIK_PASSWORD=yourpassword
npx routeros-cli exec "/export terse" --host 192.168.88.1 --login admin --transport ssh

Configuration

Connection defaults are read from environment variables (if not specified as command line options). Using an .env file is supported.

MIKROTIK_HOST=192.168.88.1      # required — device IP or hostname
# MIKROTIK_HOST=192.168.4.1    # Woobm USB serial console
MIKROTIK_PORT=22                # 22 for SSH (default), 23 for Telnet
MIKROTIK_TRANSPORT=ssh          # ssh | telnet — auto-detected from port if port given; default: ssh
MIKROTIK_LOGIN=admin
MIKROTIK_PASSWORD=yourpassword
MIKROTIK_TIMEOUT=10             # command response timeout in seconds
MIKROTIK_CONNECT_TIMEOUT=15     # TCP / SSH handshake timeout in seconds

Any option can also be passed directly as command-line options (overriding the environment variables).

Command line options

| Option | Default | Description | | -------------------- | ----------------------------------------- | ------------------------------------ | | --host <ip> | MIKROTIK_HOST env (required) | Device IP or hostname | | --port <port> | MIKROTIK_PORT env / transport default | Port (23 for Telnet, 22 for SSH) | | --transport <type> | MIKROTIK_TRANSPORT env / auto from port | telnet or ssh | | --login <user> | MIKROTIK_LOGIN env / admin | Username | | --password <pass> | MIKROTIK_PASSWORD env / "" | Password | | --timeout <sec> | MIKROTIK_TIMEOUT env / 10 | Command response timeout in seconds | | --json | — | Output as JSON ({"output": "..."}) |

All options must be placed at the end of the command.

Security note: It is not recommended to pass sensitive options like a production --password directly as command-line options, as they may be visible in process lists. Use the MIKROTIK_PASSWORD environment variable or a .env file instead when possible.

Transport default — if neither --transport nor --port is set, SSH on port 22 is used. If only --port is given, the transport is inferred: port 22 → SSH, port 23 → Telnet. Any other port requires an explicit --transport.

CLI Usage

Execute a single command

# SSH (default)
roscli exec "/ip address print"
roscli exec "/export" --host 10.0.0.1

# Telnet — specify transport explicitly, or let auto-detection pick it from port 23
roscli exec "/system identity print" --transport telnet
roscli exec "/system identity print" --port 23

# JSON output (useful for scripts and AI agents)
roscli exec "/interface print" --json

Pipe commands via stdin

# SSH (default)
echo "/ip address print" | roscli exec
# Telnet
cat commands.txt | roscli exec --transport telnet

Run a batch file

One command per line. Lines starting with # are treated as comments.

roscli batch -f commands.txt
roscli batch -f commands.txt --transport telnet --json

Example commands.txt:

# Print network interfaces
/interface print
# Print IP addresses
/ip address print

Open an interactive console session

roscli console
roscli console --transport telnet --host 10.0.0.1

Type quit or press Ctrl+C to exit.

Exit codes

| Code | Meaning | | ---- | ------------------------- | | 0 | Success | | 1 | Connection or login error |

JSON output

The --json flag makes output machine-readable. Useful for AI agents and scripts:

roscli exec "/ip address print" --json
# {"output":"Columns: ADDRESS, NETWORK, INTERFACE, VRF\n..."}

Errors are also JSON on stderr:

{ "error": "RouterOS login failed — check MIKROTIK_LOGIN / MIKROTIK_PASSWORD" }

Telnet vs. SSH

| Feature | Telnet | SSH | | -------------------------- | ----------------- | -------------------------------- | | Default port | 23 | 22 | | Encryption | None | Yes (AES / ChaCha20) | | Commands and output | Identical | Identical | | Authentication | Password prompt | Password or keyboard-interactive | | First-login wizard support | Yes | Yes | | Woobm USB serial console | Yes | No (serial bridge) | | Recommended for | Local lab / Woobm | Production / remote access |

Both transports produce identical output — the same RouterOS commands work unchanged, and cleanOutput() normalises ANSI escape sequences and cursor-movement codes that RouterOS sends regardless of the protocol.

SSH host key verification is intentionally disabled.

RouterOS devices ship with self-signed SSH host keys that have no chain of trust, so the verification is disabled by default.

Tested hardware

| Device | Connection | RouterOS | | ----------------------------------- | ------------------------ | -------------- | | MikroTik hAP ac² (RBD52G-5HacD2HnD) | Direct Telnet (port 23) | 7.22.3 | | MikroTik hAP ac² (RBD52G-5HacD2HnD) | Direct SSH (port 22) | 7.21.4, 7.22.3 | | MikroTik hAP ac² (RBD52G-5HacD2HnD) | Woobm USB serial console | 7.21.4 |

The library should work on any MikroTik device running RouterOS 7.x with Telnet or SSH enabled.

Issue fix: Git Bash on Windows

Git Bash converts paths starting with / to Windows filesystem paths
(e.g. /ip → C:/Program Files/Git/ip).

Fix — add to your ~/.bashrc:

export MSYS_NO_PATHCONV=1

Then restart Git Bash. Alternatively, use PowerShell or CMD instead.

Tip for AI agents

To return the whole current configuration in one command, use:

# Whole config, but without sensitive values (passwords, secrets):
roscli exec "/export terse" --json
# Whole config with sensitive values included:
roscli exec "/export terse show-sensitive" --json

Note: Older RouterOS versions may not support terse format.

Node.js Library

As an alternative, you can use routeros-cli as a library in your Node.js / TypeScript project — see README-usage-as-lib.md for the full API reference.