Mikrotik Service Cards

Generate Markdown service cards straight from RouterOS using the built-in REST API and the provided template.md layout.

Installation

# use npx (no install)
npx mikrotik-service-cards --help

# or install globally
npm install -g mikrotik-service-cards

# or add to a project
npm install mikrotik-service-cards

The CLI depends on Node.js 18+ and a RouterOS v7+ device with the www-ssl service enabled. SNMP location/contact values are consumed automatically when present.

Usage

The CLI reads CLI flags (or environment variables) to connect to the router, pull REST data, and write Markdown/YAML outputs. Provide credentials either on the command line or via environment variables (MIKROTIK_URL, MIKROTIK_USER, MIKROTIK_PASSWORD, etc.).

mikrotik-service-cards \
  --router-url https://192.0.2.1 \
  --username docs-1k2m9z \
  --password 'superSecret' \
  --output docs/router-01.md \
  --yaml-output docs/router-01.yaml \
  --location "Rack A1" \
  --purpose "Core edge" \
  --lan 192.0.2.0/24 \
  --wg-interface wg-docs \
  --include-config

Key flags:

• --router-url – base URL to the router (without /rest).
• --username / --password – RouterOS credentials (env: MIKROTIK_USER / MIKROTIK_PASSWORD).
• --output – destination Markdown file (directories auto-create, default docs/router.md).
• --yaml-output – optional YAML snapshot path for IaC/automation workflows.
• --template – path to a custom Handlebars template. When omitted, the CLI uses the bundled template.md inside the package.
• --location, --purpose, --lan, --contact – metadata overrides when SNMP or interface data is missing.
• --wg-interface – pick a specific WireGuard interface (defaults to the first one).
• --include-config – run /export compact and embed the output (requires a user created with --allow-export, plus --allow-sensitive when WireGuard/private-key data is involved).
• --insecure – allow self-signed certs (sets rejectUnauthorized=false).
• --timeout – REST timeout in milliseconds (default 8000).

Environment variables mirror these options (.env support is built-in via dotenv). For example, set MIKROTIK_URL, MIKROTIK_USER, MIKROTIK_PASSWORD, OUTPUT_PATH, YAML_PATH, etc., to avoid passing long flag lists.

Provision a Read-Only REST User

Use the helper script to create random credentials and a RouterOS CLI snippet that the admin can paste into the router terminal.

npm run credentials -- --certificate=myRestCert

Example output:

{
  "username": "docs-1k2m9z",
  "password": "6q0fx4mwjf3m7p0xv2r0"
}

RouterOS CLI snippet:
# Paste into RouterOS terminal
/user/group/add name=rest-docs policy=read,api,rest-api,test,winbox
/user/add name="docs-1k2m9z" group=rest-docs password="6q0fx4mwjf3m7p0xv2r0" comment="REST docs readonly" disabled=no
/ip/service/set [find where name="www-ssl"] certificate=myRestCert tls-version=only-1.2-1.3 disabled=no
/ip/service/set [find where name="www"] disabled=yes

The admin can paste the snippet via WinBox/SSH. Keep the generated password secret and store it in your .env or CI secret store.

Need --include-config support? Run npm run credentials -- --allow-export so the policy includes write. /export writes a temporary .rsc file and RouterOS will return HTTP 500 unless the user has write permission. If your config contains secrets (e.g., WireGuard private keys), add --allow-sensitive as well.

Classic npm run docs -- … still works for local development.

YAML / IaC Output

When --yaml-output (or YAML_PATH) is specified, the CLI writes a structured YAML snapshot alongside the Markdown file. The snapshot captures router metadata (identity, ROS version, location/contact), interfaces with bound addresses, VLANs, WireGuard interfaces/peers, routing table entries, firewall filter/NAT rules, DHCP servers/networks/pools, DNS settings, SNMP/SMB settings, and the optional config export text—focusing on configuration data you can replay or diff. Because the format is plain YAML, you can commit it for drift detection, feed it into RouterOS automation scripts, or treat it as source-of-truth for infrastructure-as-code pipelines.

Output

Generated files strictly follow template.md, filling sections for interfaces, WireGuard, LAN, a VLAN interface table (VLAN ID, parent interface, IP, mask, comment), storage, monitoring, firewall filter and NAT tables, a DHCP/DNS block (servers, networks, pools with calculated sizes, upstreams), a Management Access summary (WinBox/Web/API/REST/SSH endpoints derived from /ip/service), the active routing table, and an optional config export block. SNMP location/contact automatically populate the header (CLI/env values serve as fallbacks). The code handles missing data gracefully (it prints n/a when an endpoint is unavailable) and logs API errors to stderr.

Credential helper as a CLI

The helper that provisions a REST-only RouterOS account is also exposed as a binary once the package is installed:

mikrotik-service-cards-credentials --allow-export --certificate=myRestCert
# or use npx mikrotik-service-cards-credentials …

CLI flags mirror the previous npm run credentials experience (username/password length overrides, --allow-export, --allow-sensitive, etc.).

Troubleshooting

• Set --timeout (default 8000 ms) higher if routers sit behind high-latency links.
• Use --insecure only for testing; otherwise import the router's CA into the host trust store.
• If /rest/export times out, rerun with --include-config disabled and download the generated .rsc file manually from the router.
• For offline documentation, point --template to your own file and feed data via environment overrides; otherwise, the CLI always shows what RouterOS exposes live.

Releasing to npm

1. Ensure package.json metadata (version, repository, author) is up to date.
2. Run npm test/npm run docs -- --help to verify the CLI still works.
3. Optionally inspect the tarball with npm pack.
4. npm login && npm publish --access public (the publishConfig is already set to public).

The package bundles src/, scripts/, template.md, README.md, and LICENSE, so consumers can run both the main CLI and the credential helper out of the box.