# CLI Every verb of the mikroscope CLI and its flags, grouped by verb, with each flag's default, accepted values and the MIKROSCOPE_* variable that sets it, read from the Go source. Source: https://docs.jmrp.io/mikroscope/reference/cli/ `mikroscope` takes a verb and its flags. The tables below give each flag's default, the values it accepts and the environment variable that sets it, as [`cmd/mikroscope/`](https://github.com/jmrplens/mikroscope/tree/main/cmd/mikroscope) and [`internal/router/options.go`](https://github.com/jmrplens/mikroscope/blob/main/internal/router/options.go) define them. ## Usage and exit codes ```sh mikroscope [flags] ``` The verbs fall into five groups, each with its own flag set: the deployment verbs (`doctor`, `plan`, `install`, `upgrade`, `uninstall`, `status`, `image`), the recording verbs (`record`, `mark`, `plot`), the collector (`forward`), `dashboards`, and `version`. Flags are Go `flag` flags: `-rate 50` and `--rate 50` are the same, and a boolean is turned off with `-privileged=false`. | Status | When | | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `0` | the verb finished | | `1` | the verb ran and failed (a missing prerequisite, a router error, a sink that could not be built, a panel with no data, a store `dashboards publish` could not publish), the verb is unknown, or a flag of `uninstall`, `record`, `mark`, `plot`, `forward` or `dashboards` failed to parse or validate | | `2` | no verb was given, or a flag of `doctor`, `plan`, `install`, `upgrade`, `status` or `image` failed to parse or validate; nothing was sent to the router | Every deployment and connection flag is validated before anything connects, by one function, `FinishFor` in [`internal/router/options.go`](https://github.com/jmrplens/mikroscope/blob/main/internal/router/options.go), so a bad value stops the verb with nothing sent to the router and names the value it refused: ```text $ mikroscope install --rate 500 mikroscope: rate must be 1-100 Hz, got 500 ``` That exits 2; `uninstall --rate 500`, `record --port 0` and `forward --port 0` exit 1. `--triggers` goes through the agent's own `ParseTriggers`, so an unknown condition, a bad threshold, a quote or a semicolon fails the verb the same way. The agent parses `TRIGGERS` again when it starts, which is what catches an envlist edited by hand on the router: the container exits with status `2` after a `mikroscope-agent: bad configuration:` line in the router log, and `restart-policy=on-failure` restarts it. ### Defaults - A flag that names a variable in the tables below reads its default from `MIKROSCOPE_`. A variable set to the empty string counts as unset, and a flag on the command line always wins. - **Only the flags that name a variable have one.** `--rate`, `--buffer`, `--port`, `--memory-max`, `--mem-limit-mb`, `--capture-mb`, `--triggers`, `--floor-hz`, `--privileged`, `--ephemeral`, `--expose`, `--restart-max-count`, `--restart-interval`, `--start-on-boot`, `--container-name` and `--extract-timeout` are flags only. - `status`, `upgrade` and `uninstall` take the flags that describe an install's shape from the install on the router when they are not given ([Install shape](https://docs.jmrp.io/mikroscope/reference/cli/#pass-the-same-shape-to-status-upgrade-and-uninstall)). - The CLI does not read `.env` itself; export it first with `set -a; . ./.env; set +a`. [Environment variables](https://docs.jmrp.io/mikroscope/reference/environment/) lists every variable, including the credentials that have no flag at all. ## Deployment commands The seven deployment verbs share the [deployment flags](https://docs.jmrp.io/mikroscope/reference/cli/#flags-of-the-deployment-verbs); a flag a verb has no use for is accepted, checked and ignored. The flags of each verb's own are these: | Verb | What it does | Writes to the router | Its own flags | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ---------------------------------------------------- | | `doctor` | Read-only preflight in one ssh connect; each failing check names its fix. Then reads the running agent's ring for a loop, STP churn, link flaps and softnet drops. | no | none | | `plan` | Prints every object `install` would create, then stops; connects to nothing. With `--rsc` it writes a RouterOS script instead. | no | `--rsc`, `--out` | | `install` | Runs `doctor`, gets the image for the router's architecture, prints the listing, asks, writes the install manifest and then every object, then probes the agent from this host. | yes | `--dry-run`, `--yes`, `--no-doctor` | | `upgrade` | Reads the install's shape, gets a new image, lists the manifest, the container step and any step the router no longer holds, asks, writes them, re-creates the container step, then probes. | yes | `--dry-run`, `--yes` | | `uninstall` | Reads the install's manifest, removes everything the install created, newest first and the manifest last, then verifies by count and by tag. Lists and removes nothing without `--yes`. | yes | `--yes`, `--targets`, the sink and Grafana flags | | `status` | Reads the install's shape and prints the ownership count of every step; if anything is installed, probes the agent and prints its health and board. | no | none | | `image` | Builds the agent image tar and writes it to `--out`, for side-loading by hand; connects to nothing. | no | `--out` | ### `doctor` ```sh mikroscope doctor ``` It runs these checks, in this order, and exits 1 with `N prerequisite(s) missing; nothing was written` when a `MISSING` line is printed; a `WARN` line changes nothing: The checks doctor runs: | Check, as printed | Passes when | The fix it names | | --- | --- | --- | | RouterOS 7.24 or later | `/system/resource` reports a `version` of 7.24 or later, read with or without a patch number and whatever the channel, as in `7.24 (stable)` or `7.25rc1 (testing)` | upgrade RouterOS to 7.24 or later (`/system/package/update`), and the `container` package with it | | architecture has a container package | the router's `architecture-name` is `arm`, `arm64` or `x86_64`, the architectures MikroTik publishes a `container` package for | none: no agent can run on this router | | the router picks the image's architecture | with `--remote-image`: always, naming the router's architecture, because RouterOS picks it from the image's multi-architecture index. A warning on `arm`, where the index holds both `linux/arm/v5` and `linux/arm/v7` and which one RouterOS pulls is not known | on `arm`, if the container stops with `Exec format error`, install from `mikroscope-agent-armv5.tar` with `--agent-tar` | | architecture matches the --agent-tar image | with `--agent-tar`: the tar's own architecture is the router's (`amd64` for `x86_64`); `--arch` is not needed | download the release asset it names, `mikroscope-agent-.tar` | | architecture read from the router | with neither image flag and `--arch` unset (or `auto`): always; `install` and `upgrade` build or load the image for the architecture doctor read | none | | architecture matches --arch | with an explicit `--arch` and neither image flag: the router's `architecture-name` is the one `--arch` maps to (`arm64`, `arm`, `x86_64`) | re-run with the `--arch` it names, or leave `--arch` out so that `install` reads it from the router | | container package installed and enabled | a `container` package exists with `disabled=no` | download the `container` package for this architecture and RouterOS version, upload it and reboot; when it is there and disabled, `/system/package/enable container` and reboot | | device-mode container=yes | `/system/device-mode` reports `container=yes` | `/system/device-mode/update container=yes`, then confirm it as the console asks: on a router that says `update: please activate by turning power off or pressing reset or mode button`, press the reset or mode button or cut the power; on CHR, which says `update: turn off power in 5m to activate changes`, power the VM off and on again within 5 minutes | | free memory ≥ <--memory-max> | `free-memory` is at least what `--memory-max` asks for, 64 MiB by default | free memory on the router, or ask for less with `--memory-max` | | free memory leaves room for the pull | a warning, with `--remote-image` only: `free-memory` is at least `--memory-max` plus 16 MiB, room for RouterOS to pull and extract the image before the agent starts. How much a pull takes is not measured, so the margin is an estimate | install from a tar with `--agent-tar` if the pull fails | | free flash ≥ (image tar + extracted root) | without `--disk` or `--ephemeral`: `free-hdd-space` is at least twice the image plus 4 MiB. With `--remote-image` nothing is uploaded and the name ends in `(extracted root)`: the root the pulled image is extracted into, 7 MiB, plus 4 MiB | free flash, or install with `--disk tmpfs` or `--ephemeral` where a tmpfs disk exists | | disk exists | with `--disk` or `--ephemeral`: a disk with that slot exists | `/disk/add type=tmpfs tmpfs-max-size=64M slot=tmpfs` for a RAM disk, or name an existing disk with `--disk` | | disk has ≥ free (image tar + extracted root) | with `--disk` or `--ephemeral`, once the disk exists: its free space is at least twice the image plus 4 MiB; with `--remote-image`, the 7 MiB root plus 4 MiB, as the flash check | free space on that disk, or give a tmpfs disk a larger `tmpfs-max-size` | | disk tmpfs is RAM | with `--ephemeral`: the disk in slot `tmpfs` is of type `tmpfs` | free the slot for a tmpfs disk, or install with `--disk ` without `--ephemeral` | | start-on-boot suits a root in RAM | a warning, when the disk is a tmpfs disk: start-on-boot resolves to `no`, since a reboot empties the disk and a container started at boot has no root | pass `--start-on-boot no`, or `--ephemeral` | | veth name is free or ours | no veth has that name, or the one that has it carries this install's tag | pick another `--veth` (and `--subnet`), or remove the veth by hand if it is a leftover of yours | | envlist -env is free or ours | no envlist has that name, or the one that has it holds this install's `MIKROSCOPE_TAG` entry | pick another `--name` | | install manifest mikroscope/.manifest.txt is free or ours | no file is at the install manifest's path, or the one there holds this install's `tag=` line | move the file away, or pick another `--name` | | container name is free or ours | with `--container-name`: no container has that name, or the one that has it carries this install's tag | pick another `--container-name` | | subnet does not overlap a route | no route of the main table, active or not, lies inside the /30, and no connected network on another interface holds its router end. Routes that only contain the /30 (a default route, a wider prefix to a VPN), blackhole routes and the install's own veth are left out | pick another /30 with `--subnet` | | interface list exists | the `--iface-list` list (default `LAN`) exists. With `--iface-list none` doctor prints `interface list the veth joins` and passes: no membership is written | `--iface-list none` when no firewall rule needs the veth in a list (doctor offers it first then); otherwise `/interface/list/add name=…`, or pass the list your `in-interface-list=!…` drop rule uses | | address list | always: install adds the /30 to the `--addr-list` list (default `LANs`), which creates it when it is missing, and uninstall removes the entry. With `--addr-list none` doctor prints `address list the /30 joins`. Whether a rule needs the membership is the next row's question | none | | no firewall rule drops the agent's replies | doctor reads every enabled rule of the chains the agent's replies meet, `/ip/firewall/raw` prerouting and `/ip/firewall/filter` forward and input, and walks each one as RouterOS does, first match wins, with the replies in the lists the plan joins: no rule drops them. A warning when a rule might, because it matches on something doctor does not judge (a destination, a mark, a rate), and when the replies to a LAN host pass but a rule may drop the ones to the router itself (filter input), which the relay transport needs | the `--iface-list` and `--addr-list` that let the replies through; when no list does (a `src-address=!` rule, say), add an accept rule for `in-interface=` before that rule, or pick a `--subnet` inside the range | | no firewall rule doctor reads is invalid or names a deleted list | a warning: no rule of raw prerouting or filter forward and input is marked invalid, which RouterOS passes over as if it were not there (it names an interface that was removed or is not ready, and `about` says which), and none names an interface list that was removed, which RouterOS keeps as the list's id (`in-interface-list=!*2000010`) and matches as an empty list. A rule changed a moment before reads invalid with no reason until RouterOS has applied it | fix or remove what an invalid rule names; set a deleted list again by name, since creating a list of the same name does not repair the rule. With no reason given, run `doctor` again | | --lan-address
is the router's | with `--expose`: an interface of the router holds that address | pass the address the router has on its LAN, as `/ip/address/print` lists it | | --lan-address is not on the uplink | a warning, with `--expose`: the interface that holds the address carries no default route, is in no `WAN` list, and shares no interface list with the interface that carries the default route | pass the router's LAN address: on the uplink the dst-nat would publish the agent on the Internet side | | no registry credential meant for another registry | a warning, with `--remote-image` only: no `/container/config` username is set, or the host of `registry-url` is the host the image is pulled from, every spelling of Docker Hub counted as one. An empty `registry-url` with a username set warns. Doctor reads whether a username is set, never the name, and cannot read the password | `/container/config` holds one username for the whole device, and a credential from another registry can make the pull of a public image end in `auth error`. Install from a tar with `--agent-tar`, pass a `--remote-image` on the registry the username belongs to, or clear the username if nothing else needs it | | the installed agent published on the LAN asks for a token | a warning, shown only when an install of this `--name` has a dst-nat on the LAN: its environment holds a `TOKEN`. Doctor counts the entries, never reads the value | `upgrade` with the same `--name` and `--token `; or remove the agent, the LAN rules and the container together with `uninstall --name --yes` | | the router does not answer DNS from its uplink | a warning: `/ip/dns` `allow-remote-requests` is off, or a rule of raw prerouting or filter input drops a UDP query to port 53 that comes in on the interface of the active default route, walked as for the trap check, first match wins. A warning that the queries may pass when a rule matches on something doctor does not judge, a source address list say. IPv6 is not read | a drop rule for UDP and TCP port 53 on the uplink before any accept that takes it, or `/ip/dns/set allow-remote-requests=no` if no LAN host uses the router as its resolver | | nothing tagged for that these flags do not select | a warning: in every menu an install writes to, the objects that carry the install's tag are no more than the plan for these flags selects. An install made with other flags (`--expose`, other lists, another `--subnet`) leaves more | run `status` and `uninstall` with no shape flag, so that they read the install manifest, or with the flags that install was given | Standalone `doctor`, but not the doctor that `install` runs, then pulls the agent's ring once over HTTP from the `--subnet` .2 address on `--port`, sending `--token`, and gives up after 3 s. Pass the same `--subnet`, `--port` and `--token` the agent was installed with. The findings are defined in [Requirements](https://docs.jmrp.io/mikroscope/install/prerequisites/#what-the-running-agent-shows) and never change the exit status. ### `plan` ```sh mikroscope plan mikroscope plan --rsc --remote-image jmrplens/mikroscope-agent:1.6.1 --out mikroscope.rsc ``` - Without `--rsc` it prints the listing `install` would print, the same as `install --dry-run`, with the token masked as `(token)`. - With `--rsc` it writes the whole install as a RouterOS script, to `--out` or to standard output. With `--out` it prints `: N lines; review it, then paste it into the router's terminal or /import it`. Paste it only at the `] >` prompt: a script pasted while RouterOS is asking about the licence loses its first lines ([RouterOS script](https://docs.jmrp.io/mikroscope/install/script/#run-on-the-router)). With a token set, the script carries it in clear ([Installer safeguards](https://docs.jmrp.io/mikroscope/security/installer/#a-generated-rsc-script-is-a-credential)). - `--arch auto` is `arm64` here, since nothing is asked of the router. ### `install` ```sh mikroscope install --remote-image jmrplens/mikroscope-agent:1.6.1 ``` 1. `doctor`, in one connect, unless `--no-doctor`. A missing prerequisite stops it with nothing written. 2. With `--arch auto`, the architecture doctor read; `--no-doctor` without `--remote-image` makes one more connect to read it, and says so. 3. The image: built, read from `--agent-tar`, or none with `--remote-image`. 4. The listing, then `write the objects above to the router? [y/N]` unless `--yes`. Anything but `y` stops it with `not confirmed; nothing written`. 5. The install manifest, then every object, and `install done: N step(s) created`. 6. The probe from this host ([Network access](https://docs.jmrp.io/mikroscope/install/reaching-the-agent/#what-the-probe-after-install-tells-you)). `--dry-run` stops after the listing and opens no connection. ### `upgrade` ```sh mikroscope upgrade --remote-image jmrplens/mikroscope-agent:1.6.1 ``` - One connect reads how the install was made, whether each step is there, the router's architecture and, with `--remote-image`, doctor's registry-credential check. `upgrade` runs no `doctor`. - It refuses a router with no install (`nothing to upgrade: run install first`), and an install with a token when none is given. - It lists the install manifest, the container step and any step the router no longer holds, asks, writes the manifest and the missing steps, removes and re-creates the container step, then probes. The network objects stay. - The envlist is written from the flags given to `upgrade`: a tuning flag left out comes back at its default ([Install shape](https://docs.jmrp.io/mikroscope/reference/cli/#pass-the-same-shape-to-status-upgrade-and-uninstall)). - `--dry-run` stops after the listing and opens no connection. ### `uninstall` ```sh mikroscope uninstall # lists the router objects mikroscope uninstall --yes # and removes them mikroscope uninstall --targets all --influx … --grafana … # lists everything mikroscope uninstall --targets all --influx … --grafana … --yes # and removes it ``` Without `--yes` it lists: with `--router` it reads the install's shape first, and without it lists from the flags alone. `--targets` widens it past the router: | Target | What goes | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `router` | everything `install` created: the objects in the install manifest, any other object with the install's tag, the container root, the manifest, and the `mikroscope` directory when nothing else is in it. The default | | `dashboard` | per store the sink flags name: the dashboard `mikroscope-`, however it was imported, and the datasource `mikroscope-`. Not the folder, an adopted datasource or provisioned alert rules | | `data` | the tables and indices the sinks wrote, and the files the file sinks wrote | | `all` | the three above | The `dashboard` and `data` targets take the [sink](https://docs.jmrp.io/mikroscope/reference/cli/#sinks) and [Grafana](https://docs.jmrp.io/mikroscope/reference/cli/#publishing-to-grafana) flags of `forward`, to find the stores. Of the Grafana flags, `uninstall` reads `--grafana` and `--grafana-datasource-uid`, ignores the others, and refuses `--grafana-dry-run`: its dry run is leaving out `--yes`. When a sink flag names a store, `dashboard` also needs `--grafana` (or `MIKROSCOPE_GRAFANA_URL`, then `GRAFANA_URL`) and `GRAFANA_TOKEN`, and stops with `--targets dashboard needs --grafana …` without a Grafana and `--targets dashboard needs GRAFANA_TOKEN` without the token. Given no sink flag, `--targets dashboard` or `data` finds no store and prints `nothing of this is here to remove`; `all` then acts on the router objects alone. - **Nothing is removed without `--yes`**, the same `--yes` the deployment verbs take. A dropped table cannot be put back the way `install` puts back a router object. - **The stores are listed before the router is touched.** The `dashboard` and `data` targets are listed first, so one that cannot be listed stops the verb before anything is removed, the router objects of `all` included. - **A Grafana it cannot read stops it.** Only a 404 counts as not there. An unreachable Grafana, a refused token or a server error stops the verb with `asking Grafana whether dashboard mikroscope- is there: …` and exit status 1, before anything is removed. - **The tables are asked of the store, never compiled in.** A list inside the binary would be the measurements this version writes, and the ones worth removing are the ones nobody writes any more: what an earlier version collected, or a source switched off since. Everything under the `mikroscope_` prefix is claimed; nothing else is touched. - **An adopted datasource is not removed.** One named in `--grafana-datasource-uid` was somebody else's before this ran and is somebody else's after. - **One that will not go does not stop the rest.** Each failure is printed with what the store said and the removal carries on. > **Three sinks store nothing this can remove** > > `--prom` is scraped rather than written to, so the series live in a Prometheus this has never > heard of and age out with its retention. `--graphite` offers no delete at all: remove the whisper > files by hand. `--sql` writes a file, and rows already loaded into a real database from it have to > be removed there, or with `--postgres` pointed at that database. Each of them prints its own > reason rather than being silently absent. > **InfluxDB 3 deletes a table by renaming it** > > A table deleted through `/api/v3/configure/table` stays in `information_schema` under a name > carrying the deletion instant, `mikroscope_cpu-`. Those are gone and are not offered > again; without that filter an uninstall would list the same tables on every run, delete them > successfully, and never empty. The delete asks for `hard_delete_at=now`, which the server accepts > and schedules. ### `status` ```sh mikroscope status ``` It prints what it read of the install, the ownership count of each step and, when anything is installed, the agent's health, read directly with a 3 s timeout: ```text install on the router (manifest mikroscope/mikroscope.manifest.txt): veth veth-mikroscope, subnet 172.30.10.0/30, lists LAN/LANs, port 9123, … 1 install manifest mikroscope/mikroscope.manifest.txt 1 veth interface veth-mikroscope … agent: 1.6.1 () built