From 81d43d814baca0fc4fcec951fe19dd5a9478c367 Mon Sep 17 00:00:00 2001
From: Gustavo Padovan <gustavo.padovan@collabora.com>
Date: Tue, 10 Dec 2024 20:20:44 -0300
Subject: [PATCH] docs: add results cmd documentation.

Help our users understand how to use the experimental commands.

Signed-off-by: Gustavo Padovan <gustavo.padovan@collabora.com>
---
 docs/_index.md  |  6 +++++
 docs/results.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 72 insertions(+)
 create mode 100644 docs/results.md

diff --git a/docs/_index.md b/docs/_index.md
index 2debbb7..ee8d342 100644
--- 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
new file mode 100644
index 0000000..8d93ebf
--- /dev/null
+++ 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
+```
+
+
+
+