From d9d6f831212049cea6c51c384935b9353bc1defd Mon Sep 17 00:00:00 2001
From: ajzobro <241730435+ajzobro@users.noreply.github.com>
Date: Fri, 12 Dec 2025 13:35:53 -0600
Subject: [PATCH 01/14] updated agent_detail view to provide information about
 how many jobs exist across all agent queues

---
 server/devel/create_sample_data.py            |  2 +-
 .../testflinger/templates/agent_detail.html   | 30 ++++++++++++++-----
 server/src/testflinger/views.py               | 17 +++++++++++
 3 files changed, 40 insertions(+), 9 deletions(-)

diff --git a/server/devel/create_sample_data.py b/server/devel/create_sample_data.py
index d6620554a..c2fbb6344 100755
--- a/server/devel/create_sample_data.py
+++ b/server/devel/create_sample_data.py
@@ -112,7 +112,7 @@ def __iter__(self):
                 "state": random.choice(("waiting", "test", "provision")),
             }
             if self.queue_list:
-                agent_data["queues"] = [random.choice(self.queue_list)]
+                agent_data["queues"] = random.sample(self.queue_list, random.randint(1, len(self.queue_list)))
             yield (f"{self.prefix}{agent_num}", agent_data)
 
 
diff --git a/server/src/testflinger/templates/agent_detail.html b/server/src/testflinger/templates/agent_detail.html
index 9b65b035c..15f60d8a6 100644
--- a/server/src/testflinger/templates/agent_detail.html
+++ b/server/src/testflinger/templates/agent_detail.html
@@ -33,14 +33,28 @@ <h1 class="p-heading--3">Agent Detail - {{ agent.name }}</h1>
   </table>
   <h2 class="p-muted-heading">Queues</h2>
   <ul>
-    {% for queue in agent.queues %}
-      <li>
-        <a href="{{ url_for('testflinger.queue_detail', queue_name=queue) }}">{{ queue }}</a>
-        {% if agent.restricted_to[queue]|default([]) %}
-          <small>(restricted to: {{ agent.restricted_to[queue]|join(", ") }})</small>
-        {% endif %}
-      </li>
-    {% endfor %}
+    <table aria-label="Queues table" class="p-table--mobile-card">
+      <thead>
+        <tr>
+          <th>Name</th>
+          <th>Number of jobs</th>
+          <th>Description</th>
+        </tr>
+      </thead>
+      <tbody>
+        {% for queue in agent.queues %}
+          <tr class="searchable-row">
+            <td data-heading="Name">
+              <a href="{{ url_for('testflinger.queue_detail', queue_name=queue.name) }}">{{ queue.name }}</a>
+              {% if agent.restricted_to[queue.name]|default([]) %}
+                <small>(restricted to: {{ agent.restricted_to[queue.name]|join(", ") }})</small>
+              {% endif %}
+            </td>
+            <td data-heading="Number of Unfinished Jobs">{{ queue.numjobs }}</td>
+            <td data-heading="Description">{{ queue.description }}</td>
+          </tr>
+        {% endfor %}
+      </tbody>
   </ul>
   <h2 class="p-muted-heading">Provision History</h2>
   <form action="" method="get" class="p-form--inline">
diff --git a/server/src/testflinger/views.py b/server/src/testflinger/views.py
index 67e20f6da..1ef609bc3 100644
--- a/server/src/testflinger/views.py
+++ b/server/src/testflinger/views.py
@@ -91,6 +91,23 @@ def agent_detail(agent_id):
         for queue in agent_info.get("queues", [])
     }
 
+    queue_info = []
+    for queue_name in agent_info.pop("queues", []):
+        queue_data = mongo.db.queues.find_one({"name": queue_name})
+        if queue_data:
+            queue_data["name"] = queue_name
+            queue_data["numjobs"] = mongo.db.jobs.count_documents(
+                {
+                    "job_data.job_queue": queue_name,
+                    "result_data.job_state": {
+                        "$nin": ["complete", "completed", "cancelled"]
+                    },
+                }
+            )
+            queue_info.append(queue_data)
+
+    agent_info["queues"] = queue_info
+
     # We want to include the start/stop dates so that default values
     # can be filled in for the date pickers
     agent_info["start"] = start_date

From 1bf91f62933c8117745e6a0946a33aea42670f00 Mon Sep 17 00:00:00 2001
From: ajzobro <241730435+ajzobro@users.noreply.github.com>
Date: Fri, 12 Dec 2025 18:40:56 -0600
Subject: [PATCH 02/14] address concern with concept of "advertised" queues

---
 server/devel/create_sample_data.py | 13 +++++++++++--
 server/src/testflinger/views.py    | 24 +++++++++++++-----------
 2 files changed, 24 insertions(+), 13 deletions(-)

diff --git a/server/devel/create_sample_data.py b/server/devel/create_sample_data.py
index c2fbb6344..4aedaa4bd 100755
--- a/server/devel/create_sample_data.py
+++ b/server/devel/create_sample_data.py
@@ -63,7 +63,15 @@ def _server_validator(server: str) -> str:
         "--queues",
         type=int,
         default=10,
-        help="Number of queues to create",
+        help="Number of queues to distribute amongst jobs and agents",
+    )
+
+    parser.add_argument(
+        "-d",
+        "--advertised-queues",
+        type=int,
+        default=1,
+        help="Number of advertised queues to create",
     )
 
     parser.add_argument(
@@ -241,7 +249,8 @@ def main():
     testflinger_client = TestflingerClient(server_url=args.server)
 
     queues = QueueDataGenerator(num_queues=args.queues)
-    testflinger_client.post_queue_data(queues=queues)
+    # configure "advertised" queues:
+    testflinger_client.post_queue_data(random.sample(tuple(queues), random.randint(1, args.advertised_queues)))
     logging.info("Created %s queues", args.queues)
 
     valid_queue_names = extract_queue_names(queues=queues)
diff --git a/server/src/testflinger/views.py b/server/src/testflinger/views.py
index 1ef609bc3..7f85ce370 100644
--- a/server/src/testflinger/views.py
+++ b/server/src/testflinger/views.py
@@ -94,17 +94,19 @@ def agent_detail(agent_id):
     queue_info = []
     for queue_name in agent_info.pop("queues", []):
         queue_data = mongo.db.queues.find_one({"name": queue_name})
-        if queue_data:
-            queue_data["name"] = queue_name
-            queue_data["numjobs"] = mongo.db.jobs.count_documents(
-                {
-                    "job_data.job_queue": queue_name,
-                    "result_data.job_state": {
-                        "$nin": ["complete", "completed", "cancelled"]
-                    },
-                }
-            )
-            queue_info.append(queue_data)
+        if not queue_data:
+            # If it's not an advertised queue, create some dummy data
+            queue_data = {"description": "No description"}
+        queue_data["name"] = queue_name
+        queue_data["numjobs"] = mongo.db.jobs.count_documents(
+            {
+                "job_data.job_queue": queue_name,
+                "result_data.job_state": {
+                    "$nin": ["complete", "completed", "cancelled"]
+                },
+            }
+        )
+        queue_info.append(queue_data)
 
     agent_info["queues"] = queue_info
 

From 43502d1ea808c0875777d10f82d8deeaa194fa79 Mon Sep 17 00:00:00 2001
From: ajzobro <241730435+ajzobro@users.noreply.github.com>
Date: Fri, 12 Dec 2025 18:42:36 -0600
Subject: [PATCH 03/14] reformat source with `djlint --reformat src`

---
 .../testflinger/templates/agent_detail.html   | 106 +++++++++---------
 1 file changed, 53 insertions(+), 53 deletions(-)

diff --git a/server/src/testflinger/templates/agent_detail.html b/server/src/testflinger/templates/agent_detail.html
index 15f60d8a6..5c7786f76 100644
--- a/server/src/testflinger/templates/agent_detail.html
+++ b/server/src/testflinger/templates/agent_detail.html
@@ -55,64 +55,64 @@ <h2 class="p-muted-heading">Queues</h2>
           </tr>
         {% endfor %}
       </tbody>
-  </ul>
-  <h2 class="p-muted-heading">Provision History</h2>
-  <form action="" method="get" class="p-form--inline">
-    <div class="p-form__group">
-      <label for="start-date" class="p-form__label">Start Date</label>
-      <input type="date"
-             id="start-date"
-             name="start"
-             class="p-form__control"
-             value="{{ request.args.get('start', agent.start) }}">
+    </ul>
+    <h2 class="p-muted-heading">Provision History</h2>
+    <form action="" method="get" class="p-form--inline">
+      <div class="p-form__group">
+        <label for="start-date" class="p-form__label">Start Date</label>
+        <input type="date"
+               id="start-date"
+               name="start"
+               class="p-form__control"
+               value="{{ request.args.get('start', agent.start) }}">
+      </div>
+      <div class="p-form__group">
+        <label for="stop-date" class="p-form__label">Stop Date</label>
+        <input type="date"
+               id="stop-date"
+               name="stop"
+               class="p-form__control"
+               value="{{ request.args.get('stop', agent.stop) }}">
+      </div>
+      <button type="submit" class="p-button--positive">Refresh</button>
+    </form>
+    <div>
+      <strong>Provision success rate for this range:</strong> {{ agent.provision_success_rate }}%
     </div>
-    <div class="p-form__group">
-      <label for="stop-date" class="p-form__label">Stop Date</label>
-      <input type="date"
-             id="stop-date"
-             name="stop"
-             class="p-form__control"
-             value="{{ request.args.get('stop', agent.stop) }}">
-    </div>
-    <button type="submit" class="p-button--positive">Refresh</button>
-  </form>
-  <div>
-    <strong>Provision success rate for this range:</strong> {{ agent.provision_success_rate }}%
-  </div>
-  <div>
-    <table>
-      <thead>
-        <tr>
-          <th style="width: 150pt">Finished At</th>
-          <th style="width: 300pt">Job ID</th>
-          <th class="p-table__cell--icon-placeholder" style="width: 75pt">Status</th>
-          <th>Detail</th>
-        </tr>
-      </thead>
-      <tbody>
-        {% for log in agent.provision_log|reverse %}
+    <div>
+      <table>
+        <thead>
           <tr>
-            <td>{{ log.timestamp.strftime("%Y-%m-%d %H:%M:%S") }}</td>
-            <td>
-              <a href="{{ url_for('testflinger.job_detail', job_id=log.job_id) }}">{{ log.job_id }}</a>
-            </td>
-            <td class="u-align--right p-table__cell--icon-placeholder">
-              <i class="{{ 'p-icon--success' if log.exit_code==0 else 'p-icon--error' }}"></i>{{ log.exit_code }}
-            </td>
-            <td>{{ log.detail }}</td>
+            <th style="width: 150pt">Finished At</th>
+            <th style="width: 300pt">Job ID</th>
+            <th class="p-table__cell--icon-placeholder" style="width: 75pt">Status</th>
+            <th>Detail</th>
           </tr>
-        {% endfor %}
-      </tbody>
-    </table>
-  </div>
-  <h2 class="p-muted-heading">Agent Log</h2>
-  <div class="p-code-snippet">
-    <div class="scrollable">
-      <pre class="p-code-snippet__block">
+        </thead>
+        <tbody>
+          {% for log in agent.provision_log|reverse %}
+            <tr>
+              <td>{{ log.timestamp.strftime("%Y-%m-%d %H:%M:%S") }}</td>
+              <td>
+                <a href="{{ url_for('testflinger.job_detail', job_id=log.job_id) }}">{{ log.job_id }}</a>
+              </td>
+              <td class="u-align--right p-table__cell--icon-placeholder">
+                <i class="{{ 'p-icon--success' if log.exit_code==0 else 'p-icon--error' }}"></i>{{ log.exit_code }}
+              </td>
+              <td>{{ log.detail }}</td>
+            </tr>
+          {% endfor %}
+        </tbody>
+      </table>
+    </div>
+    <h2 class="p-muted-heading">Agent Log</h2>
+    <div class="p-code-snippet">
+      <div class="scrollable">
+        <pre class="p-code-snippet__block">
         <code>
             {{ agent.log|join('\n') }}
         </code>
     </pre>
+      </div>
     </div>
-  </div>
-{% endblock content %}
+  {% endblock content %}

From 5eb6eacc5b78e2a3a52d42acea5879bf9aa1eb63 Mon Sep 17 00:00:00 2001
From: ajzobro <241730435+ajzobro@users.noreply.github.com>
Date: Thu, 18 Dec 2025 11:07:00 -0600
Subject: [PATCH 04/14] Update the instructions for starting docker compose
 (version 2.x), fixed the agent detail page, updated the queue description to
 match the display of the queue list page (blank when no description).

---
 server/HACKING.md                             |   2 +-
 .../testflinger/templates/agent_detail.html   | 141 +++++++++---------
 server/src/testflinger/views.py               |   2 +-
 3 files changed, 72 insertions(+), 73 deletions(-)

diff --git a/server/HACKING.md b/server/HACKING.md
index 032feb448..0561da3d5 100644
--- a/server/HACKING.md
+++ b/server/HACKING.md
@@ -16,7 +16,7 @@ This will setup Testflinger running on port 5000, along with MongoDB and Vault.
 To get this running on your system:
 
 ```shell
-docker-compose up -d --build
+docker compose up -d --build
 ```
 
 If you want to manage client credentials in your local database, you can use
diff --git a/server/src/testflinger/templates/agent_detail.html b/server/src/testflinger/templates/agent_detail.html
index 5c7786f76..c32ce8341 100644
--- a/server/src/testflinger/templates/agent_detail.html
+++ b/server/src/testflinger/templates/agent_detail.html
@@ -32,87 +32,86 @@ <h1 class="p-heading--3">Agent Detail - {{ agent.name }}</h1>
     </tbody>
   </table>
   <h2 class="p-muted-heading">Queues</h2>
-  <ul>
-    <table aria-label="Queues table" class="p-table--mobile-card">
+  <table aria-label="Queues table" class="p-table--mobile-card">
+    <thead>
+      <tr>
+        <th>Name</th>
+        <th>Number of jobs</th>
+        <th>Description</th>
+      </tr>
+    </thead>
+    <tbody>
+      {% for queue in agent.queues %}
+        <tr class="searchable-row">
+          <td data-heading="Name">
+            <a href="{{ url_for('testflinger.queue_detail', queue_name=queue.name) }}">{{ queue.name }}</a>
+            {% if agent.restricted_to[queue.name]|default([]) %}
+              <small>(restricted to: {{ agent.restricted_to[queue.name]|join(", ") }})</small>
+            {% endif %}
+          </td>
+          <td data-heading="Number of Unfinished Jobs">{{ queue.numjobs }}</td>
+          <td data-heading="Description">{{ queue.description }}</td>
+        </tr>
+      {% endfor %}
+    </tbody>
+  </table>
+  <h2 class="p-muted-heading">Provision History</h2>
+  <form action="" method="get" class="p-form--inline">
+    <div class="p-form__group">
+      <label for="start-date" class="p-form__label">Start Date</label>
+      <input type="date"
+             id="start-date"
+             name="start"
+             class="p-form__control"
+             value="{{ request.args.get('start', agent.start) }}">
+    </div>
+    <div class="p-form__group">
+      <label for="stop-date" class="p-form__label">Stop Date</label>
+      <input type="date"
+             id="stop-date"
+             name="stop"
+             class="p-form__control"
+             value="{{ request.args.get('stop', agent.stop) }}">
+    </div>
+    <button type="submit" class="p-button--positive">Refresh</button>
+  </form>
+  <div>
+    <strong>Provision success rate for this range:</strong> {{ agent.provision_success_rate }}%
+  </div>
+  <div>
+    <table>
       <thead>
         <tr>
-          <th>Name</th>
-          <th>Number of jobs</th>
-          <th>Description</th>
+          <th style="width: 150pt">Finished At</th>
+          <th style="width: 300pt">Job ID</th>
+          <th class="p-table__cell--icon-placeholder" style="width: 75pt">Status</th>
+          <th>Detail</th>
         </tr>
       </thead>
       <tbody>
-        {% for queue in agent.queues %}
-          <tr class="searchable-row">
-            <td data-heading="Name">
-              <a href="{{ url_for('testflinger.queue_detail', queue_name=queue.name) }}">{{ queue.name }}</a>
-              {% if agent.restricted_to[queue.name]|default([]) %}
-                <small>(restricted to: {{ agent.restricted_to[queue.name]|join(", ") }})</small>
-              {% endif %}
+        {% for log in agent.provision_log|reverse %}
+          <tr>
+            <td>{{ log.timestamp.strftime("%Y-%m-%d %H:%M:%S") }}</td>
+            <td>
+              <a href="{{ url_for('testflinger.job_detail', job_id=log.job_id) }}">{{ log.job_id }}</a>
+            </td>
+            <td class="u-align--right p-table__cell--icon-placeholder">
+              <i class="{{ 'p-icon--success' if log.exit_code==0 else 'p-icon--error' }}"></i>{{ log.exit_code }}
             </td>
-            <td data-heading="Number of Unfinished Jobs">{{ queue.numjobs }}</td>
-            <td data-heading="Description">{{ queue.description }}</td>
+            <td>{{ log.detail }}</td>
           </tr>
         {% endfor %}
       </tbody>
-    </ul>
-    <h2 class="p-muted-heading">Provision History</h2>
-    <form action="" method="get" class="p-form--inline">
-      <div class="p-form__group">
-        <label for="start-date" class="p-form__label">Start Date</label>
-        <input type="date"
-               id="start-date"
-               name="start"
-               class="p-form__control"
-               value="{{ request.args.get('start', agent.start) }}">
-      </div>
-      <div class="p-form__group">
-        <label for="stop-date" class="p-form__label">Stop Date</label>
-        <input type="date"
-               id="stop-date"
-               name="stop"
-               class="p-form__control"
-               value="{{ request.args.get('stop', agent.stop) }}">
-      </div>
-      <button type="submit" class="p-button--positive">Refresh</button>
-    </form>
-    <div>
-      <strong>Provision success rate for this range:</strong> {{ agent.provision_success_rate }}%
-    </div>
-    <div>
-      <table>
-        <thead>
-          <tr>
-            <th style="width: 150pt">Finished At</th>
-            <th style="width: 300pt">Job ID</th>
-            <th class="p-table__cell--icon-placeholder" style="width: 75pt">Status</th>
-            <th>Detail</th>
-          </tr>
-        </thead>
-        <tbody>
-          {% for log in agent.provision_log|reverse %}
-            <tr>
-              <td>{{ log.timestamp.strftime("%Y-%m-%d %H:%M:%S") }}</td>
-              <td>
-                <a href="{{ url_for('testflinger.job_detail', job_id=log.job_id) }}">{{ log.job_id }}</a>
-              </td>
-              <td class="u-align--right p-table__cell--icon-placeholder">
-                <i class="{{ 'p-icon--success' if log.exit_code==0 else 'p-icon--error' }}"></i>{{ log.exit_code }}
-              </td>
-              <td>{{ log.detail }}</td>
-            </tr>
-          {% endfor %}
-        </tbody>
-      </table>
-    </div>
-    <h2 class="p-muted-heading">Agent Log</h2>
-    <div class="p-code-snippet">
-      <div class="scrollable">
-        <pre class="p-code-snippet__block">
+    </table>
+  </div>
+  <h2 class="p-muted-heading">Agent Log</h2>
+  <div class="p-code-snippet">
+    <div class="scrollable">
+      <pre class="p-code-snippet__block">
         <code>
             {{ agent.log|join('\n') }}
         </code>
-    </pre>
-      </div>
+        </pre>
     </div>
-  {% endblock content %}
+  </div>
+{% endblock content %}
diff --git a/server/src/testflinger/views.py b/server/src/testflinger/views.py
index 7f85ce370..9e50fcc41 100644
--- a/server/src/testflinger/views.py
+++ b/server/src/testflinger/views.py
@@ -96,7 +96,7 @@ def agent_detail(agent_id):
         queue_data = mongo.db.queues.find_one({"name": queue_name})
         if not queue_data:
             # If it's not an advertised queue, create some dummy data
-            queue_data = {"description": "No description"}
+            queue_data = {"description": ""}
         queue_data["name"] = queue_name
         queue_data["numjobs"] = mongo.db.jobs.count_documents(
             {

From 7454a1b0281359789c5ec65feb4d56a99ac4b942 Mon Sep 17 00:00:00 2001
From: ajzobro <241730435+ajzobro@users.noreply.github.com>
Date: Thu, 18 Dec 2025 15:51:41 -0600
Subject: [PATCH 05/14] move logic for acquiring the number of waiting/running
 jobs to database.py

---
 server/src/testflinger/database.py | 12 ++++++++++++
 server/src/testflinger/views.py    | 18 ++++--------------
 2 files changed, 16 insertions(+), 14 deletions(-)

diff --git a/server/src/testflinger/database.py b/server/src/testflinger/database.py
index 7f708ef4d..d6910cb6a 100644
--- a/server/src/testflinger/database.py
+++ b/server/src/testflinger/database.py
@@ -280,6 +280,18 @@ def get_jobs_on_queue(queue: str) -> list[dict]:
     return list(jobs)
 
 
+def get_num_incomplete_jobs_on_queue(queue: str) -> int:
+    """Get the number of incomplete jobs on a specific queue."""
+    return mongo.db.jobs.count_documents(
+        {
+            "job_data.job_queue": queue,
+            "result_data.job_state": {
+                "$nin": ["complete", "completed", "cancelled"]
+            },
+        }
+    )
+
+
 def calculate_percentiles(data: list) -> dict:
     """
     Calculate the percentiles of the wait times for each queue.
diff --git a/server/src/testflinger/views.py b/server/src/testflinger/views.py
index 9e50fcc41..f12c16a6b 100644
--- a/server/src/testflinger/views.py
+++ b/server/src/testflinger/views.py
@@ -98,13 +98,8 @@ def agent_detail(agent_id):
             # If it's not an advertised queue, create some dummy data
             queue_data = {"description": ""}
         queue_data["name"] = queue_name
-        queue_data["numjobs"] = mongo.db.jobs.count_documents(
-            {
-                "job_data.job_queue": queue_name,
-                "result_data.job_state": {
-                    "$nin": ["complete", "completed", "cancelled"]
-                },
-            }
+        queue_data["numjobs"] = database.get_num_incomplete_jobs_on_queue(
+            queue_name
         )
         queue_info.append(queue_data)
 
@@ -205,13 +200,8 @@ def queues_data():
 
     # Get job counts for each queue
     for queue in queue_data:
-        queue["numjobs"] = mongo.db.jobs.count_documents(
-            {
-                "job_data.job_queue": queue["name"],
-                "result_data.job_state": {
-                    "$nin": ["complete", "completed", "cancelled"]
-                },
-            }
+        queue["numjobs"] = database.get_num_incomplete_jobs_on_queue(
+            queue["name"]
         )
     return queue_data
 

From 7e378021861b59758c3358531fc59af1ea043a38 Mon Sep 17 00:00:00 2001
From: ajzobro <241730435+ajzobro@users.noreply.github.com>
Date: Thu, 18 Dec 2025 21:11:28 -0600
Subject: [PATCH 06/14] Move get_jobs_status from CLI to client module for
 reusability in support of adding more human readable YAML output format for
 displaying job counts, and included documentation for the various uses of the
 agent-status command.

---
 cli/testflinger_cli/__init__.py    | 74 ++++++++----------------------
 cli/testflinger_cli/client.py      | 74 ++++++++++++++++++++++++++++--
 cli/testflinger_cli/helpers.py     | 24 +++++++++-
 cli/tests/test_cli.py              |  8 +++-
 cli/tests/test_helpers.py          |  5 +-
 docs/how-to/index.rst              |  1 +
 docs/how-to/view-agent-status.rst  | 24 ++++++++++
 server/devel/create_sample_data.py |  8 +++-
 server/src/testflinger/api/v1.py   | 13 +++++-
 server/tests/test_views.py         | 30 +++++++++---
 10 files changed, 184 insertions(+), 77 deletions(-)
 create mode 100644 docs/how-to/view-agent-status.rst

diff --git a/cli/testflinger_cli/__init__.py b/cli/testflinger_cli/__init__.py
index 592583ee4..9fb3b5072 100644
--- a/cli/testflinger_cli/__init__.py
+++ b/cli/testflinger_cli/__init__.py
@@ -350,6 +350,9 @@ def _add_agent_status_args(self, subparsers):
         parser.add_argument(
             "--json", action="store_true", help="Print output in JSON format"
         )
+        parser.add_argument(
+            "--yaml", action="store_true", help="Print output in YAML format"
+        )
 
     def _add_queue_status_args(self, subparsers):
         """Command line arguments for queue status."""
@@ -462,7 +465,10 @@ def agent_status(self):
         """Show the status of a specified agent."""
         try:
             try:
-                agent_status = self.client.get_agent_data(self.args.agent_name)
+                agent_status = self.client.get_agent_data(
+                    self.args.agent_name,
+                    expanded_queue_info=(self.args.json or self.args.yaml),
+                )
             except client.HTTPError as exc:
                 if exc.status == HTTPStatus.NOT_FOUND:
                     sys.exit(f"Agent '{self.args.agent_name}' does not exist.")
@@ -477,13 +483,16 @@ def agent_status(self):
         except UnknownStatusError as exc:
             sys.exit(exc)
 
-        if self.args.json:
+        if self.args.json or self.args.yaml:
             # For unclear historical reasons,
             # the "name" and "state" fields were renamed,
             # so we maintain that for compatibility
             agent_status["agent"] = agent_status.pop("name")
             agent_status["status"] = agent_status.pop("state")
-            output = json.dumps(agent_status, sort_keys=True)
+            if self.args.json:
+                output = json.dumps(agent_status, sort_keys=True)
+            else:  # yaml
+                output = helpers.pretty_yaml_dump(agent_status)
         else:
             output = agent_status["state"]
         print(output)
@@ -492,7 +501,7 @@ def queue_status(self):
         """Show agent and job status in a specified queue."""
         # Get agent and job status data
         agents_status = self._get_agents_status()
-        jobs_status = self._get_jobs_status()
+        jobs_status = self.client.get_jobs_status(self.args.queue_name)
 
         if self.args.json:
             output = self._queue_status_format_json_output(
@@ -533,51 +542,6 @@ def _get_agents_status(self):
         except UnknownStatusError as exc:
             sys.exit(exc)
 
-    def _get_jobs_status(self):
-        """Retrieve the status of jobs in a specified queue."""
-        try:
-            jobs_data = self.client.get_jobs_on_queue(self.args.queue_name)
-        except client.HTTPError as exc:
-            if exc.status == HTTPStatus.NO_CONTENT:
-                jobs_data = []
-            else:
-                logger.debug("Unable to retrieve job data: %s", exc)
-                jobs_data = []
-        except (IOError, ValueError) as exc:
-            logger.debug("Unable to retrieve job data: %s", exc)
-            jobs_data = []
-
-        # Categorize jobs based on completion outcome
-        jobs_waiting = []
-        jobs_running = []
-        jobs_completed = []
-
-        for job in jobs_data:
-            # Handle MongoDB date structure or plain string
-            created_at = job.get("created_at", "")
-            if isinstance(created_at, dict) and "$date" in created_at:
-                created_at = created_at["$date"]
-
-            job_info = {
-                "job_id": job["job_id"],
-                "created_at": created_at,
-            }
-
-            job_state = job.get("job_state", "").lower()
-            if job_state == "waiting":
-                jobs_waiting.append(job_info)
-            elif job_state == "complete":
-                jobs_completed.append(job_info)
-            elif job_state not in ("cancelled",):  # Ignore cancelled jobs
-                # All non-waiting, non-complete, non-cancelled are "running"
-                jobs_running.append(job_info)
-
-        return {
-            "jobs_waiting": jobs_waiting,
-            "jobs_running": jobs_running,
-            "jobs_completed": jobs_completed,
-        }
-
     def _queue_status_format_json_output(self, agents_status, jobs_status):
         """Format queue status output as JSON."""
         output_data = {
@@ -942,9 +906,7 @@ def show(self):
             )
             sys.exit(1)
         if self.args.yaml:
-            to_print = helpers.pretty_yaml_dump(
-                results, sort_keys=True, indent=4, default_flow_style=False
-            )
+            to_print = helpers.pretty_yaml_dump(results)
         else:
             to_print = json.dumps(results, sort_keys=True, indent=4)
         print(to_print)
@@ -1108,14 +1070,14 @@ def do_poll(
                         prev_queue_pos = queue_pos
                         if queue_pos == 0:
                             print(
-                                "This job will be picked up after the "
-                                "current job is complete (it is next in line)"
+                                "This job will be picked up after the current "
+                                "(1) job ahead of it is complete"
                             )
                         else:
                             print(
                                 f"This job will be picked up after the "
-                                f"current job and {queue_pos} job(s) ahead "
-                                f"of it in the queue are complete"
+                                f"{queue_pos + 1} jobs ahead of it in the "
+                                f"queue are complete"
                             )
                 elif last_fragment_number < 0:
                     consecutive_empty_polls += 1
diff --git a/cli/testflinger_cli/client.py b/cli/testflinger_cli/client.py
index cddba73b2..de22b78a8 100644
--- a/cli/testflinger_cli/client.py
+++ b/cli/testflinger_cli/client.py
@@ -244,14 +244,82 @@ def get_status(self, job_id):
         data = json.loads(self.get(endpoint))
         return data.get("job_state")
 
-    def get_agent_data(self, agent_name: str) -> dict:
+    def get_agent_data(
+        self, agent_name: str, expanded_queue_info: bool = False
+    ) -> dict:
         """Get all the data for a specified agent.
 
         :param agent_name: Name of the agent to retrieve its data
+        :param expanded_queue_info: If True, expand queue info with job counts
+                                   (default: False)
         :return: Dict containing all the data from the agent.
         """
         endpoint = f"/v1/agents/data/{agent_name}"
-        return json.loads(self.get(endpoint))
+        data = json.loads(self.get(endpoint))
+        if expanded_queue_info:
+            # TODO: If get_jobs_on_queue could accept a filter to identify
+            #  jobs which are not finished running vs those that are we could
+            #  more readily get the information we need by filtering on the
+            #  server instead of here.
+            queues = data.pop("queues")
+            data["queues"] = {}
+            for queue in queues:
+                jobs = self.get_jobs_status(queue)
+                job_count = len(jobs["jobs_waiting"]) + len(
+                    jobs["jobs_running"]
+                )
+                data["queues"][queue] = {"num_jobs": job_count}
+        return data
+
+    def get_jobs_status(self, queue: str) -> dict:
+        """Retrieve the status of jobs in a specified queue.
+
+        :param queue: Name of the queue to retrieve job status from
+        :return: Dict containing categorized jobs with keys:
+                 'jobs_waiting', 'jobs_running', 'jobs_completed'
+        """
+        try:
+            jobs_data = self.get_jobs_on_queue(queue)
+        except HTTPError as exc:
+            if exc.status == HTTPStatus.NO_CONTENT:
+                jobs_data = []
+            else:
+                logger.debug("Unable to retrieve job data: %s", exc)
+                jobs_data = []
+        except (IOError, ValueError) as exc:
+            logger.debug("Unable to retrieve job data: %s", exc)
+            jobs_data = []
+
+        # Categorize jobs based on completion outcome
+        jobs_waiting = []
+        jobs_running = []
+        jobs_completed = []
+
+        for job in jobs_data:
+            # Handle MongoDB date structure or plain string
+            created_at = job.get("created_at", "")
+            if isinstance(created_at, dict) and "$date" in created_at:
+                created_at = created_at["$date"]
+
+            job_info = {
+                "job_id": job["job_id"],
+                "created_at": created_at,
+            }
+
+            job_state = job.get("job_state", "").lower()
+            if job_state == "waiting":
+                jobs_waiting.append(job_info)
+            elif job_state == "complete":
+                jobs_completed.append(job_info)
+            elif job_state not in ("cancelled",):  # Ignore cancelled jobs
+                # All non-waiting, non-complete, non-cancelled are "running"
+                jobs_running.append(job_info)
+
+        return {
+            "jobs_waiting": jobs_waiting,
+            "jobs_running": jobs_running,
+            "jobs_completed": jobs_completed,
+        }
 
     def get_agent_status_by_queue(self, queue: str) -> list[dict]:
         """Get the status of the agents by a specified queue.
@@ -410,7 +478,7 @@ def get_logs(
         return json.loads(self.get(complete_url_frag))
 
     def get_job_position(self, job_id):
-        """Get the status of a test job.
+        """Get the position of a test job.
 
         :param job_id:
             ID for the test job
diff --git a/cli/testflinger_cli/helpers.py b/cli/testflinger_cli/helpers.py
index 950817448..8377d3ed2 100644
--- a/cli/testflinger_cli/helpers.py
+++ b/cli/testflinger_cli/helpers.py
@@ -157,13 +157,33 @@ def multiline_str_representer(dumper, data):
 yaml.add_representer(str, multiline_str_representer)
 
 
-def pretty_yaml_dump(obj, **kwargs) -> str:
+def pretty_yaml_dump(
+    obj: object,
+    sort_keys: bool = True,
+    indent: int = 2,
+    **kwargs,
+) -> str:
     """Create a pretty YAML representation of obj.
 
     :param obj: The object to be represented.
+    :param sort_keys: Whether to sort keys in the output (default: True).
+    :param indent: Number of spaces to use for indentation (default: 2).
+    :param kwargs: Additional keyword arguments to pass to yaml.dump().
     :return: A pretty representation of obj as a YAML string.
     """
-    return yaml.dump(obj, **kwargs)
+
+    class YamlDumper(yaml.Dumper):
+        def increase_indent(self, flow=False, indentless=False):
+            return super(YamlDumper, self).increase_indent(flow, False)
+
+    return yaml.dump(
+        obj,
+        Dumper=YamlDumper,
+        default_flow_style=False,
+        sort_keys=sort_keys,
+        indent=indent,
+        **kwargs,
+    )
 
 
 def format_timestamp(timestamp_str: str) -> str:
diff --git a/cli/tests/test_cli.py b/cli/tests/test_cli.py
index c170935e2..191d205d7 100644
--- a/cli/tests/test_cli.py
+++ b/cli/tests/test_cli.py
@@ -888,7 +888,8 @@ def test_poll_with_phase_filter(requests_mock):
         }
     }
     requests_mock.get(
-        URL + f"/v1/result/{job_id}/log/output?start_fragment=0&phase=provision",
+        URL
+        + f"/v1/result/{job_id}/log/output?start_fragment=0&phase=provision",
         json=mock_response,
     )
 
@@ -947,7 +948,9 @@ def test_agent_status_json(capsys, requests_mock):
         "provision_streak_count": 1,
         "provision_streak_type": "pass",
     }
+    fake_job_data = []
     requests_mock.get(URL + "/v1/agents/data/" + fake_agent, json=fake_return)
+    requests_mock.get(URL + "/v1/queues/fake/jobs", json=fake_job_data)
     sys.argv = ["", "agent-status", fake_agent, "--json"]
     tfcli = testflinger_cli.TestflingerCli()
     tfcli.agent_status()
@@ -955,7 +958,7 @@ def test_agent_status_json(capsys, requests_mock):
     expected_out = {
         "agent": "fake_agent",
         "status": "waiting",
-        "queues": ["fake"],
+        "queues": {"fake": {"num_jobs": 0}},
         "provision_streak_count": 1,
         "provision_streak_type": "pass",
     }
@@ -1275,6 +1278,7 @@ def combined_log_wrapper_2(
     # Should have slept between iterations
     assert len(sleep_calls) >= 2
 
+
 def test_live_polling_with_empty_poll(capsys, requests_mock, monkeypatch):
     """Test that live output handles empty polls correctly."""
     job_id = str(uuid.uuid1())
diff --git a/cli/tests/test_helpers.py b/cli/tests/test_helpers.py
index c17f951f7..a07a47cdd 100644
--- a/cli/tests/test_helpers.py
+++ b/cli/tests/test_helpers.py
@@ -67,7 +67,4 @@ def test_pretty_yaml_dump():
             other
         """
     )
-    assert (
-        pretty_yaml_dump(multiline, indent=4, default_flow_style=False).strip()
-        == result.strip()
-    )
+    assert pretty_yaml_dump(multiline, indent=4).strip() == result.strip()
diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst
index 6185defcb..a25c33121 100644
--- a/docs/how-to/index.rst
+++ b/docs/how-to/index.rst
@@ -16,6 +16,7 @@ Work with jobs via Testflinger CLI
     cancel-job
     reserve-job
     search-job
+    view-agent-status
     job-priority
     authentication
     manage-client-permissions
diff --git a/docs/how-to/view-agent-status.rst b/docs/how-to/view-agent-status.rst
new file mode 100644
index 000000000..171f01422
--- /dev/null
+++ b/docs/how-to/view-agent-status.rst
@@ -0,0 +1,24 @@
+View agent status
+=================
+
+You can view the status of an agent using the agent-status command. This command
+displays the current state of an agent, including its status and the queues it
+listens to.
+
+.. code-block:: shell
+
+    testflinger-cli agent-status <agent_name>
+
+By default, this command returns a brief status output. You can also request
+structured output in JSON or YAML format using the ``--json`` or ``--yaml`` flags:
+
+.. code-block:: shell
+
+    testflinger-cli agent-status <agent_name> --json
+
+.. code-block:: shell
+
+    testflinger-cli agent-status <agent_name> --yaml
+
+The structured output includes additional information such as the number of jobs
+waiting and running in each queue the agent listens to.
diff --git a/server/devel/create_sample_data.py b/server/devel/create_sample_data.py
index 4aedaa4bd..cc7a97a17 100755
--- a/server/devel/create_sample_data.py
+++ b/server/devel/create_sample_data.py
@@ -120,7 +120,9 @@ def __iter__(self):
                 "state": random.choice(("waiting", "test", "provision")),
             }
             if self.queue_list:
-                agent_data["queues"] = random.sample(self.queue_list, random.randint(1, len(self.queue_list)))
+                agent_data["queues"] = random.sample(
+                    self.queue_list, random.randint(1, len(self.queue_list))
+                )
             yield (f"{self.prefix}{agent_num}", agent_data)
 
 
@@ -250,7 +252,9 @@ def main():
 
     queues = QueueDataGenerator(num_queues=args.queues)
     # configure "advertised" queues:
-    testflinger_client.post_queue_data(random.sample(tuple(queues), random.randint(1, args.advertised_queues)))
+    testflinger_client.post_queue_data(
+        random.sample(tuple(queues), random.randint(1, args.advertised_queues))
+    )
     logging.info("Created %s queues", args.queues)
 
     valid_queue_names = extract_queue_names(queues=queues)
diff --git a/server/src/testflinger/api/v1.py b/server/src/testflinger/api/v1.py
index 858e30415..dc2062e46 100644
--- a/server/src/testflinger/api/v1.py
+++ b/server/src/testflinger/api/v1.py
@@ -784,8 +784,17 @@ def check_valid_uuid(job_id):
 
 
 @v1.get("/job/<job_id>/position")
-def job_position_get(job_id):
-    """Return the position of the specified jobid in the queue."""
+# TODO: This is billed as providing the position in a queue describing at what
+#  point the job will be picked up, however there are certainly cases where
+#  this is an oversimplification as each agent listens to multiple queues.
+#  Therefore, there could be countless other jobs keeping the agents for the
+#  queue which this job is in busy rather than servicing this job.
+def job_position_get(job_id: str) -> tuple[str, int]:
+    """Return the position of the specified jobid in the queue.
+
+    :param job_id: ID of the job to retrieve position for
+    :return: Tuple containing position information and HTTP status code
+    """
     job_data, status = job_get_id(job_id)
     if status == 204:
         return "Job not found or already started\n", 410
diff --git a/server/tests/test_views.py b/server/tests/test_views.py
index 3f89656ef..6ad39f029 100644
--- a/server/tests/test_views.py
+++ b/server/tests/test_views.py
@@ -56,16 +56,34 @@ def test_queues():
     )
     mongo.db.jobs.insert_many(
         [
-            {"job_data": {"job_queue": "advertised_queue1"}},
-            {"job_data": {"job_queue": "advertised_queue1"}},
-            {"job_data": {"job_queue": "advertised_queue1"}},
-            {"job_data": {"job_queue": "advertised_queue2"}},
-            {"job_data": {"job_queue": "advertised_queue2"}},
+            {
+                "job_data": {"job_queue": "advertised_queue1"},
+                "result_data": {"job_state": "waiting"},
+            },
+            {
+                "job_data": {"job_queue": "advertised_queue1"},
+                "result_data": {"job_state": "running"},
+            },
+            {
+                "job_data": {"job_queue": "advertised_queue1"},
+                "result_data": {"job_state": "waiting"},
+            },
+            {
+                "job_data": {"job_queue": "advertised_queue2"},
+                "result_data": {"job_state": "running"},
+            },
+            {
+                "job_data": {"job_queue": "advertised_queue2"},
+                "result_data": {"job_state": "waiting"},
+            },
         ]
     )
 
     # Get the data from the function we use to generate the view
-    with patch("testflinger.views.mongo", mongo):
+    with (
+        patch("testflinger.views.mongo", mongo),
+        patch("testflinger.database.mongo", mongo),
+    ):
         data = queues_data()
 
     # Make sure we found all the queues, not just advertised ones

From e7938419c7f26df5204bcf883bd2babba99d990e Mon Sep 17 00:00:00 2001
From: ajzobro <241730435+ajzobro@users.noreply.github.com>
Date: Fri, 19 Dec 2025 08:33:00 -0600
Subject: [PATCH 07/14] same modifications as were made in many other PRs to
 get the checks to pass

---
 docs/.custom_wordlist.txt | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt
index 2c9e1f36e..dd1d2b771 100644
--- a/docs/.custom_wordlist.txt
+++ b/docs/.custom_wordlist.txt
@@ -1,14 +1,21 @@
 autoinstall
 dragonboard
+fragment_number
 Lenovo
+log_data
 logfile
 muxpi
 netboot
 oemrecovery
+passwordless
+preconfigured
 preloaded
-SDWire
-Tegra
 Queryable
+rclone
+SDWire
 stderr
-fragment_number
-log_data
+supervisord
+systemd
+Tegra
+url
+webdav

From 651ba81bbe4a32a2cbd1ed00f8e7039cb1196194 Mon Sep 17 00:00:00 2001
From: ajzobro <241730435+ajzobro@users.noreply.github.com>
Date: Mon, 5 Jan 2026 15:21:21 -0600
Subject: [PATCH 08/14] split server and client changes due to discussion in PR
 #853

---
 cli/testflinger_cli/__init__.py   | 74 +++++++++++++++++++++++--------
 cli/testflinger_cli/client.py     | 74 ++-----------------------------
 cli/testflinger_cli/helpers.py    | 24 +---------
 cli/tests/test_cli.py             |  8 +---
 cli/tests/test_helpers.py         |  5 ++-
 docs/how-to/index.rst             |  1 -
 docs/how-to/view-agent-status.rst | 24 ----------
 7 files changed, 67 insertions(+), 143 deletions(-)
 delete mode 100644 docs/how-to/view-agent-status.rst

diff --git a/cli/testflinger_cli/__init__.py b/cli/testflinger_cli/__init__.py
index a5323cdf5..d84084904 100644
--- a/cli/testflinger_cli/__init__.py
+++ b/cli/testflinger_cli/__init__.py
@@ -350,9 +350,6 @@ def _add_agent_status_args(self, subparsers):
         parser.add_argument(
             "--json", action="store_true", help="Print output in JSON format"
         )
-        parser.add_argument(
-            "--yaml", action="store_true", help="Print output in YAML format"
-        )
 
     def _add_queue_status_args(self, subparsers):
         """Command line arguments for queue status."""
@@ -465,10 +462,7 @@ def agent_status(self):
         """Show the status of a specified agent."""
         try:
             try:
-                agent_status = self.client.get_agent_data(
-                    self.args.agent_name,
-                    expanded_queue_info=(self.args.json or self.args.yaml),
-                )
+                agent_status = self.client.get_agent_data(self.args.agent_name)
             except client.HTTPError as exc:
                 if exc.status == HTTPStatus.NOT_FOUND:
                     sys.exit(f"Agent '{self.args.agent_name}' does not exist.")
@@ -483,16 +477,13 @@ def agent_status(self):
         except UnknownStatusError as exc:
             sys.exit(exc)
 
-        if self.args.json or self.args.yaml:
+        if self.args.json:
             # For unclear historical reasons,
             # the "name" and "state" fields were renamed,
             # so we maintain that for compatibility
             agent_status["agent"] = agent_status.pop("name")
             agent_status["status"] = agent_status.pop("state")
-            if self.args.json:
-                output = json.dumps(agent_status, sort_keys=True)
-            else:  # yaml
-                output = helpers.pretty_yaml_dump(agent_status)
+            output = json.dumps(agent_status, sort_keys=True)
         else:
             output = agent_status["state"]
         print(output)
@@ -501,7 +492,7 @@ def queue_status(self):
         """Show agent and job status in a specified queue."""
         # Get agent and job status data
         agents_status = self._get_agents_status()
-        jobs_status = self.client.get_jobs_status(self.args.queue_name)
+        jobs_status = self._get_jobs_status()
 
         if self.args.json:
             output = self._queue_status_format_json_output(
@@ -542,6 +533,51 @@ def _get_agents_status(self):
         except UnknownStatusError as exc:
             sys.exit(exc)
 
+    def _get_jobs_status(self):
+        """Retrieve the status of jobs in a specified queue."""
+        try:
+            jobs_data = self.client.get_jobs_on_queue(self.args.queue_name)
+        except client.HTTPError as exc:
+            if exc.status == HTTPStatus.NO_CONTENT:
+                jobs_data = []
+            else:
+                logger.debug("Unable to retrieve job data: %s", exc)
+                jobs_data = []
+        except (IOError, ValueError) as exc:
+            logger.debug("Unable to retrieve job data: %s", exc)
+            jobs_data = []
+
+        # Categorize jobs based on completion outcome
+        jobs_waiting = []
+        jobs_running = []
+        jobs_completed = []
+
+        for job in jobs_data:
+            # Handle MongoDB date structure or plain string
+            created_at = job.get("created_at", "")
+            if isinstance(created_at, dict) and "$date" in created_at:
+                created_at = created_at["$date"]
+
+            job_info = {
+                "job_id": job["job_id"],
+                "created_at": created_at,
+            }
+
+            job_state = job.get("job_state", "").lower()
+            if job_state == "waiting":
+                jobs_waiting.append(job_info)
+            elif job_state == "complete":
+                jobs_completed.append(job_info)
+            elif job_state not in ("cancelled",):  # Ignore cancelled jobs
+                # All non-waiting, non-complete, non-cancelled are "running"
+                jobs_running.append(job_info)
+
+        return {
+            "jobs_waiting": jobs_waiting,
+            "jobs_running": jobs_running,
+            "jobs_completed": jobs_completed,
+        }
+
     def _queue_status_format_json_output(self, agents_status, jobs_status):
         """Format queue status output as JSON."""
         output_data = {
@@ -906,7 +942,9 @@ def show(self):
             )
             sys.exit(1)
         if self.args.yaml:
-            to_print = helpers.pretty_yaml_dump(results)
+            to_print = helpers.pretty_yaml_dump(
+                results, sort_keys=True, indent=4, default_flow_style=False
+            )
         else:
             to_print = json.dumps(results, sort_keys=True, indent=4)
         print(to_print)
@@ -1097,14 +1135,14 @@ def do_poll(
                         prev_queue_pos = queue_pos
                         if queue_pos == 0:
                             print(
-                                "This job will be picked up after the current "
-                                "(1) job ahead of it is complete"
+                                "This job will be picked up after the "
+                                "current job is complete (it is next in line)"
                             )
                         else:
                             print(
                                 f"This job will be picked up after the "
-                                f"{queue_pos + 1} jobs ahead of it in the "
-                                f"queue are complete"
+                                f"current job and {queue_pos} job(s) ahead "
+                                f"of it in the queue are complete"
                             )
                 time.sleep(10)
             except (IOError, client.HTTPError):
diff --git a/cli/testflinger_cli/client.py b/cli/testflinger_cli/client.py
index 69af6d6bf..3343d4959 100644
--- a/cli/testflinger_cli/client.py
+++ b/cli/testflinger_cli/client.py
@@ -245,82 +245,14 @@ def get_status(self, job_id: str) -> dict:
         job_status["job_state"] = data.get("job_state")
         return job_status
 
-    def get_agent_data(
-        self, agent_name: str, expanded_queue_info: bool = False
-    ) -> dict:
+    def get_agent_data(self, agent_name: str) -> dict:
         """Get all the data for a specified agent.
 
         :param agent_name: Name of the agent to retrieve its data
-        :param expanded_queue_info: If True, expand queue info with job counts
-                                   (default: False)
         :return: Dict containing all the data from the agent.
         """
         endpoint = f"/v1/agents/data/{agent_name}"
-        data = json.loads(self.get(endpoint))
-        if expanded_queue_info:
-            # TODO: If get_jobs_on_queue could accept a filter to identify
-            #  jobs which are not finished running vs those that are we could
-            #  more readily get the information we need by filtering on the
-            #  server instead of here.
-            queues = data.pop("queues")
-            data["queues"] = {}
-            for queue in queues:
-                jobs = self.get_jobs_status(queue)
-                job_count = len(jobs["jobs_waiting"]) + len(
-                    jobs["jobs_running"]
-                )
-                data["queues"][queue] = {"num_jobs": job_count}
-        return data
-
-    def get_jobs_status(self, queue: str) -> dict:
-        """Retrieve the status of jobs in a specified queue.
-
-        :param queue: Name of the queue to retrieve job status from
-        :return: Dict containing categorized jobs with keys:
-                 'jobs_waiting', 'jobs_running', 'jobs_completed'
-        """
-        try:
-            jobs_data = self.get_jobs_on_queue(queue)
-        except HTTPError as exc:
-            if exc.status == HTTPStatus.NO_CONTENT:
-                jobs_data = []
-            else:
-                logger.debug("Unable to retrieve job data: %s", exc)
-                jobs_data = []
-        except (IOError, ValueError) as exc:
-            logger.debug("Unable to retrieve job data: %s", exc)
-            jobs_data = []
-
-        # Categorize jobs based on completion outcome
-        jobs_waiting = []
-        jobs_running = []
-        jobs_completed = []
-
-        for job in jobs_data:
-            # Handle MongoDB date structure or plain string
-            created_at = job.get("created_at", "")
-            if isinstance(created_at, dict) and "$date" in created_at:
-                created_at = created_at["$date"]
-
-            job_info = {
-                "job_id": job["job_id"],
-                "created_at": created_at,
-            }
-
-            job_state = job.get("job_state", "").lower()
-            if job_state == "waiting":
-                jobs_waiting.append(job_info)
-            elif job_state == "complete":
-                jobs_completed.append(job_info)
-            elif job_state not in ("cancelled",):  # Ignore cancelled jobs
-                # All non-waiting, non-complete, non-cancelled are "running"
-                jobs_running.append(job_info)
-
-        return {
-            "jobs_waiting": jobs_waiting,
-            "jobs_running": jobs_running,
-            "jobs_completed": jobs_completed,
-        }
+        return json.loads(self.get(endpoint))
 
     def get_agent_status_by_queue(self, queue: str) -> list[dict]:
         """Get the status of the agents by a specified queue.
@@ -479,7 +411,7 @@ def get_logs(
         return json.loads(self.get(complete_url_frag))
 
     def get_job_position(self, job_id):
-        """Get the position of a test job.
+        """Get the status of a test job.
 
         :param job_id:
             ID for the test job
diff --git a/cli/testflinger_cli/helpers.py b/cli/testflinger_cli/helpers.py
index 8377d3ed2..950817448 100644
--- a/cli/testflinger_cli/helpers.py
+++ b/cli/testflinger_cli/helpers.py
@@ -157,33 +157,13 @@ def multiline_str_representer(dumper, data):
 yaml.add_representer(str, multiline_str_representer)
 
 
-def pretty_yaml_dump(
-    obj: object,
-    sort_keys: bool = True,
-    indent: int = 2,
-    **kwargs,
-) -> str:
+def pretty_yaml_dump(obj, **kwargs) -> str:
     """Create a pretty YAML representation of obj.
 
     :param obj: The object to be represented.
-    :param sort_keys: Whether to sort keys in the output (default: True).
-    :param indent: Number of spaces to use for indentation (default: 2).
-    :param kwargs: Additional keyword arguments to pass to yaml.dump().
     :return: A pretty representation of obj as a YAML string.
     """
-
-    class YamlDumper(yaml.Dumper):
-        def increase_indent(self, flow=False, indentless=False):
-            return super(YamlDumper, self).increase_indent(flow, False)
-
-    return yaml.dump(
-        obj,
-        Dumper=YamlDumper,
-        default_flow_style=False,
-        sort_keys=sort_keys,
-        indent=indent,
-        **kwargs,
-    )
+    return yaml.dump(obj, **kwargs)
 
 
 def format_timestamp(timestamp_str: str) -> str:
diff --git a/cli/tests/test_cli.py b/cli/tests/test_cli.py
index 9f01ff7fb..dfc96276e 100644
--- a/cli/tests/test_cli.py
+++ b/cli/tests/test_cli.py
@@ -888,8 +888,7 @@ def test_poll_with_phase_filter(requests_mock):
         }
     }
     requests_mock.get(
-        URL
-        + f"/v1/result/{job_id}/log/output?start_fragment=0&phase=provision",
+        URL + f"/v1/result/{job_id}/log/output?start_fragment=0&phase=provision",
         json=mock_response,
     )
 
@@ -948,9 +947,7 @@ def test_agent_status_json(capsys, requests_mock):
         "provision_streak_count": 1,
         "provision_streak_type": "pass",
     }
-    fake_job_data = []
     requests_mock.get(URL + "/v1/agents/data/" + fake_agent, json=fake_return)
-    requests_mock.get(URL + "/v1/queues/fake/jobs", json=fake_job_data)
     sys.argv = ["", "agent-status", fake_agent, "--json"]
     tfcli = testflinger_cli.TestflingerCli()
     tfcli.agent_status()
@@ -958,7 +955,7 @@ def test_agent_status_json(capsys, requests_mock):
     expected_out = {
         "agent": "fake_agent",
         "status": "waiting",
-        "queues": {"fake": {"num_jobs": 0}},
+        "queues": ["fake"],
         "provision_streak_count": 1,
         "provision_streak_type": "pass",
     }
@@ -1282,7 +1279,6 @@ def combined_log_wrapper_2(
     # Should have slept between iterations
     assert len(sleep_calls) >= 2
 
-
 def test_live_polling_with_empty_poll(capsys, requests_mock, monkeypatch):
     """Test that live output handles empty polls correctly."""
     job_id = str(uuid.uuid1())
diff --git a/cli/tests/test_helpers.py b/cli/tests/test_helpers.py
index a07a47cdd..c17f951f7 100644
--- a/cli/tests/test_helpers.py
+++ b/cli/tests/test_helpers.py
@@ -67,4 +67,7 @@ def test_pretty_yaml_dump():
             other
         """
     )
-    assert pretty_yaml_dump(multiline, indent=4).strip() == result.strip()
+    assert (
+        pretty_yaml_dump(multiline, indent=4, default_flow_style=False).strip()
+        == result.strip()
+    )
diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst
index a25c33121..6185defcb 100644
--- a/docs/how-to/index.rst
+++ b/docs/how-to/index.rst
@@ -16,7 +16,6 @@ Work with jobs via Testflinger CLI
     cancel-job
     reserve-job
     search-job
-    view-agent-status
     job-priority
     authentication
     manage-client-permissions
diff --git a/docs/how-to/view-agent-status.rst b/docs/how-to/view-agent-status.rst
deleted file mode 100644
index 171f01422..000000000
--- a/docs/how-to/view-agent-status.rst
+++ /dev/null
@@ -1,24 +0,0 @@
-View agent status
-=================
-
-You can view the status of an agent using the agent-status command. This command
-displays the current state of an agent, including its status and the queues it
-listens to.
-
-.. code-block:: shell
-
-    testflinger-cli agent-status <agent_name>
-
-By default, this command returns a brief status output. You can also request
-structured output in JSON or YAML format using the ``--json`` or ``--yaml`` flags:
-
-.. code-block:: shell
-
-    testflinger-cli agent-status <agent_name> --json
-
-.. code-block:: shell
-
-    testflinger-cli agent-status <agent_name> --yaml
-
-The structured output includes additional information such as the number of jobs
-waiting and running in each queue the agent listens to.

From d023cd6a791479fa276f45a46c49e402a09906a9 Mon Sep 17 00:00:00 2001
From: Andy Zobro <241730435+ajzobro@users.noreply.github.com>
Date: Mon, 5 Jan 2026 15:40:24 -0600
Subject: [PATCH 09/14] Update server/src/testflinger/api/v1.py

Co-authored-by: rene-oromtz <157750458+rene-oromtz@users.noreply.github.com>
---
 server/src/testflinger/api/v1.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/server/src/testflinger/api/v1.py b/server/src/testflinger/api/v1.py
index dc2062e46..20701e5d0 100644
--- a/server/src/testflinger/api/v1.py
+++ b/server/src/testflinger/api/v1.py
@@ -789,7 +789,7 @@ def check_valid_uuid(job_id):
 #  this is an oversimplification as each agent listens to multiple queues.
 #  Therefore, there could be countless other jobs keeping the agents for the
 #  queue which this job is in busy rather than servicing this job.
-def job_position_get(job_id: str) -> tuple[str, int]:
+def job_position_get(job_id: str) -> dict | str | tuple[str, int]:
     """Return the position of the specified jobid in the queue.
 
     :param job_id: ID of the job to retrieve position for

From b55a7265294b83edc34d6cb6d5ce4ff4303cc512 Mon Sep 17 00:00:00 2001
From: ajzobro <241730435+ajzobro@users.noreply.github.com>
Date: Mon, 5 Jan 2026 15:49:44 -0600
Subject: [PATCH 10/14] revert changes to the api that are unrelated to this
 issue

---
 server/src/testflinger/api/v1.py | 13 ++-----------
 1 file changed, 2 insertions(+), 11 deletions(-)

diff --git a/server/src/testflinger/api/v1.py b/server/src/testflinger/api/v1.py
index dc2062e46..858e30415 100644
--- a/server/src/testflinger/api/v1.py
+++ b/server/src/testflinger/api/v1.py
@@ -784,17 +784,8 @@ def check_valid_uuid(job_id):
 
 
 @v1.get("/job/<job_id>/position")
-# TODO: This is billed as providing the position in a queue describing at what
-#  point the job will be picked up, however there are certainly cases where
-#  this is an oversimplification as each agent listens to multiple queues.
-#  Therefore, there could be countless other jobs keeping the agents for the
-#  queue which this job is in busy rather than servicing this job.
-def job_position_get(job_id: str) -> tuple[str, int]:
-    """Return the position of the specified jobid in the queue.
-
-    :param job_id: ID of the job to retrieve position for
-    :return: Tuple containing position information and HTTP status code
-    """
+def job_position_get(job_id):
+    """Return the position of the specified jobid in the queue."""
     job_data, status = job_get_id(job_id)
     if status == 204:
         return "Job not found or already started\n", 410

From 9a41fa6080fc7d88c815e7b5805a43126699166b Mon Sep 17 00:00:00 2001
From: ajzobro <241730435+ajzobro@users.noreply.github.com>
Date: Tue, 6 Jan 2026 11:13:45 -0600
Subject: [PATCH 11/14] restore docs dir, this effort has no changes to docs/

---
 docs/.custom_wordlist.txt | 15 ++++-----------
 1 file changed, 4 insertions(+), 11 deletions(-)

diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt
index dd1d2b771..2c9e1f36e 100644
--- a/docs/.custom_wordlist.txt
+++ b/docs/.custom_wordlist.txt
@@ -1,21 +1,14 @@
 autoinstall
 dragonboard
-fragment_number
 Lenovo
-log_data
 logfile
 muxpi
 netboot
 oemrecovery
-passwordless
-preconfigured
 preloaded
-Queryable
-rclone
 SDWire
-stderr
-supervisord
-systemd
 Tegra
-url
-webdav
+Queryable
+stderr
+fragment_number
+log_data

From e9614ce139be4f0ad663089c1a642618b742aabd Mon Sep 17 00:00:00 2001
From: ajzobro <241730435+ajzobro@users.noreply.github.com>
Date: Tue, 6 Jan 2026 16:58:37 -0600
Subject: [PATCH 12/14] improve test coverage

---
 server/tests/test_views.py | 43 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/server/tests/test_views.py b/server/tests/test_views.py
index 6ad39f029..ce91fd417 100644
--- a/server/tests/test_views.py
+++ b/server/tests/test_views.py
@@ -167,6 +167,49 @@ def test_agent_detail_with_restricted_to(testapp):
     assert "(restricted to: test-client-id)" in html
 
 
+def test_agent_detail_with_non_advertised_queue(testapp):
+    """Test that agent detail page handles both advertised and non-advertised queues."""
+    mongo = mongomock.MongoClient()
+    # Insert one advertised queue
+    mongo.db.queues.insert_one(
+        {"name": "advertised_queue", "description": "advertised description"}
+    )
+    # Agent listens to both advertised and non-advertised queues
+    mongo.db.agents.insert_one(
+        {
+            "name": "agent1",
+            "queues": ["advertised_queue", "non_advertised_queue"],
+            "updated_at": datetime.now(tz=timezone.utc),
+        }
+    )
+    mongo.db.jobs.insert_many(
+        [
+            {
+                "job_data": {"job_queue": "advertised_queue"},
+                "result_data": {"job_state": "waiting"},
+            },
+            {
+                "job_data": {"job_queue": "non_advertised_queue"},
+                "result_data": {"job_state": "running"},
+            },
+        ]
+    )
+
+    with (
+        patch("testflinger.views.mongo", mongo),
+        patch("testflinger.database.mongo", mongo),
+    ):
+        with testapp.test_request_context():
+            response = agent_detail("agent1")
+
+    html = str(response)
+    # Should include both advertised and non-advertised queues
+    assert "advertised_queue" in html
+    assert "non_advertised_queue" in html
+    # Non-advertised queue creates dummy data with empty description
+    assert "advertised description" in html
+
+
 def test_job_not_found(testapp):
     """
     Test that the job_detail fails gracefully when

From 993329bbffd18eb7958a2562eebfc46b80108184 Mon Sep 17 00:00:00 2001
From: ajzobro <241730435+ajzobro@users.noreply.github.com>
Date: Wed, 7 Jan 2026 10:30:13 -0600
Subject: [PATCH 13/14] updated line lengths and ran uvx ruff format to correct
 style in server directory

---
 server/devel/openapi_app.py               |  8 +++++---
 server/scripts/generate_openapi_schema.py | 18 ++++++++++++------
 server/tests/test_views.py                |  4 +++-
 3 files changed, 20 insertions(+), 10 deletions(-)

diff --git a/server/devel/openapi_app.py b/server/devel/openapi_app.py
index 1215fe6d6..441afa7ad 100644
--- a/server/devel/openapi_app.py
+++ b/server/devel/openapi_app.py
@@ -18,22 +18,24 @@
 
 This module creates a lightweight Testflinger server instance specifically
 for extracting the OpenAPI specification without requiring MongoDB or other
-external dependencies. 
-It's used by the APIFlask to generate the API spec in JSON format. 
+external dependencies.
+It's used by the APIFlask to generate the API spec in JSON format.
 (https://apiflask.com/openapi/#the-flask-spec-command)
 
 Usage:
     uvx --with tox-uv tox -e schema
 """
 
-from dataclasses import dataclass 
+from dataclasses import dataclass
 from testflinger.application import create_flask_app
 
+
 @dataclass
 class OpenAPIConfig:
     """Config for Testing."""
 
     TESTING = True
 
+
 # Create and expose the app in TESTING mode for Flask CLI to use
 app = create_flask_app(OpenAPIConfig)
diff --git a/server/scripts/generate_openapi_schema.py b/server/scripts/generate_openapi_schema.py
index 293a32511..0f89cfe8a 100755
--- a/server/scripts/generate_openapi_schema.py
+++ b/server/scripts/generate_openapi_schema.py
@@ -53,7 +53,7 @@ def generate_schema() -> dict:
 
 def normalize_json(data: dict) -> str:
     """Normalize JSON to compact form for comparison"""
-    return json.dumps(data, sort_keys=True, separators=(',', ':'))
+    return json.dumps(data, sort_keys=True, separators=(",", ":"))
 
 
 def diff_schemas(local_schema_path: Path) -> bool:
@@ -70,7 +70,10 @@ def diff_schemas(local_schema_path: Path) -> bool:
     generated = generate_schema()
 
     if not local_schema_path.exists():
-        print(f"Error: Expected schema file not found: {local_schema_path}", file=sys.stderr)
+        print(
+            f"Error: Expected schema file not found: {local_schema_path}",
+            file=sys.stderr,
+        )
         return False
 
     with local_schema_path.open() as f:
@@ -83,7 +86,10 @@ def diff_schemas(local_schema_path: Path) -> bool:
     if generated_normalized != local_normalized:
         print("Error: OpenAPI schema is out of date", file=sys.stderr)
         print("", file=sys.stderr)
-        print("To update the schema, run from server/ directory:", file=sys.stderr)
+        print(
+            "To update the schema, run from server/ directory:",
+            file=sys.stderr,
+        )
         print(f"  uvx --with tox-uv tox run -e schema", file=sys.stderr)
         return False
 
@@ -99,13 +105,13 @@ def main():
         "-o",
         type=Path,
         default=None,
-        help="Write schema to specified file (default is stdout)"
+        help="Write schema to specified file (default is stdout)",
     )
     parser.add_argument(
         "--diff",
         "-d",
         type=Path,
-        help="Compare generated schema with the specified file for validation"
+        help="Compare generated schema with the specified file for validation",
     )
 
     args = parser.parse_args()
@@ -124,7 +130,7 @@ def main():
         args.output.parent.mkdir(parents=True, exist_ok=True)
         with args.output.open("w") as f:
             json.dump(schema, f, indent=2, sort_keys=True)
-            f.write("\n")       # trailing linebreak
+            f.write("\n")  # trailing linebreak
         print(f" Schema written to: {args.output}")
     else:
         print(json.dumps(schema, indent=2, sort_keys=True))
diff --git a/server/tests/test_views.py b/server/tests/test_views.py
index ce91fd417..63a7d514e 100644
--- a/server/tests/test_views.py
+++ b/server/tests/test_views.py
@@ -168,7 +168,9 @@ def test_agent_detail_with_restricted_to(testapp):
 
 
 def test_agent_detail_with_non_advertised_queue(testapp):
-    """Test that agent detail page handles both advertised and non-advertised queues."""
+    """
+    Test that agent detail page handles both advertised and non-advertised queues.
+    """
     mongo = mongomock.MongoClient()
     # Insert one advertised queue
     mongo.db.queues.insert_one(

From 2ba519c524cf82a8ddf86186dcf72336e5658671 Mon Sep 17 00:00:00 2001
From: ajzobro <241730435+ajzobro@users.noreply.github.com>
Date: Thu, 8 Jan 2026 09:40:21 -0600
Subject: [PATCH 14/14] fix docstring

---
 server/tests/test_views.py | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/server/tests/test_views.py b/server/tests/test_views.py
index 63a7d514e..0969bafd9 100644
--- a/server/tests/test_views.py
+++ b/server/tests/test_views.py
@@ -168,9 +168,7 @@ def test_agent_detail_with_restricted_to(testapp):
 
 
 def test_agent_detail_with_non_advertised_queue(testapp):
-    """
-    Test that agent detail page handles both advertised and non-advertised queues.
-    """
+    """Test agent detail with advertised and non-advertised queues."""
     mongo = mongomock.MongoClient()
     # Insert one advertised queue
     mongo.db.queues.insert_one(