feat: axon list with pagination and api-client upgrade (#184)

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->
## Summary

Adds CLI support for listing active axons with cursor-style pagination
(`limit`, `starting_after`, `has_more`), matching the updated backend
contract.

## Changes

- **Dependency:** Bump `@runloop/api-client` to `1.14.1` (includes
`client.axons` and other API updates).
- **Devbox tunnel:** Replace removed `createTunnel` with `enableTunnel`
and construct the V2 tunnel URL from `tunnel_key` and port (required for
the upgraded client to compile).
- **New command:** `rli axon list` with `--limit`, `--starting-after`,
and `-o/--output` (text default; json/yaml supported). Default `--limit
0` means fetch all pages when not using `--starting-after`.
- **Service:** `listActiveAxons` passes query params via request `query`
and reads optional `has_more` from the JSON response (forward-compatible
until the published client types catch up).
- **Docs:** README command section updated via `docs:commands`.

## Usage

```bash
rli axon list
rli axon list --limit 50
rli axon list --starting-after <last_axon_id> --limit 100
rli axon list -o json
```

## Testing

- `pnpm run build` — pass
- `pnpm test` — unit/router tests pass; e2e fails without a valid
`RUNLOOP_API_KEY` (pre-existing environment constraint)
<!-- CURSOR_AGENT_PR_BODY_END -->

[Slack
Thread](https://runloophq.slack.com/archives/C0AH4DJ5HB8/p1774575256282429?thread_ts=1774575256.282429&cid=C0AH4DJ5HB8)

<div><a
href="https://cursor.com/agents/bc-ffbec2da-fab8-5f94-a065-a185ecd8f447"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-web-light.png"><img
alt="Open in Web" width="114" height="28"
src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a>&nbsp;<a
href="https://cursor.com/background-agent?bcId=bc-ffbec2da-fab8-5f94-a065-a185ecd8f447"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img
alt="Open in Cursor" width="131" height="28"
src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a>&nbsp;</div>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>

Author: alb-rl

README.md

@@ -181,6 +181,12 @@ rli mcp start                            # Start the MCP server
 rli mcp install                          # Install Runloop MCP server configurat...
 ```
 
+### Axon Commands
+
+```bash
+rli axon list                            # List active axons
+```
+
 ### Scenario Commands (alias: `scn`)
 
 ```bash

package.json

@@ -72,7 +72,7 @@
   "dependencies": {
     "@js-temporal/polyfill": "^0.5.1",
     "@modelcontextprotocol/sdk": "^1.26.0",
-    "@runloop/api-client": "1.10.3",
+    "@runloop/api-client": "1.16.0",
     "@types/express": "^5.0.6",
     "adm-zip": "^0.5.16",
     "chalk": "^5.6.2",

pnpm-lock.yaml

@@ -0,0 +1,106 @@
+/**
+ * List active axons (beta)
+ */
+
+import chalk from "chalk";
+import { formatTimeAgo } from "../../components/ResourceListView.js";
+import { listActiveAxons, type Axon } from "../../services/axonService.js";
+import { output, outputError, parseLimit } from "../../utils/output.js";
+
+interface ListOptions {
+  limit?: string;
+  startingAfter?: string;
+  output?: string;
+}
+
+const PAGE_SIZE = 100;
+
+function printTable(axons: Axon[]): void {
+  if (axons.length === 0) {
+    console.log(chalk.dim("No active axons found"));
+    return;
+  }
+
+  const COL_ID = 34;
+  const COL_NAME = 28;
+  const COL_CREATED = 12;
+
+  const header =
+    "ID".padEnd(COL_ID) +
+    " " +
+    "NAME".padEnd(COL_NAME) +
+    " " +
+    "CREATED".padEnd(COL_CREATED);
+  console.log(chalk.bold(header));
+  console.log(chalk.dim("─".repeat(header.length)));
+
+  for (const axon of axons) {
+    const id =
+      axon.id.length > COL_ID ? axon.id.slice(0, COL_ID - 1) + "…" : axon.id;
+    const nameRaw = axon.name ?? "";
+    const name =
+      nameRaw.length > COL_NAME
+        ? nameRaw.slice(0, COL_NAME - 1) + "…"
+        : nameRaw;
+    const created = formatTimeAgo(axon.created_at_ms);
+    console.log(
+      `${id.padEnd(COL_ID)} ${name.padEnd(COL_NAME)} ${created.padEnd(COL_CREATED)}`,
+    );
+  }
+
+  console.log();
+  console.log(
+    chalk.dim(`${axons.length} axon${axons.length !== 1 ? "s" : ""}`),
+  );
+}
+
+export async function listAxonsCommand(options: ListOptions): Promise<void> {
+  try {
+    const maxResults = parseLimit(options.limit);
+    const format = options.output || "text";
+
+    let axons: Axon[];
+
+    if (options.startingAfter) {
+      const pageLimit = maxResults === Infinity ? PAGE_SIZE : maxResults;
+      const { axons: page, hasMore } = await listActiveAxons({
+        limit: pageLimit,
+        startingAfter: options.startingAfter,
+      });
+      axons = page;
+      if (format === "text" && hasMore && axons.length > 0) {
+        console.log(
+          chalk.dim(
+            "More results may be available; use --starting-after with the last ID to continue.",
+          ),
+        );
+        console.log();
+      }
+    } else {
+      const all: Axon[] = [];
+      let cursor: string | undefined;
+      while (all.length < maxResults) {
+        const remaining = maxResults - all.length;
+        const pageLimit = Math.min(PAGE_SIZE, remaining);
+        const { axons: page, hasMore } = await listActiveAxons({
+          limit: pageLimit,
+          startingAfter: cursor,
+        });
+        all.push(...page);
+        if (!hasMore || page.length === 0) {
+          break;
+        }
+        cursor = page[page.length - 1].id;
+      }
+      axons = all;
+    }
+
+    if (format !== "text") {
+      output(axons, { format, defaultFormat: "json" });
+    } else {
+      printTable(axons);
+    }
+  } catch (error) {
+    outputError("Failed to list active axons", error);
+  }
+}

src/commands/axon/list.ts

@@ -100,7 +100,10 @@ function buildScenarioOutcomeMap(
   const map = new Map<string, ScenarioOutcome>();
   for (const outcome of job.benchmark_outcomes || []) {
     for (const scenario of outcome.scenario_outcomes || []) {
-      map.set(scenario.scenario_run_id, scenario);
+      const runId = scenario.scenario_run_id;
+      if (runId) {
+        map.set(runId, scenario);
+      }
     }
   }
   return map;

src/commands/benchmark-job/logs.ts

@@ -12,7 +12,7 @@ import {
   type DetailSection,
   type ResourceOperation,
 } from "./ResourceDetailPage.js";
-import { getDevboxUrl } from "../utils/url.js";
+import { getDevboxUrl, getDevboxTunnelUrlPattern } from "../utils/url.js";
 import { colors } from "../utils/theme.js";
 import { formatTimeAgo } from "../utils/time.js";
 import { getMcpConfig } from "../services/mcpConfigService.js";
@@ -339,7 +339,7 @@ export const DevboxDetailPage = ({ devbox, onBack }: DevboxDetailPageProps) => {
     if (devbox.tunnel && devbox.tunnel.tunnel_key) {
       const tunnelKey = devbox.tunnel.tunnel_key;
       const authMode = devbox.tunnel.auth_mode;
-      const tunnelUrl = `https://{port}-${tunnelKey}.tunnel.runloop.ai`;
+      const tunnelUrl = getDevboxTunnelUrlPattern(tunnelKey);
 
       detailFields.push({
         label: "Tunnel",
@@ -651,7 +651,7 @@ export const DevboxDetailPage = ({ devbox, onBack }: DevboxDetailPageProps) => {
         </Text>,
       );
 
-      const tunnelUrl = `https://{port}-${devbox.tunnel.tunnel_key}.tunnel.runloop.ai`;
+      const tunnelUrl = getDevboxTunnelUrlPattern(devbox.tunnel.tunnel_key);
       lines.push(
         <Text key="tunnel-url" color={colors.success}>
           {" "}

src/components/DevboxDetailPage.tsx

@@ -0,0 +1,47 @@
+/**
+ * Axon service — active axons listing (beta API)
+ */
+import { getClient } from "../utils/client.js";
+import type { AxonView } from "@runloop/api-client/resources/axons/axons";
+import type { AxonsCursorIDPage } from "@runloop/api-client/pagination";
+
+export type Axon = AxonView;
+
+export interface ListActiveAxonsOptions {
+  limit?: number;
+  startingAfter?: string;
+}
+
+export interface ListActiveAxonsResult {
+  axons: Axon[];
+  hasMore: boolean;
+}
+
+/**
+ * List active axons with optional cursor pagination (`limit`, `starting_after`).
+ */
+export async function listActiveAxons(
+  options: ListActiveAxonsOptions,
+): Promise<ListActiveAxonsResult> {
+  const client = getClient();
+
+  const query: {
+    limit?: number;
+    starting_after?: string;
+  } = {};
+  if (options.limit !== undefined) {
+    query.limit = options.limit;
+  }
+  if (options.startingAfter) {
+    query.starting_after = options.startingAfter;
+  }
+
+  const page = (await client.axons.list(
+    Object.keys(query).length > 0 ? query : undefined,
+  )) as AxonsCursorIDPage<AxonView>;
+
+  const axons = page.axons || [];
+  const hasMore = page.has_more || false;
+
+  return { axons, hasMore };
+}

src/services/axonService.ts

@@ -3,6 +3,7 @@
  * Returns plain data objects with no SDK reference retention
  */
 import { getClient } from "../utils/client.js";
+import { getTunnelBaseHost } from "../utils/url.js";
 import type { Devbox } from "../store/devboxStore.js";
 import type { DevboxesCursorIDPage } from "@runloop/api-client/pagination";
 import type {
@@ -254,17 +255,18 @@ export async function createSSHKey(id: string): Promise<{
 }
 
 /**
- * Create tunnel to devbox
+ * Enable V2 HTTP tunnel on devbox and return the public URL for the given port.
  */
 export async function createTunnel(
   id: string,
   port: number,
 ): Promise<{ url: string }> {
   const client = getClient();
-  const tunnel = await client.devboxes.createTunnel(id, { port });
+  const tunnel = await client.devboxes.enableTunnel(id);
+  const url = `https://${port}-${tunnel.tunnel_key}.${getTunnelBaseHost()}`;
 
   return {
-    url: String((tunnel as any).url || "").substring(0, 500),
+    url: url.substring(0, 500),
   };
 }
 

src/services/devboxService.ts

@@ -1012,6 +1012,26 @@ export function createProgram(): Command {
       await installMcpConfig();
     });
 
+  // Axon commands (beta)
+  const axon = program.command("axon").description("Manage axons (beta)");
+
+  axon
+    .command("list")
+    .description("List active axons")
+    .option("--limit <n>", "Max axons to return (0 = unlimited)", "0")
+    .option(
+      "--starting-after <id>",
+      "Starting point for cursor pagination (axon ID)",
+    )
+    .option(
+      "-o, --output [format]",
+      "Output format: text|json|yaml (default: text)",
+    )
+    .action(async (options) => {
+      const { listAxonsCommand } = await import("../commands/axon/list.js");
+      await listAxonsCommand(options);
+    });
+
   // Scenario commands
   const scenario = program
     .command("scenario")

src/utils/commands.ts

@@ -42,3 +42,18 @@ export function getSettingsUrl(): string {
   const baseUrl = getBaseUrl();
   return `${baseUrl}/settings`;
 }
+
+/**
+ * Hostname for V2 devbox tunnel URLs (matches RUNLOOP_ENV / API host).
+ */
+export function getTunnelBaseHost(): string {
+  const env = process.env.RUNLOOP_ENV?.toLowerCase();
+  return env === "dev" ? "tunnel.runloop.pro" : "tunnel.runloop.ai";
+}
+
+/**
+ * Tunnel URL pattern with a literal `{port}` placeholder for display.
+ */
+export function getDevboxTunnelUrlPattern(tunnelKey: string): string {
+  return `https://{port}-${tunnelKey}.${getTunnelBaseHost()}`;
+}