RouterOS Syntax Inspection
Overview
RouterOS exposes its own parser over the REST API: /console/inspect
classifies every byte of console input (highlight), proposes continuations
(completion), returns structured help (syntax), and enumerates the command
tree (child); the :parse scripting command returns the intermediate
language (IL) the engine actually executes. Together these are the ground
truth for "is this valid RouterOS?" — version-exact, package-exact, and even
runtime-state-exact, which no static grammar can be.
This skill is a probe-selection and wire-format guide: which surface
answers which question, how to read each response, and which claims the
responses do and do not support. It is grounded in full-corpus captures
(913 scripts × multiple RouterOS versions) published in
tikoci/lsp-routeros-ts — the
docs/ references there carry the full evidence [^1].
"Parse RouterOS" is not one operation. Pick the probe for the question:
| Question |
Probe |
What it cannot establish |
| Which span is a command, argument, variable, comment, live-state marker? |
request=highlight |
Nested structure; value validity; anything after the first hard error |
| Is the script structurally valid; what blocks/expressions result? |
:parse |
Source ranges; partial IL on error; path/argument split without schema data |
| What is valid at this cursor position? Enum values? |
request=completion |
Requiredness; exhaustiveness of candidate lists; runtime acceptance |
| What paths, commands, arguments exist on this device? |
request=child + request=syntax |
Enum values (those come from completion); required arguments |
| Which arguments are required? |
Execute-error probe (add with no args) |
Conditional requirements past the first discriminator |
Details per surface: references/highlight.md,
references/parseil.md,
references/command-schema.md,
references/validation.md.
For crawling the full command hierarchy (child traversal, schema/RAML/OpenAPI
generation), see the routeros-command-tree skill — this skill covers the
syntax/validity surfaces of the same /console/inspect endpoint.
Request shape
All four inspect surfaces share one endpoint (basic auth, any RouterOS 7.x):
POST /rest/console/inspect
{"request": "highlight" | "completion" | "syntax" | "child",
"input": "<console input>", // optional
"path": "ip,address,add"} // optional comma-separated menu context
Every successful response is a JSON array of flat all-string objects with a
type field naming the request type. Beyond that, the four response shapes
share nothing — treat them as four APIs behind one endpoint.
Version baseline and safety
- Baseline: RouterOS 7.20.8 — a long-term-channel release, used here as the
recommended floor: the parseIL and crash-path behavior below was captured on
it [^1][^3]. REST itself exists since 7.1beta4 (HTTPS-only at first [^2]);
behavior below 7.20.8 is best-effort (7.9.2 was measured but harsher — see
references/highlight.md), and RouterOS v6 has no
REST API at all.
- Always set a per-request timeout (a few seconds). Old versions can hang
the whole REST server on specific inspect calls; a hung server also makes
subsequent unrelated probes appear broken.
- Known hazards (all measured, see [^1] and [^3]):
| Hazard |
Versions |
Rule |
request=syntax/completion at bare path do deadlocks the REST server |
≤ 7.20.8 (fixed by 7.21.4) [^3] |
Skip scripting-keyword paths (where, do, else, rule, command, on-error) on old/unknown versions; it is a conservative skip policy, not a timeless six-path crash rule |
request=syntax with input, or command-level syntax, stalls ~60 s |
observed on 7.9.2 |
Query syntax by path only; feature-detect command-level lookups with a short timeout |
input beyond 32,767 bytes rejected |
all |
Route oversized input to :parse (no cap) or reject it — never highlight a truncated copy and present it as validating the whole script |
| Highlight latency cliff near 28 KB |
observed 7.23.x |
Prefer a :parse pre-check for big scripts (no such cliff, no 32 KB cap) |
- Distinguish
[], timeout, and transport failure. An empty array is a
real answer (nonexistent path); a timeout is not. Conflating them corrupts
any cached conclusion.
Reading results — rules that prevent wrong claims
These are the measured behaviors that most often get summarized wrongly:
- Offsets and tokens are byte-based. RouterOS strings are single-byte
data — the console has no Unicode awareness. Highlight emits exactly one
token per input byte, and completion
offset counts bytes as received
on the wire (UTF-8 over REST, so non-ASCII characters occupy 2+ bytes and
desynchronize byte offsets from UTF-16/JS string indexes). ASCII-normalize
input first — replacing each char > 127 with one ASCII byte (?) keeps
editor character positions aligned to RouterOS byte positions.
- One hard error, then silence. Both highlight and
:parse stop at the
first hard error. Highlight marks exactly one error byte and leaves the
rest unclassified (none); :parse returns a message with line/column
and no partial IL. Neither gives multi-error diagnostics in one call.
Soft markers (obj-*, variable-undefined, syntax-obsolete) do not
stop classification.
none means unclassified, not "valid literal." Highlight accepts an
obviously bad IP as none. Value validation is a different layer.
obj-inactive / obj-disabled / obj-dynamic are live-state
classifications, not grammar errors. A disabled service or dynamic route
table is a perfectly valid reference. Diagnostic severity is the
consumer's policy decision — do not hard-code these as "invalid syntax."
- An undeclared
$name is usually not an error. It classifies as
variable-parameter (it may be supplied at call time). The "probably a
typo" signal is variable-undefined — a bare unresolvable identifier in
expression position.
- Completion candidates are observed suggestions, not proven-closed
enums. Preserve "observed candidates" provenance unless independent
evidence proves closure.
- Results are stateful. Token classes and candidates depend on the
RouterOS version, installed packages, and current object flags. Record
version + package manifest with any captured result; a snapshot from one
router is only approximately valid for another.
Validating a command via completion
The grounded mechanics of "check before you run" (full detail:
references/command-schema.md):
- Probe with the cursor immediately after the word under test — before
=, whitespace, or the next token. Completion verdicts are cursor-local:
advancing past an invalid word can hide its sentinel.
- Sentinel rows (
preference:"-20", empty completion,
text:"unknown command"/"unknown parameter") classify the word at
their offset — and also appear prospectively at the end of valid
input, so presence alone is not a verdict. Decision rule (7.21+):
sentinel with no completing candidate → unknown name; sentinel plus
candidates at the same offset → ambiguous prefix; candidates only → valid
partial; a nonexistent path returns [] outright.
- Feature-detect on old versions: 7.9.2 emits the unknown-command sentinel
but returns bare
[] for an unknown typed argument.
- Passing inspect validation is necessary, not sufficient. There is a
measured inspect-vs-runtime gap:
/console/inspect accepts forms the
device rejects at execution (e.g. blackhole=yes on a route, where the
runtime wants the bare blackhole flag) [^4]. Only execution on an
appropriate target proves runtime acceptance.
Minimum pipeline for a syntax "explain"
- Segment input statically (find command boundaries; preserve offsets).
- highlight the ASCII-normalized input → lexical spans + first error.
:parse only when structure or an error message is needed → nested IL
or line/column message. Align its error with highlight's error byte.
child/syntax/completion (or a same-version schema snapshot) →
split IL's fused path/argument forms, enumerate arguments, fetch enums.
- Enrich with docs/changelog prose — but the live device wins for what
its inspect surface exposes; only execution proves runtime acceptance.
Steps 1–2 suffice for a lightweight explain; block/scope analysis needs 3;
rich command help needs 4–5. Execution probes (required-args discovery,
/rest/execute) mutate state — run them only on explicit request against an
appropriate target.
Whatever the depth, keep provenance with every derived fact: source probe,
RouterOS version + packages, path context, whether the claim is a direct
response or derived, normalization applied, truncation, and outcome
(ok / empty / timeout / transport-error).
References
- references/highlight.md — per-byte token stream:
vocabulary, error model, statefulness, drift.
- references/parseil.md —
:parse IL: readout
recipe, grammar, canonicalizations, error behavior.
- references/command-schema.md —
child/syntax/completion response shapes, enum discovery, sentinels.
- references/validation.md — required-argument
probing and layering live vs static evidence.
[^1]: Full format references with capture artifacts:
highlight-format.md,
parseil-format.md,
inspect-shapes.md
in tikoci/lsp-routeros-ts — 913-script corpus swept on 7.9.2/7.23.2/7.24rc2
(highlight, inspect shapes) and 7.20.8/7.22.1/7.23rc1 (parseIL).
[^2]: MikroTik REST API introduction in 7.1beta4:
https://help.mikrotik.com/docs/spaces/ROS/pages/47579162/REST+API.
[^3]: MikroTik support case SUP-127641; per-version probe data in
tikoci/restraml (deep-inspect.ts
CRASH_PATHS notes and docs/<version>/deep-inspect.json
crashPathsCrashed): bare do hangs syntax/completion on 7.20.8 at
both 128 MB and 512 MB RAM; all six paths return instantly on 7.21.4+.
[^4]: tikoci/bench-routeros-tools
REPORT.md — the blackhole=yes inspect-vs-runtime case.
1---
2name: routeros-syntax-inspection
3description: "Inspecting and validating RouterOS command/script syntax against a live device via /console/inspect (highlight, completion, syntax, child) and :parse IL. Use when: validating RouterOS commands before execution, explaining or linting RouterOS scripts, building syntax-aware tooling (LSP servers, validators, agent explain/check commands), interpreting highlight token streams or :parse intermediate language, discovering enum values or argument schemas, or when the user mentions console/inspect, highlight tokens, parseIL, or RouterOS script validation."
4metadata:
5 source: https://skillmd.com/skills/tikoci/routeros-syntax-inspection
6---
7
8# RouterOS Syntax Inspection
9
10## Overview
11
12RouterOS exposes its **own parser** over the REST API: `/console/inspect`
13classifies every byte of console input (`highlight`), proposes continuations
14(`completion`), returns structured help (`syntax`), and enumerates the command
15tree (`child`); the `:parse` scripting command returns the intermediate
16language (IL) the engine actually executes. Together these are the ground
17truth for "is this valid RouterOS?" — version-exact, package-exact, and even
18runtime-state-exact, which no static grammar can be.
19
20This skill is a **probe-selection and wire-format guide**: which surface
21answers which question, how to read each response, and which claims the
22responses do and do not support. It is grounded in full-corpus captures
23(913 scripts × multiple RouterOS versions) published in
24[tikoci/lsp-routeros-ts](https://github.com/tikoci/lsp-routeros-ts) — the
25`docs/` references there carry the full evidence [^1].
26
27**"Parse RouterOS" is not one operation.** Pick the probe for the question:
28
29| Question | Probe | What it cannot establish |
30|---|---|---|
31| Which span is a command, argument, variable, comment, live-state marker? | `request=highlight` | Nested structure; value validity; anything after the first hard error |
32| Is the script structurally valid; what blocks/expressions result? | `:parse` | Source ranges; partial IL on error; path/argument split without schema data |
33| What is valid at this cursor position? Enum values? | `request=completion` | Requiredness; exhaustiveness of candidate lists; runtime acceptance |
34| What paths, commands, arguments exist on this device? | `request=child` + `request=syntax` | Enum values (those come from `completion`); required arguments |
35| Which arguments are required? | Execute-error probe (`add` with no args) | Conditional requirements past the first discriminator |
36
37Details per surface: [references/highlight.md](references/highlight.md),
38[references/parseil.md](references/parseil.md),
39[references/command-schema.md](references/command-schema.md),
40[references/validation.md](references/validation.md).
41
42For crawling the full command hierarchy (`child` traversal, schema/RAML/OpenAPI
43generation), see the **`routeros-command-tree`** skill — this skill covers the
44*syntax/validity* surfaces of the same `/console/inspect` endpoint.
45
46## Request shape
47
48All four inspect surfaces share one endpoint (basic auth, any RouterOS 7.x):
49
50```text
51POST /rest/console/inspect
52{"request": "highlight" | "completion" | "syntax" | "child",
53 "input": "<console input>", // optional
54 "path": "ip,address,add"} // optional comma-separated menu context
55```
56
57Every successful response is a JSON array of flat all-string objects with a
58`type` field naming the request type. Beyond that, the four response shapes
59share nothing — treat them as four APIs behind one endpoint.
60
61## Version baseline and safety
62
63- **Baseline: RouterOS 7.20.8** — a long-term-channel release, used here as the
64 recommended floor: the parseIL and crash-path behavior below was captured on
65 it [^1][^3]. REST itself exists since 7.1beta4 (HTTPS-only at first [^2]);
66 behavior below 7.20.8 is best-effort (7.9.2 was measured but harsher — see
67 [references/highlight.md](references/highlight.md)), and RouterOS v6 has no
68 REST API at all.
69- **Always set a per-request timeout** (a few seconds). Old versions can hang
70 the whole REST server on specific inspect calls; a hung server also makes
71 *subsequent* unrelated probes appear broken.
72- **Known hazards** (all measured, see [^1] and [^3]):
73
74| Hazard | Versions | Rule |
75|---|---|---|
76| `request=syntax`/`completion` at bare path `do` deadlocks the REST server | ≤ 7.20.8 (fixed by 7.21.4) [^3] | Skip scripting-keyword paths (`where`, `do`, `else`, `rule`, `command`, `on-error`) on old/unknown versions; it is a conservative skip policy, not a timeless six-path crash rule |
77| `request=syntax` with `input`, or command-level `syntax`, stalls ~60 s | observed on 7.9.2 | Query `syntax` by `path` only; feature-detect command-level lookups with a short timeout |
78| `input` beyond 32,767 bytes rejected | all | Route oversized input to `:parse` (no cap) or reject it — never highlight a truncated copy and present it as validating the whole script |
79| Highlight latency cliff near 28 KB | observed 7.23.x | Prefer a `:parse` pre-check for big scripts (no such cliff, no 32 KB cap) |
80
81- **Distinguish `[]`, timeout, and transport failure.** An empty array is a
82 real answer (nonexistent path); a timeout is not. Conflating them corrupts
83 any cached conclusion.
84
85## Reading results — rules that prevent wrong claims
86
87These are the measured behaviors that most often get summarized wrongly:
88
891. **Offsets and tokens are byte-based.** RouterOS strings are single-byte
90 data — the console has no Unicode awareness. Highlight emits exactly one
91 token per input **byte**, and completion `offset` counts bytes as received
92 on the wire (UTF-8 over REST, so non-ASCII characters occupy 2+ bytes and
93 desynchronize byte offsets from UTF-16/JS string indexes). ASCII-normalize
94 input first — replacing each char > 127 with one ASCII byte (`?`) keeps
95 editor character positions aligned to RouterOS byte positions.
962. **One hard error, then silence.** Both highlight and `:parse` stop at the
97 first hard error. Highlight marks exactly one `error` byte and leaves the
98 rest unclassified (`none`); `:parse` returns a message with line/column
99 and **no partial IL**. Neither gives multi-error diagnostics in one call.
100 Soft markers (`obj-*`, `variable-undefined`, `syntax-obsolete`) do *not*
101 stop classification.
1023. **`none` means unclassified, not "valid literal."** Highlight accepts an
103 obviously bad IP as `none`. Value validation is a different layer.
1044. **`obj-inactive` / `obj-disabled` / `obj-dynamic` are live-state
105 classifications, not grammar errors.** A disabled service or dynamic route
106 table is a perfectly valid reference. Diagnostic severity is the
107 consumer's policy decision — do not hard-code these as "invalid syntax."
1085. **An undeclared `$name` is usually not an error.** It classifies as
109 `variable-parameter` (it may be supplied at call time). The "probably a
110 typo" signal is `variable-undefined` — a bare unresolvable identifier in
111 expression position.
1126. **Completion candidates are observed suggestions, not proven-closed
113 enums.** Preserve "observed candidates" provenance unless independent
114 evidence proves closure.
1157. **Results are stateful.** Token classes and candidates depend on the
116 RouterOS version, installed packages, and current object flags. Record
117 version + package manifest with any captured result; a snapshot from one
118 router is only approximately valid for another.
119
120## Validating a command via completion
121
122The grounded mechanics of "check before you run" (full detail:
123[references/command-schema.md](references/command-schema.md)):
124
125- Probe with the cursor **immediately after the word under test** — before
126 `=`, whitespace, or the next token. Completion verdicts are cursor-local:
127 advancing past an invalid word can hide its sentinel.
128- Sentinel rows (`preference:"-20"`, empty `completion`,
129 `text:"unknown command"`/`"unknown parameter"`) classify **the word at
130 their `offset`** — and also appear *prospectively* at the end of valid
131 input, so presence alone is not a verdict. Decision rule (7.21+):
132 sentinel with no completing candidate → unknown name; sentinel plus
133 candidates at the same offset → ambiguous prefix; candidates only → valid
134 partial; a nonexistent *path* returns `[]` outright.
135- Feature-detect on old versions: 7.9.2 emits the unknown-*command* sentinel
136 but returns bare `[]` for an unknown typed *argument*.
137- **Passing inspect validation is necessary, not sufficient.** There is a
138 measured inspect-vs-runtime gap: `/console/inspect` accepts forms the
139 device rejects at execution (e.g. `blackhole=yes` on a route, where the
140 runtime wants the bare `blackhole` flag) [^4]. Only execution on an
141 appropriate target proves runtime acceptance.
142
143## Minimum pipeline for a syntax "explain"
144
1451. **Segment** input statically (find command boundaries; preserve offsets).
1462. **highlight** the ASCII-normalized input → lexical spans + first error.
1473. **`:parse`** only when structure or an error message is needed → nested IL
148 or line/column message. Align its error with highlight's error byte.
1494. **`child`/`syntax`/`completion`** (or a same-version schema snapshot) →
150 split IL's fused path/argument forms, enumerate arguments, fetch enums.
1515. **Enrich** with docs/changelog prose — but the live device wins for what
152 its inspect surface exposes; only execution proves runtime acceptance.
153
154Steps 1–2 suffice for a lightweight explain; block/scope analysis needs 3;
155rich command help needs 4–5. Execution probes (required-args discovery,
156`/rest/execute`) mutate state — run them only on explicit request against an
157appropriate target.
158
159Whatever the depth, keep provenance with every derived fact: source probe,
160RouterOS version + packages, path context, whether the claim is a direct
161response or derived, normalization applied, truncation, and outcome
162(`ok` / `empty` / `timeout` / `transport-error`).
163
164## References
165
166- [references/highlight.md](references/highlight.md) — per-byte token stream:
167 vocabulary, error model, statefulness, drift.
168- [references/parseil.md](references/parseil.md) — `:parse` IL: readout
169 recipe, grammar, canonicalizations, error behavior.
170- [references/command-schema.md](references/command-schema.md) —
171 `child`/`syntax`/`completion` response shapes, enum discovery, sentinels.
172- [references/validation.md](references/validation.md) — required-argument
173 probing and layering live vs static evidence.
174
175[^1]: Full format references with capture artifacts:
176 [`highlight-format.md`](https://github.com/tikoci/lsp-routeros-ts/blob/main/docs/highlight-format.md),
177 [`parseil-format.md`](https://github.com/tikoci/lsp-routeros-ts/blob/main/docs/parseil-format.md),
178 [`inspect-shapes.md`](https://github.com/tikoci/lsp-routeros-ts/blob/main/docs/inspect-shapes.md)
179 in tikoci/lsp-routeros-ts — 913-script corpus swept on 7.9.2/7.23.2/7.24rc2
180 (highlight, inspect shapes) and 7.20.8/7.22.1/7.23rc1 (parseIL).
181[^2]: MikroTik REST API introduction in 7.1beta4:
182 <https://help.mikrotik.com/docs/spaces/ROS/pages/47579162/REST+API>.
183[^3]: MikroTik support case SUP-127641; per-version probe data in
184 [tikoci/restraml](https://github.com/tikoci/restraml) (`deep-inspect.ts`
185 `CRASH_PATHS` notes and `docs/<version>/deep-inspect.json`
186 `crashPathsCrashed`): bare `do` hangs `syntax`/`completion` on 7.20.8 at
187 both 128 MB and 512 MB RAM; all six paths return instantly on 7.21.4+.
188[^4]: [tikoci/bench-routeros-tools](https://github.com/tikoci/bench-routeros-tools)
189 `REPORT.md` — the `blackhole=yes` inspect-vs-runtime case.