feat(wrangler): add wrangler auth token command (#11682)

* feat(wrangler): add `wrangler auth token` command

Add a new command `wrangler auth token` that retrieves the current OAuth token,
refreshing it if necessary. This is similar to `gh auth token` in the GitHub CLI
and allows users to easily retrieve their authentication token for use with other
tools and scripts.

Fixes #10095

Co-Authored-By: mkane@cloudflare.com <m@mk.gg>

* fix: output auth token without preamble and update snapshots

Co-Authored-By: mkane@cloudflare.com <m@mk.gg>

* fix: use printBanner: false for proper preamble suppression

Co-Authored-By: mkane@cloudflare.com <m@mk.gg>

* docs: add usage example to changeset per review

Co-Authored-By: mkane@cloudflare.com <m@mk.gg>

* feat(wrangler): add --json flag and refactor auth token command

- Refactor getAuthToken to getOAuthTokenFromLocalState (only handles OAuth)
- Rename LocalState to localState throughout user.ts
- Add --json flag to return structured output with token type
- Support API key/email auth with --json flag
- Add JSDoc documentation for auth priority behavior
- Update changeset to reflect all auth types
- Update tests (24 tests passing)

Co-Authored-By: mkane@cloudflare.com <m@mk.gg>

* chore: trigger CI re-run for PR description validation

Co-Authored-By: mkane@cloudflare.com <m@mk.gg>

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: ascorbic

.changeset/auth-token-command.md

@@ -0,0 +1,23 @@
+---
+"wrangler": minor
+---
+
+Add `wrangler auth token` command to retrieve your current authentication credentials.
+
+You can now retrieve your authentication token for use with other tools and scripts:
+
+```bash
+wrangler auth token
+```
+
+The command returns whichever authentication method is currently configured:
+- OAuth token from `wrangler login` (automatically refreshed if expired)
+- API token from `CLOUDFLARE_API_TOKEN` environment variable
+
+Use `--json` to get structured output including the token type, which also supports API key/email authentication:
+
+```bash
+wrangler auth token --json
+```
+
+This is similar to `gh auth token` in the GitHub CLI.

packages/wrangler/src/__tests__/index.test.ts

@@ -71,6 +71,7 @@ describe("wrangler", () => {
 				  wrangler login                  🔓 Login to Cloudflare
 				  wrangler logout                 🚪 Logout from Cloudflare
 				  wrangler whoami                 🕵️  Retrieve your user information
+				  wrangler auth                   🔐 Manage authentication
 
 				GLOBAL FLAGS
 				  -c, --config    Path to Wrangler configuration file  [string]
@@ -135,6 +136,7 @@ describe("wrangler", () => {
 				  wrangler login                  🔓 Login to Cloudflare
 				  wrangler logout                 🚪 Logout from Cloudflare
 				  wrangler whoami                 🕵️  Retrieve your user information
+				  wrangler auth                   🔐 Manage authentication
 
 				GLOBAL FLAGS
 				  -c, --config    Path to Wrangler configuration file  [string]

packages/wrangler/src/__tests__/user.test.ts

@@ -11,6 +11,7 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 import { CI } from "../is-ci";
 import {
 	getAuthConfigFilePath,
+	getOAuthTokenFromLocalState,
 	loginOrRefreshIfRequired,
 	readAuthConfigFile,
 	requireAuth,
@@ -334,4 +335,174 @@ describe("User", () => {
 			scopes: ["account:read"],
 		});
 	});
+
+	describe("auth token", () => {
+		it("should output the OAuth token when logged in with a valid token", async () => {
+			// Set up a valid, non-expired token
+			const futureDate = new Date(Date.now() + 100000 * 1000).toISOString();
+			writeAuthConfigFile({
+				oauth_token: "test-access-token",
+				refresh_token: "test-refresh-token",
+				expiration_time: futureDate,
+				scopes: ["account:read"],
+			});
+
+			await runWrangler("auth token");
+
+			expect(std.out).toContain("test-access-token");
+		});
+
+		it("should refresh and output the token when the token is expired", async () => {
+			// Set up an expired token
+			const pastDate = new Date(Date.now() - 100000 * 1000).toISOString();
+			writeAuthConfigFile({
+				oauth_token: "expired-token",
+				refresh_token: "test-refresh-token",
+				expiration_time: pastDate,
+				scopes: ["account:read"],
+			});
+
+			mockExchangeRefreshTokenForAccessToken({ respondWith: "refreshSuccess" });
+
+			await runWrangler("auth token");
+
+			// The token should have been refreshed (mock returns "access_token_success_mock")
+			expect(std.out).toContain("access_token_success_mock");
+		});
+
+		it("should error when not logged in", async () => {
+			await expect(runWrangler("auth token")).rejects.toThrowError(
+				"Not logged in. Please run `wrangler login` to authenticate."
+			);
+		});
+
+		it("should output the API token from environment variable", async () => {
+			vi.stubEnv("CLOUDFLARE_API_TOKEN", "env-api-token");
+
+			await runWrangler("auth token");
+
+			expect(std.out).toContain("env-api-token");
+		});
+
+		it("should error when using global auth key/email without --json", async () => {
+			vi.stubEnv("CLOUDFLARE_API_KEY", "test-api-key");
+			vi.stubEnv("CLOUDFLARE_EMAIL", "test@example.com");
+
+			await expect(runWrangler("auth token")).rejects.toThrowError(
+				"Cannot output a single token when using CLOUDFLARE_API_KEY and CLOUDFLARE_EMAIL"
+			);
+		});
+
+		it("should output JSON with key and email when using global auth key/email with --json", async () => {
+			vi.stubEnv("CLOUDFLARE_API_KEY", "test-api-key");
+			vi.stubEnv("CLOUDFLARE_EMAIL", "test@example.com");
+
+			await runWrangler("auth token --json");
+
+			const output = JSON.parse(std.out);
+			expect(output).toEqual({
+				type: "api_key",
+				key: "test-api-key",
+				email: "test@example.com",
+			});
+		});
+
+		it("should output JSON with oauth type when logged in with --json", async () => {
+			const futureDate = new Date(Date.now() + 100000 * 1000).toISOString();
+			writeAuthConfigFile({
+				oauth_token: "test-access-token",
+				refresh_token: "test-refresh-token",
+				expiration_time: futureDate,
+				scopes: ["account:read"],
+			});
+
+			await runWrangler("auth token --json");
+
+			const output = JSON.parse(std.out);
+			expect(output).toEqual({
+				type: "oauth",
+				token: "test-access-token",
+			});
+		});
+
+		it("should output JSON with api_token type when using CLOUDFLARE_API_TOKEN with --json", async () => {
+			vi.stubEnv("CLOUDFLARE_API_TOKEN", "env-api-token");
+
+			await runWrangler("auth token --json");
+
+			const output = JSON.parse(std.out);
+			expect(output).toEqual({
+				type: "api_token",
+				token: "env-api-token",
+			});
+		});
+
+		it("should error when token refresh fails and user is not logged in", async () => {
+			// Set up an expired token with a refresh token that will fail
+			const pastDate = new Date(Date.now() - 100000 * 1000).toISOString();
+			writeAuthConfigFile({
+				oauth_token: "expired-token",
+				refresh_token: "invalid-refresh-token",
+				expiration_time: pastDate,
+				scopes: ["account:read"],
+			});
+
+			mockExchangeRefreshTokenForAccessToken({ respondWith: "refreshError" });
+
+			await expect(runWrangler("auth token")).rejects.toThrowError(
+				"Not logged in. Please run `wrangler login` to authenticate."
+			);
+		});
+	});
+
+	describe("getOAuthTokenFromLocalState", () => {
+		it("should return undefined when not logged in", async () => {
+			const token = await getOAuthTokenFromLocalState();
+			expect(token).toBeUndefined();
+		});
+
+		it("should return the OAuth token when logged in with a valid token", async () => {
+			const futureDate = new Date(Date.now() + 100000 * 1000).toISOString();
+			writeAuthConfigFile({
+				oauth_token: "test-oauth-token",
+				refresh_token: "test-refresh-token",
+				expiration_time: futureDate,
+				scopes: ["account:read"],
+			});
+
+			const token = await getOAuthTokenFromLocalState();
+			expect(token).toBe("test-oauth-token");
+		});
+
+		it("should refresh and return the token when expired", async () => {
+			const pastDate = new Date(Date.now() - 100000 * 1000).toISOString();
+			writeAuthConfigFile({
+				oauth_token: "expired-token",
+				refresh_token: "test-refresh-token",
+				expiration_time: pastDate,
+				scopes: ["account:read"],
+			});
+
+			mockExchangeRefreshTokenForAccessToken({ respondWith: "refreshSuccess" });
+
+			const token = await getOAuthTokenFromLocalState();
+			// Mock returns "access_token_success_mock" for refreshSuccess
+			expect(token).toBe("access_token_success_mock");
+		});
+
+		it("should return undefined when token refresh fails", async () => {
+			const pastDate = new Date(Date.now() - 100000 * 1000).toISOString();
+			writeAuthConfigFile({
+				oauth_token: "expired-token",
+				refresh_token: "invalid-refresh-token",
+				expiration_time: pastDate,
+				scopes: ["account:read"],
+			});
+
+			mockExchangeRefreshTokenForAccessToken({ respondWith: "refreshError" });
+
+			const token = await getOAuthTokenFromLocalState();
+			expect(token).toBeUndefined();
+		});
+	});
 });

packages/wrangler/src/index.ts

@@ -285,7 +285,13 @@ import { setupCommand } from "./setup";
 import { tailCommand } from "./tail";
 import { triggersDeployCommand, triggersNamespace } from "./triggers";
 import { typesCommand } from "./type-generation";
-import { loginCommand, logoutCommand, whoamiCommand } from "./user/commands";
+import {
+	authNamespace,
+	authTokenCommand,
+	loginCommand,
+	logoutCommand,
+	whoamiCommand,
+} from "./user/commands";
 import { betaCmdColor, proxy } from "./utils/constants";
 import { debugLogFilepath } from "./utils/log-file";
 import { vectorizeCreateCommand } from "./vectorize/create";
@@ -1555,6 +1561,18 @@ export function createCLIParser(argv: string[]) {
 	]);
 	registry.registerNamespace("whoami");
 
+	registry.define([
+		{
+			command: "wrangler auth",
+			definition: authNamespace,
+		},
+		{
+			command: "wrangler auth token",
+			definition: authTokenCommand,
+		},
+	]);
+	registry.registerNamespace("auth");
+
 	registry.define([
 		{
 			command: "wrangler telemetry",

packages/wrangler/src/metrics/send-event.ts

@@ -38,6 +38,7 @@ export type EventNames =
 	| "delete r2 bucket"
 	| "login user"
 	| "logout user"
+	| "retrieve auth token"
 	| "create pubsub namespace"
 	| "list pubsub namespaces"
 	| "delete pubsub namespace"

packages/wrangler/src/user/commands.ts

@@ -1,9 +1,25 @@
-import { CommandLineArgsError } from "@cloudflare/workers-utils";
-import { createCommand } from "../core/create-command";
+import { CommandLineArgsError, UserError } from "@cloudflare/workers-utils";
+import { createCommand, createNamespace } from "../core/create-command";
+import { logger } from "../logger";
 import * as metrics from "../metrics";
-import { listScopes, login, logout, validateScopeKeys } from "./user";
+import {
+	getAuthFromEnv,
+	getOAuthTokenFromLocalState,
+	listScopes,
+	login,
+	logout,
+	validateScopeKeys,
+} from "./user";
 import { whoami } from "./whoami";
 
+/**
+ * Represents the authentication information returned by `wrangler auth token --json`.
+ */
+export type AuthTokenInfo =
+	| { type: "oauth"; token: string }
+	| { type: "api_token"; token: string }
+	| { type: "api_key"; key: string; email: string };
+
 export const loginCommand = createCommand({
 	metadata: {
 		description: "🔓 Login to Cloudflare",
@@ -121,3 +137,75 @@ export const whoamiCommand = createCommand({
 		});
 	},
 });
+
+export const authNamespace = createNamespace({
+	metadata: {
+		description: "🔐 Manage authentication",
+		owner: "Workers: Authoring and Testing",
+		status: "stable",
+	},
+});
+
+export const authTokenCommand = createCommand({
+	metadata: {
+		description: "🔑 Retrieve the current authentication token or credentials",
+		owner: "Workers: Authoring and Testing",
+		status: "stable",
+	},
+	behaviour: {
+		printBanner: (args) => !args.json,
+		printConfigWarnings: false,
+	},
+	args: {
+		json: {
+			type: "boolean",
+			description: "Return output as JSON with token type information",
+			default: false,
+		},
+	},
+	async handler({ json }, { config }) {
+		const authFromEnv = getAuthFromEnv();
+
+		let result: AuthTokenInfo;
+
+		if (authFromEnv) {
+			if ("apiToken" in authFromEnv) {
+				// API token from CLOUDFLARE_API_TOKEN
+				result = { type: "api_token", token: authFromEnv.apiToken };
+			} else {
+				// Global API key + email from CLOUDFLARE_API_KEY + CLOUDFLARE_EMAIL
+				result = {
+					type: "api_key",
+					key: authFromEnv.authKey,
+					email: authFromEnv.authEmail,
+				};
+			}
+		} else {
+			// OAuth token from local state (wrangler login)
+			const token = await getOAuthTokenFromLocalState();
+			if (!token) {
+				throw new UserError(
+					"Not logged in. Please run `wrangler login` to authenticate."
+				);
+			}
+			result = { type: "oauth", token };
+		}
+
+		if (json) {
+			logger.log(JSON.stringify(result, null, 2));
+		} else {
+			// For non-JSON output, only output a single token for scripting
+			if (result.type === "api_key") {
+				throw new UserError(
+					"Cannot output a single token when using CLOUDFLARE_API_KEY and CLOUDFLARE_EMAIL.\n" +
+						"Use --json to get both key and email, or use CLOUDFLARE_API_TOKEN instead."
+				);
+			}
+			logger.log(result.token);
+		}
+
+		metrics.sendMetricsEvent("retrieve auth token", {
+			sendMetrics: config.send_metrics,
+		});
+	},
+});