A local command-line wrapper around the MikroTik RouterOS CLI — run router commands over SSH or Telnet from AI agents, your terminal or Node.js scripts.
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)
- 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.
Global CLI (recommended for terminal use):
npm install -g routeros-cliMakes the roscli command available globally.
Show help:
roscli --helpRun without installing (npx):
export MIKROTIK_PASSWORD=yourpassword
npx routeros-cli exec "/export terse" --host 192.168.88.1 --login admin --transport sshConnection 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_TRANSPORT=ssh # `ssh` | `telnet`
# default: `ssh`, or auto-detected from port if given
# optional
MIKROTIK_PORT=22 # auto-detected from transport. Or define if non-standard port is required.
# optional
MIKROTIK_LOGIN=admin # default: `admin`
MIKROTIK_PASSWORD=yourpassword # default: ""
# additional options:
MIKROTIK_TIMEOUT=10 # command response timeout in seconds
# optional, default: `10`
MIKROTIK_CONNECT_TIMEOUT=15 # TCP / SSH handshake timeout in seconds
# optional, default: `15`Any option can also be passed directly as command-line options (overriding the environment variables).
| Option | Default | Description |
|---|---|---|
--host <ip> |
MIKROTIK_HOST env (required) |
Device IP or hostname |
--transport <type> |
MIKROTIK_TRANSPORT env / default |
ssh or telnet |
--port <port> |
MIKROTIK_PORT env / transport default |
if non-standard port is needed |
--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.
# 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 AI agents and scripts)
roscli exec "/interface print" --json# SSH (default)
echo "/ip address print" | roscli exec
# Telnet
cat commands.txt | roscli exec --transport telnetOne command per line. Lines starting with # are treated as comments.
roscli batch -f commands.txt
roscli batch -f commands.txt --transport telnet --jsonExample commands.txt:
# Print network interfaces
/interface print
# Print IP addresses
/ip address print
roscli console
roscli console --transport telnet --host 10.0.0.1Type quit or press Ctrl+C to exit.
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" }To return the whole current configuration in one command, use:
# Whole config, but without sensitive values (passwords, secrets):
roscli exec "/export terse"
# Complete config exports, including sensitive values (use with caution!):
roscli exec "/export terse show-sensitive"
# Router name and model
roscli exec "/system identity print"
roscli exec "/system routerboard print"
# RouterOS version, uptime, CPU/memory usage, architecture
roscli exec "/system resource print"
# Recent log entries
roscli exec "/log print"| 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.
| 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.
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.
Git Bash converts paths starting with / to Windows filesystem paths (e.g. /ip → C:/Program Files/Git/ip).
As a fix, add to your ~/.bashrc: export MSYS_NO_PATHCONV=1. Then restart Git Bash. Alternatively, use PowerShell or CMD instead.