Add auth status command and scope guidance

Author: pweiskircher

API.md

@@ -111,6 +111,61 @@ This keeps automation predictable while allowing full passthrough.
 
 ## MVP commands
 
+## `auth.status`
+
+Read the token details and report whether required scopes are present.
+
+Required scopes for this CLI:
+
+- `read_builds`
+- `read_build_logs`
+- `read_artifacts`
+
+### Success response
+
+```json
+{
+  "ok": true,
+  "apiVersion": "v1",
+  "command": "auth.status",
+  "request": {},
+  "summary": {
+    "requiredScopes": [
+      "read_builds",
+      "read_build_logs",
+      "read_artifacts"
+    ],
+    "grantedScopes": 3,
+    "missingScopes": [],
+    "ready": true
+  },
+  "pagination": null,
+  "data": {
+    "token": {
+      "uuid": "019c...",
+      "description": "local cli token",
+      "createdAt": "2026-02-08T20:15:32Z",
+      "scopes": [
+        "read_builds",
+        "read_build_logs",
+        "read_artifacts"
+      ]
+    },
+    "user": {
+      "name": "Pat Example",
+      "email": "pat@example.com"
+    },
+    "requiredScopes": [
+      "read_builds",
+      "read_build_logs",
+      "read_artifacts"
+    ],
+    "missingScopes": []
+  },
+  "error": null
+}
+```
+
 ## `builds.list`
 
 List builds globally, by organization, or by pipeline.
@@ -442,6 +497,7 @@ List build annotations.
 
 ## Mapping to Buildkite REST endpoints
 
+- `auth.status` -> `GET /v2/access-token`
 - `builds.list` -> `GET /v2/builds` or `GET /v2/organizations/{org}/builds` or `GET /v2/organizations/{org}/pipelines/{pipeline}/builds`
 - `builds.get` -> `GET /v2/organizations/{org}/pipelines/{pipeline}/builds/{number}`
 - `jobs.log.get` -> `GET /v2/organizations/{org}/pipelines/{pipeline}/builds/{number}/jobs/{job.id}/log`
@@ -460,4 +516,3 @@ These are strong candidates for the next version:
 - `jobs.unblock`
 - `jobs.env.get`
 - `pipelines.list`
-- `auth.status`

README.md

@@ -40,6 +40,7 @@ Set one of these environment variables:
 ## Commands
 
 ```bash
+bkci auth status
 bkci builds list --org ORG [--pipeline PIPELINE] [--branch BRANCH] [--state STATE]
 bkci builds get --org ORG --pipeline PIPELINE --build BUILD_NUMBER
 bkci jobs log get --org ORG --pipeline PIPELINE --build BUILD_NUMBER --job JOB_ID
@@ -48,8 +49,15 @@ bkci artifacts download --org ORG --pipeline PIPELINE --build BUILD_NUMBER [--jo
 bkci annotations list --org ORG --pipeline PIPELINE --build BUILD_NUMBER
 ```
 
+## Required token scopes
+
+- `read_builds`
+- `read_build_logs`
+- `read_artifacts`
+
 ## Notes
 
 - Use `--raw` on any command to return raw Buildkite payloads inside the envelope.
+- `bkci auth status` checks token scopes and reports missing required scopes.
 - `jobs log get` strips ANSI/control sequences in normalized mode for cleaner LLM output.
 - Pagination metadata is parsed from Buildkite `Link` headers for list endpoints.

src/cli/execute-command.test.ts

@@ -48,6 +48,42 @@ function createMockClient(options: {
   };
 }
 
+test("executeCommand auth.status returns required scope diagnostics", async () => {
+  const command = parseCliArgs(["auth", "status"]);
+
+  const client = createMockClient({
+    jsonResponses: [
+      {
+        status: 200,
+        headers: new Headers(),
+        requestId: "req-auth",
+        data: {
+          uuid: "token-1",
+          description: "Agent token",
+          scopes: ["read_builds", "read_build_logs"],
+          created_at: "2026-02-08T20:00:00Z",
+          user: {
+            name: "Pat",
+            email: "pat@example.com",
+          },
+        },
+      },
+    ],
+  });
+
+  const result = await executeCommand({ command, client });
+
+  assert.deepEqual(result.summary, {
+    requiredScopes: ["read_builds", "read_build_logs", "read_artifacts"],
+    grantedScopes: 2,
+    missingScopes: ["read_artifacts"],
+    ready: false,
+  });
+
+  const data = result.data as Record<string, unknown>;
+  assert.deepEqual(data.missingScopes, ["read_artifacts"]);
+});
+
 test("executeCommand builds.list normalizes data and pagination", async () => {
   const command = parseCliArgs(["builds", "list", "--org", "acme", "--pipeline", "web"]);
   const headers = new Headers({

src/cli/execute-command.ts

@@ -136,6 +136,59 @@ function mapAnnotation(annotation: unknown): Record<string, unknown> {
   };
 }
 
+function asStringArray(value: unknown): Array<string> {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  const strings: Array<string> = [];
+  for (const item of value) {
+    if (typeof item === "string") {
+      strings.push(item);
+    }
+  }
+
+  return strings;
+}
+
+const REQUIRED_SCOPES: ReadonlyArray<string> = [
+  "read_builds",
+  "read_build_logs",
+  "read_artifacts",
+];
+
+function mapAuthStatus(data: unknown): {
+  readonly token: Record<string, unknown>;
+  readonly user: Record<string, unknown> | null;
+  readonly scopes: Array<string>;
+} {
+  const record = isObject(data) ? data : {};
+  const scopes = asStringArray(record.scopes);
+  const token = {
+    uuid: asString(record.uuid),
+    description: asString(record.description),
+    createdAt: asString(record.created_at),
+    scopes,
+  };
+
+  const user = isObject(record.user)
+    ? {
+        name: asString(record.user.name),
+        email: asString(record.user.email),
+      }
+    : null;
+
+  return {
+    token,
+    user,
+    scopes,
+  };
+}
+
+function getMissingRequiredScopes(scopes: ReadonlyArray<string>): Array<string> {
+  return REQUIRED_SCOPES.filter((scope) => !scopes.includes(scope));
+}
+
 function getPaginationOrNull(options: {
   readonly command: ParsedCommand;
   readonly headers: Headers;
@@ -246,6 +299,41 @@ export async function executeCommand(options: {
 }> {
   const request = getRequestForCommand(options.command);
 
+  if (options.command.name === "auth.status") {
+    const response = await options.client.requestJson({
+      path: "/v2/access-token",
+    });
+
+    if (options.command.global.raw) {
+      return {
+        request,
+        summary: {},
+        pagination: null,
+        data: response.data,
+      };
+    }
+
+    const status = mapAuthStatus(response.data);
+    const missingScopes = getMissingRequiredScopes(status.scopes);
+
+    return {
+      request,
+      summary: {
+        requiredScopes: [...REQUIRED_SCOPES],
+        grantedScopes: status.scopes.length,
+        missingScopes,
+        ready: missingScopes.length === 0,
+      },
+      pagination: null,
+      data: {
+        token: status.token,
+        user: status.user,
+        requiredScopes: [...REQUIRED_SCOPES],
+        missingScopes,
+      },
+    };
+  }
+
   if (options.command.name === "builds.list") {
     const response = await options.client.requestJson({
       path: getBuildsListPath(options.command.args),

src/cli/parse-args.test.ts

@@ -3,6 +3,14 @@ import test from "node:test";
 
 import { parseCliArgs } from "./parse-args.js";
 
+test("parseCliArgs parses auth status", () => {
+  const parsed = parseCliArgs(["auth", "status"]);
+
+  assert.equal(parsed.name, "auth.status");
+  assert.equal(parsed.global.raw, false);
+  assert.deepEqual(parsed.args, {});
+});
+
 test("parseCliArgs parses builds list with global raw option", () => {
   const parsed = parseCliArgs([
     "--raw",

src/cli/parse-args.ts

@@ -2,6 +2,7 @@ import type {
   AnnotationsListArgs,
   ArtifactsDownloadArgs,
   ArtifactsListArgs,
+  AuthStatusArgs,
   BuildsGetArgs,
   BuildsListArgs,
   JobsLogGetArgs,
@@ -59,6 +60,13 @@ function parseGlobalOptions(tokens: Array<string>): { readonly global: ParsedGlo
   };
 }
 
+function parseAuthStatus(tokens: Array<string>): AuthStatusArgs {
+  if (tokens.length > 0) {
+    throw new Error(`unknown argument for auth status: ${tokens[0] ?? ""}`);
+  }
+  return {};
+}
+
 function parseBuildsList(tokens: Array<string>): BuildsListArgs {
   let org: string | null = null;
   let pipeline: string | null = null;
@@ -405,6 +413,14 @@ export function parseCliArgs(argv: Array<string>): ParsedCommand {
 
   const [group, action, ...rest] = tokens;
 
+  if (group === "auth" && action === "status") {
+    return {
+      name: "auth.status",
+      global: globalParsed.global,
+      args: parseAuthStatus(rest),
+    };
+  }
+
   if (group === "builds" && action === "list") {
     return {
       name: "builds.list",
@@ -460,6 +476,7 @@ export function parseCliArgs(argv: Array<string>): ParsedCommand {
 }
 
 export const USAGE_TEXT = `Usage:
+  bkci auth status [--raw]
   bkci builds list --org ORG [--pipeline PIPELINE] [--branch BRANCH] [--state STATE] [--page N] [--per-page N] [--raw]
   bkci builds get --org ORG --pipeline PIPELINE --build BUILD_NUMBER [--raw]
   bkci jobs log get --org ORG --pipeline PIPELINE --build BUILD_NUMBER --job JOB_ID [--max-bytes N] [--tail-lines N] [--raw]

src/cli/types.ts

@@ -2,6 +2,8 @@ export type ParsedGlobalOptions = {
   readonly raw: boolean;
 };
 
+export type AuthStatusArgs = Record<string, never>;
+
 export type BuildsListArgs = {
   readonly org: string;
   readonly pipeline: string | null;
@@ -50,6 +52,7 @@ export type AnnotationsListArgs = {
 };
 
 export type ParsedCommand =
+  | { readonly name: "auth.status"; readonly global: ParsedGlobalOptions; readonly args: AuthStatusArgs }
   | { readonly name: "builds.list"; readonly global: ParsedGlobalOptions; readonly args: BuildsListArgs }
   | { readonly name: "builds.get"; readonly global: ParsedGlobalOptions; readonly args: BuildsGetArgs }
   | { readonly name: "jobs.log.get"; readonly global: ParsedGlobalOptions; readonly args: JobsLogGetArgs }

src/core/types.ts

@@ -1,4 +1,5 @@
 export type CommandName =
+  | "auth.status"
   | "builds.list"
   | "builds.get"
   | "jobs.log.get"

src/shell/env.ts

@@ -6,7 +6,9 @@ export function getBuildkiteTokenFromEnv(): string {
     null;
 
   if (token === null || token.trim().length === 0) {
-    throw new Error("missing buildkite token in env (BUILDKITE_TOKEN, BUILDKITE_API_TOKEN, BK_TOKEN)");
+    throw new Error(
+      "missing buildkite token in env (BUILDKITE_TOKEN, BUILDKITE_API_TOKEN, BK_TOKEN). create one at https://buildkite.com/user/api-access-tokens with scopes: read_builds, read_build_logs, read_artifacts"
+    );
   }
 
   return token.trim();