mr docs check-examples
Walks the command tree, extracts every example tagged # mr-doctest:, and
evaluates each block against the connected server. Per-example metadata on the
label line controls behavior: expect-exit=N, tolerate=/regex/,
skip-on=<env>, timeout=Ns, and stdin=<fixture>. skip-on takes one
environment or a |-separated list of them (skip-on=ephemeral|auth), so an
example that cannot run in more than one environment can say so.
The runner pipes each block through bash -e -o pipefail -c, with cwd set to
cmd/mr/ so examples can reference ./testdata/* fixtures. Requires bash and
jq on PATH. The target server comes from --server, then MAHRESOURCES_URL,
then http://localhost:8181.
--files switches the source from the command tree to markdown outside it:
files, globs, or directories, repeatable, and each .md file's fenced
bash/sh/shell blocks become one doctest apiece. The opt-in is inverted
there, because such a file is examples rather than prose that contains some: a
block runs unless it opens with # mr-doctest: skip, <reason>. The same
per-example metadata is accepted on that directive line. This is what keeps the
installable agent skill under skills/ executable rather than merely plausible.
Those blocks run in a temporary directory, so an example that writes a file
(mrql export -o out.csv) cannot dirty the working tree that CI diffs
afterwards. A relative path in such a block therefore resolves inside that
scratch directory; only stdin=<fixture> still resolves against
cmd/mr/testdata. A listed file with no runnable block is an error rather than
a silent pass, since zero examples look exactly like success.
Usage
mr docs check-examples
Examples
Run against a local ephemeral server
mr docs check-examples --server http://localhost:8181 --environment=ephemeral
Inherit server URL from the environment
MAHRESOURCES_URL=http://localhost:8181 mr docs check-examples --environment=ephemeral
Run the agent skill's markdown examples instead of the command tree's
mr docs check-examples --files skills/mahresources-mrql/SKILL.md --environment=ephemeral
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--environment | string | `` | Target environment label used by skip-on=<env> metadata. Example: ephemeral when targeting a seed-less in-memory server. |
--files | stringArray | [] | Run the fenced bash blocks in these markdown files, globs, or directories instead of the command tree's own examples. Repeatable. |
Inherited global flags
| Flag | Type | Default | Description |
|---|---|---|---|
--json | bool | false | Output raw JSON |
--no-header | bool | false | Omit table headers |
--page | int | 1 | Page number for list commands (default page size: 50) |
--quiet | bool | false | Only output IDs |
Exit Codes
0 if every non-skipped doctest passes its declared expectation; 1 otherwise