docs: add results cmd documentation.

Help our users understand how to use the experimental commands. Signed-off-by: Gustavo Padovan <[email protected]>
kernelci · Dec 12, 2024 · 81d43d8 · 81d43d8
1 parent f2f4a25
commit 81d43d8
Show file tree

Hide file tree

Showing 2 changed files with 72 additions and 0 deletions.
diff --git a/docs/_index.md b/docs/_index.md
@@ -102,6 +102,12 @@ Example:
 kci-dev --settings /path/to/.kci-dev.toml
 ```
 
+### General Commands
+
+#### results
+
+Pull results from the Dashboard. See detailed [documentation](results).
+
 ### Maestro Commands
 
 #### checkout

diff --git a/docs/results.md b/docs/results.md
@@ -0,0 +1,66 @@
++++
+title = 'results'
+date = 2024-12-10T07:07:07+01:00
+description = 'Fetch results from the KernelCI ecosystem.'
++++
+
+`kci-dev` pulls from our Dashboard API. As of now, it is an EXPERIMENTAL tooling under development with close collaboration from Linux kernel maintainers.
+
+> KNOWN ISSUE: The Dashboard endpoint we are using returns a file of a few megabytes in size, so download may take
+a few seconds, slowing down your usage of `kci-dev results`. We are working on [it](https://github.com/kernelci/dashboard/issues/661).
+
+## Base parameters
+
+### --origin
+
+Set the KCIDB origin desired. 'maestro' is the default.
+
+### --giturl
+
+The url of the tree to fetch results
+
+### --branch
+
+The branch to get results for
+
+### --commit
+
+The tip of tree commit being tested. It needs to be the full commit hash.
+
+Unfortunately the Dashboard API doesn't support git tags as parameters yet.
+
+## Results actions
+
+### --action=summary
+
+Shows a numeric summary of the build, boot and test results.
+If `--action` is omitted, it will show the summary by default.
+
+Example:
+
+```sh
+kci-dev results --giturl 'https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git' --branch master --commit  d1486dca38afd08ca279ae94eb3a397f10737824 --action=summary
+```
+
+### --action=failed-builds
+
+List failed builds.
+
+Example:
+
+```sh
+kci-dev results --giturl 'https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git' --branch master --commit  d1486dca38afd08ca279ae94eb3a397f10737824 --action failed-builds
+```
+
+## Downloading logs
+
+`--download-logs` Download failed logs when used with `--action=failed-*` commands.
+
+Example:
+```sh
+kci-dev results --giturl 'https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git' --branch master --commit  d1486dca38afd08ca279ae94eb3a397f10737824 --action failed-builds --download-logs
+```
+
+
+
+