Docs about RunMe CLI run <command> are unclear

[jlewi]

The documentation about how to run commands directly isn't that clear.
Specifically this section
https://docs.runme.dev/how-runme-works/cli#running-commands-directly

In particular there are a couple things that aren't clear

1. What is a command?
   • It looks like a command in this case is the name assigned to a particular cell in the metadata of the code cell
   • My original interpretation was that command was a file
2. If you don't specify a filename with "--filename" how does it determine what markdown file to look at?
   • I suspect its looking over markdown files and then loading them up but I'm not really sure.

For context, I was trying to figure out how the test rule in vsode-runme works
https://github.com/stateful/vscode-runme/blob/1dbf5f1fb8f7a2d64fc6d811b6d7d5f13b500dbd/package.json#L1067
That runs the command runme run test. It looks like the command argument is matching cell names in CONTRIBUTING.md. Its not entirely clear to me how the CLI knows to look at CONTRIBUTING.md. I assume its looking at all markdown files. This is non obvious because the default for "--filename" is README.md so my initial assumption was that it looks at README.md in which case I didn't understand how it was finding the cells to execute.

[sourishkrout]

That's great feedback, @jlewi. We're definitely criss-crossing terminology there. We'll get that updated.

Getting ahead of editing the docs, we do actually have a blog that is explain this much better. The runme CLI interface considers all markdown files (respecting .gitignore etc). If a single "named" cell/task exists all unnamed will be filtered out. A good way to get an overview is to run runme ls vs runme ls --allow-unnamed. Or, runme tui and press the u key to toggle named vs unnamed. Btw, the same repo/project loader is integrated in vscode from the Run Task in the command palette.

For context, I was trying to figure out how the test rule in vsode-runme works
https://github.com/stateful/vscode-runme/blob/1dbf5f1fb8f7a2d64fc6d811b6d7d5f13b500dbd/package.json#L1067
That runs the command runme run test.

Recursion is at play here where test runs other cells. A way to inspect this is:

$ runme print test
` ` `sh {"id":"01HF7VQMH8ESX1EFV4PFZ87Q58","name":"test"}
export NODE_OPTIONS="--experimental-specifier-resolution=node --max-old-space-size=8192"
npx runme run test:format test:lint test:unit test:e2e
` ` `

GHA will run runme print test:ci which works similarly with the goal to run "the docs" on every build.