Live CLI and MOPs

The Live CLI feature gives Claude a real console session to your devices, plus tooling to turn what happens in that session into a documented, repeatable procedure.

Enable it under Features in the dashboard.

device_cli — a real console

device_cli opens a live interactive CLI to a RUCKUS ICX switch or an AP over the same R1 web-UI WebSocket the R1 web console uses. It is the full CLI — any command, real output.

To open a session Claude needs the venue, the device type, and the device’s serial number (not its MAC), plus an ordered batch of commands. Commands run sequentially at the switch enable prompt or the AP rkscli: prompt. On ICX you can interleave config and show commands in one batch, because show works from config mode.

AP CLI needs a read-write connection. RUCKUS One issues the AP console token only to an API client with the ADMIN role, so if your default connection is read-only, an AP session fails with jwt_mint_forbidden. Pass connection naming a read-write connection (see Multiple connections). Switch CLI works on either. A session belongs to the connection it was opened with: naming a different one on a later batch returns connection_mismatch.

A batch carries at most 20 commands. By default a session is one-shot: it logs in, runs the batch, and closes as soon as the batch completes. For multi-batch work Claude opens the session with keepOpen: true, which holds the logged-in session so later batches, sent with its sessionId, run with no re-login — which is how a long configuration job gets applied: several batches of twenty into one live session, not one giant push. A held session closes on action: "close", or on its own after about 4 minutes idle (hard cap about 13 minutes).

Long-running commands

Logging in takes a few seconds, so a first call can come back connecting: true with a sessionId and no output yet; Claude then polls with action: "poll". A long command such as show tech also returns in pieces through poll until complete: true. For a command that never ends on its own (an un-counted ping, iperf3 -s), action: "interrupt" sends Ctrl-C and keeps the session open.

Reading the output

Each completed command comes back with its real console output. R1-MCP’s rule is that this output is surfaced verbatim in Claude’s reply — in a fenced code block, labeled with its command — and then interpreted. You should always get to see what the device actually said, not only a paraphrase of it.

Occasionally a result carries a marker meaning completion took a fallback path — the device kept talking after the prompt, or the command echo was never recognized. When that happens the attribution of output to command may be imperfect, and it’s worth reading that block yourself rather than trusting the summary.

When it fails

A prompt timeout usually means the device is offline or unreachable, not that the request was malformed. Confirm the device is online before retrying — each first-call retry opens a fresh session, so blind retries against a dead target just pile up.

Other errors are explicit: switch_credentials_unavailable, jwt_mint_failed, jwt_mint_forbidden (read-only connection, AP), ws_upgrade_failed, login_incorrect, no_commands, too_many_commands. On a held session:

Error	Meaning
busy	Another call on the same session is still executing — wait for it, then retry (close always works)
command_in_flight	A command is still streaming — poll it out first
no_command_to_interrupt	interrupt was sent but nothing was running
session_lost	The socket dropped or the session idled out — open a fresh session

MOPs — Method of Procedure

A MOP is a change runbook: ordered steps, each with the command, its intent, where the syntax was verified, the observed output pinned as the expected baseline, a verification gate, and rollback commands.

Tools: mop_save, mop_list, mop_get, mop_edit, mop_delete, mop_export, mop_replay.

The MOP tools also ship with the Copy feature, because a venue copy compiles into a MOP and is run by this same engine. Enabling either feature gives you them. device_cli itself — and so recording a live session and replaying CLI steps — needs Live CLI.

Recording a live session

The fast way to author one:

1. Save a draft MOP with just a title — you get back a MOP id.
2. Pass that id to device_cli as the record target.
3. Every command you run is captured as a draft step with its real output pinned as the baseline — one step per command, structural lines such as configure terminal and end included.
4. Enrich the draft afterwards — intent, gates, rollback, provenance.

Provenance is required

For every switch configuration step, the syntax must first be verified against the FastIron documentation for the device’s firmware train, and the section recorded on the step. Exported MOPs print that citation. A step without provenance exports as “no provenance recorded”, and the sign-off footer states plainly that the commands were not validated against documentation.

This is the difference between a runbook a change board will accept and a transcript.

Test plans

The same artifact with kind: "test_plan" turns the steps into test cases with declared expectations that gate on replay — a case with no gate defaults to requiring a human OK rather than silently passing. Test-plan runs keep 90 days of regression history.

The kind is immutable once saved: decide up front whether you’re writing a change procedure or a test plan.

Replaying and autopilot

mop_replay runs a saved MOP. By default it runs one step per call, so you see each result before the next command goes out, and dryRun: true walks the whole plan without touching anything.

action: "start_auto" runs the whole plan unattended instead: a server-side driver executes every step and returns { runId, autopilot: true } immediately. Poll action: "status" for progress.

Autopilot is preflight-gated, and the gates are the point. It refuses if:

• the plan isn’t live-ready;
• it contains config-changing steps without an explicit unattended: true acknowledgement — the server cannot tell a bench from production, so you are the one declaring it;
• onFail: "rollback" was asked for but a config step has no rollback commands;
• preflight raised warnings and you didn’t pass acceptWarnings: true.

What happens on failure is a policy you choose. onFail: "pause" (the default) stops on any failed gate or device error with the position preserved; "rollback" runs the consolidated reverse rollback and marks the run failed; "continue" records failures and keeps going, which is for lab-build momentum and not for change windows. A test plan is different again: a failed gate is recorded and the run continues, a device error retries the case once and then marks it blocked, and two consecutive blocked cases pause the run on the assumption the device has gone away.

One autopilot run per user at a time, capped at 30 minutes of wall clock by default and 120 at most. Expiry pauses a run; it never fails one — resume it with action: "resume_auto", which also re-arms a run whose progress has stalled. action: "abort" stops at the next step boundary.

Note

On a paused run, action: "step" is a permanent manual takeover — it clears autopilot ownership, and resume_auto no longer applies. If you only want to get past one case, use action: "skip", which keeps ownership intact.

skip applies to test plans only: skipAs: "skipped" (the default) doesn’t fail the run, and skipAs: "blocked" does. A MOP whose API steps write to named connection targets also needs armWrites: true to create a run (write_arming_required lists the tenants) — a separate gate from Write Guard.

Steps can be API checks too

A step doesn’t have to be a CLI command. An API step carries an R1 call plus expected-status and comparison gates, authored from a response you actually observed. Useful when the verification is “the controller now reports X” rather than “the console prints Y”.

Exporting a MOP

mop_export turns a saved MOP or test plan into a print-ready document. Every export also returns a download_url that opens only in your own signed-in browser.

format	What you get
both (default)	The structured JSON plus the standalone HTML document
json	The structured MOP
html	The print-ready runbook (or test plan) document
report	A test report across the recorded replay runs — needs at least one run, else no_runs_to_report
pdf	Link only — the download_url serves a PDF of the document
docx	Link only — the download_url serves a Word document

Documents use your saved branding (the dashboard’s Branding card) and embed the venue topology when the MOP names a venue; pass include_topology: false to omit it.

POC and QA test plans

The POC / QA test plan (author → run → report) prompt runs the whole cycle: writes a plan against an objective, executes it, and reports the results. The Deep-dive an ICX switch / fleet (live CLI) prompt runs a deep dive of a venue’s switches over the real CLI, read-only by default.

Limits worth knowing

Limit	Value
Commands per device_cli batch	20
MOPs / test plans per user	50 — untouched drafts age out after 30 days
Steps per MOP	200, or 400 for an API-only MOP
Runs kept per artifact	20, oldest dropped
Run history	7 days for a MOP, 90 days for a test plan

The MOPs a venue copy compiles are counted and swept separately — see Limits and quotas.

Next steps

• ICX switches and FastIron docs — where step syntax is verified
• Write Guard — confirm-before-write on mutating calls
• Test beds — lab hardware swaps
• Venue config copy — the other feature that ships the mop_* tools
• Limits and quotas — every cap in one place