@agentuity/cli 2.0.6 → 2.0.7

package/src/cmd/cloud/task/util.ts

@@ -11,11 +11,14 @@ export interface TaskContext {
 	auth: AuthData;
 	config: Config | null;
 	options: GlobalOptions;
+	project?: {
+		projectId: string;
+		orgId: string;
+	};
 }
 
 export async function createStorageAdapter(ctx: TaskContext) {
-	const orgId =
-		ctx.options.orgId ?? (process.env.AGENTUITY_CLOUD_ORG_ID || ctx.config?.preferences?.orgId);
+	const orgId = resolveOrgId(ctx);
 	if (!orgId) {
 		tui.fatal('Organization ID is required. Use --org-id flag or set AGENTUITY_CLOUD_ORG_ID.');
 	}
@@ -37,8 +40,7 @@ export async function createStorageAdapter(ctx: TaskContext) {
 }
 
 export async function createStorageAdapterOptionalOrg(ctx: TaskContext) {
-	const orgId =
-		ctx.options.orgId ?? (process.env.AGENTUITY_CLOUD_ORG_ID || ctx.config?.preferences?.orgId);
+	const orgId = resolveOrgId(ctx);
 
 	const headers: Record<string, string> = {
 		Authorization: `Bearer ${ctx.auth.apiKey}`,
@@ -54,17 +56,30 @@ export async function createStorageAdapterOptionalOrg(ctx: TaskContext) {
 	return new TaskStorageService(baseUrl, adapter);
 }
 
+function resolveOrgId(ctx: TaskContext): string | undefined {
+	return (
+		ctx.options.orgId ??
+		process.env.AGENTUITY_CLOUD_ORG_ID ??
+		ctx.project?.orgId ??
+		ctx.config?.preferences?.orgId
+	);
+}
+
 export async function cacheTaskId(
 	ctx: {
 		config: Config | null;
 		options: GlobalOptions;
+		project?: { orgId: string };
 	},
 	taskId: string
 ) {
 	const profileName = ctx.config?.name ?? defaultProfileName;
 	const region = await getDefaultRegion(profileName, ctx.config);
 	const orgId =
-		ctx.options.orgId ?? (process.env.AGENTUITY_CLOUD_ORG_ID || ctx.config?.preferences?.orgId);
+		ctx.options.orgId ??
+		process.env.AGENTUITY_CLOUD_ORG_ID ??
+		ctx.project?.orgId ??
+		ctx.config?.preferences?.orgId;
 	await setResourceInfo('task', profileName, taskId, region, orgId);
 }
 
@@ -76,3 +91,42 @@ export function parseMetadataFlag(raw: string | undefined): Record<string, unkno
 		tui.fatal('Invalid JSON for --metadata flag');
 	}
 }
+
+const DURATION_UNITS: Record<string, number> = {
+	s: 1000,
+	m: 60 * 1000,
+	h: 60 * 60 * 1000,
+	d: 24 * 60 * 60 * 1000,
+	w: 7 * 24 * 60 * 60 * 1000,
+};
+
+export function parseDuration(duration: string): number {
+	const match = duration.match(/^(\d+)([smhdw])$/);
+	if (!match) {
+		tui.fatal(
+			`Invalid duration format: "${duration}". Use a number followed by s (seconds), m (minutes), h (hours), d (days), or w (weeks). Examples: 30s, 30m, 24h, 7d, 2w`
+		);
+		throw new Error('unreachable');
+	}
+	const value = parseInt(match[1]!, 10);
+	const unit = match[2]!;
+	const ms = DURATION_UNITS[unit];
+	if (!ms) {
+		tui.fatal(`Unknown duration unit: "${unit}"`);
+		throw new Error('unreachable');
+	}
+	return value * ms;
+}
+
+export function truncate(s: string, max: number): string {
+	if (s.length <= max) return s;
+	return `${s.slice(0, max - 1)}…`;
+}
+
+export function resolveMeId(id: string | undefined, ctx: TaskContext): string | undefined {
+	if (!id) return undefined;
+	if (id === 'me') {
+		return ctx.auth.userId;
+	}
+	return id;
+}

package/src/cmd/coder/config/index.ts

@@ -0,0 +1,20 @@
+import { createCommand } from '../../../types';
+import { getCommand } from '../../../command-prefix';
+import { setSubcommand } from './set';
+
+export const configSubcommand = createCommand({
+	name: 'config',
+	description: 'Manage stored Coder Hub configuration',
+	tags: ['fast'],
+	examples: [
+		{
+			command: getCommand('coder config set url https://hub.example.com'),
+			description: 'Set the default Coder Hub URL for the active profile',
+		},
+		{
+			command: getCommand('coder config set apikey agc_...'),
+			description: 'Set the default Coder Hub API key for the active profile',
+		},
+	],
+	subcommands: [setSubcommand],
+});

package/src/cmd/coder/config/set.ts

@@ -0,0 +1,112 @@
+import { z } from 'zod';
+import { saveCoderApiKey, saveCoderHubUrl } from '../../../coder-config';
+import { normalizeCoderHubHttpUrl } from '../../../coder-hub-url';
+import { getCommand } from '../../../command-prefix';
+import * as tui from '../../../tui';
+import { createCommand, createSubcommand } from '../../../types';
+
+const setUrlSubcommand = createSubcommand({
+	name: 'url',
+	description: 'Set the default Coder Hub URL for the active profile',
+	tags: ['mutating', 'fast'],
+	examples: [
+		{
+			command: getCommand('coder config set url https://hub.example.com'),
+			description: 'Set the default Coder Hub URL',
+		},
+		{
+			command: getCommand('coder config set url ws://127.0.0.1:3650/api/ws'),
+			description: 'Store a local dev Hub URL using a WebSocket input',
+		},
+	],
+	schema: {
+		args: z.object({
+			url: z.string().min(1).describe('Hub URL to store for the active profile'),
+		}),
+		response: z.object({
+			profile: z.string().describe('Active CLI profile name'),
+			hubUrl: z.string().describe('Normalized stored Hub HTTP URL'),
+		}),
+	},
+	async handler(ctx) {
+		const { args, options } = ctx;
+		const normalized = normalizeCoderHubHttpUrl(args.url);
+
+		try {
+			new URL(normalized);
+		} catch {
+			tui.fatal(
+				`Invalid Hub URL: ${args.url}\n\nExpected a full URL such as https://hub.example.com or ws://127.0.0.1:3650/api/ws`
+			);
+		}
+
+		const result = await saveCoderHubUrl(normalized);
+
+		if (!options.json) {
+			tui.success(
+				`Default Coder Hub URL set to ${tui.bold(result.hubUrl)} for profile ${tui.bold(result.profileName)}`
+			);
+		}
+
+		return {
+			profile: result.profileName,
+			hubUrl: result.hubUrl,
+		};
+	},
+});
+
+const setApiKeySubcommand = createSubcommand({
+	name: 'apikey',
+	description: 'Set the default Coder Hub API key for the active profile',
+	tags: ['mutating', 'fast'],
+	examples: [
+		{
+			command: getCommand('coder config set apikey agc_...'),
+			description: 'Set the default Coder Hub API key',
+		},
+	],
+	schema: {
+		args: z.object({
+			apikey: z.string().min(1).describe('Hub API key to store for the active profile'),
+		}),
+		response: z.object({
+			profile: z.string().describe('Active CLI profile name'),
+			stored: z.boolean().describe('Whether the API key was stored successfully'),
+		}),
+	},
+	async handler(ctx) {
+		const { args, options } = ctx;
+		const trimmed = args.apikey.trim();
+		if (!trimmed) {
+			tui.fatal('Hub API key cannot be empty');
+		}
+
+		const result = await saveCoderApiKey(trimmed);
+
+		if (!options.json) {
+			tui.success(`Coder Hub API key stored for profile ${tui.bold(result.profileName)}`);
+		}
+
+		return {
+			profile: result.profileName,
+			stored: true,
+		};
+	},
+});
+
+export const setSubcommand = createCommand({
+	name: 'set',
+	description: 'Set stored Coder Hub configuration values',
+	tags: ['mutating', 'fast'],
+	examples: [
+		{
+			command: getCommand('coder config set url https://hub.example.com'),
+			description: 'Store the default Hub URL',
+		},
+		{
+			command: getCommand('coder config set apikey agc_...'),
+			description: 'Store the default Hub API key',
+		},
+	],
+	subcommands: [setUrlSubcommand, setApiKeySubcommand],
+});

package/src/cmd/coder/hub-url.ts

@@ -4,11 +4,27 @@
  * Resolution priority:
  *   1. --hub-url flag (explicit per-command override)
  *   2. AGENTUITY_CODER_HUB_URL env var
- *   3. AGENTUITY_DEVMODE_URL env var (dev tunnel URL)
+ *   3. Stored per-profile Hub URL
+ *   4. AGENTUITY_DEVMODE_URL env var (dev tunnel URL)
  */
 
+import {
+	clearStoredCoderApiKey,
+	getStoredCoderApiKey,
+	getStoredCoderHubUrl,
+} from '../../coder-config';
+import { normalizeCoderHubHttpUrl, toCoderHubWsUrl } from '../../coder-hub-url';
+import { getCommand } from '../../command-prefix';
+import type { Config } from '../../types';
 import { getVersion } from '../../version';
 
+export type HubApiKeySource = 'env' | 'stored' | 'none';
+
+export interface ResolvedHubApiKey {
+	apiKey: string | null;
+	source: HubApiKeySource;
+}
+
 /**
  * Resolve the Hub HTTP base URL for REST API calls.
  * Converts ws:// URLs to http:// automatically.
@@ -16,17 +32,24 @@ import { getVersion } from '../../version';
  * @param flagUrl  Optional --hub-url flag value
  * @returns HTTP base URL (e.g. "http://localhost:3500") or null if Hub is unreachable
  */
-export async function resolveHubUrl(flagUrl?: string): Promise<string | null> {
+export async function resolveHubUrl(
+	flagUrl?: string,
+	config?: Config | null
+): Promise<string | null> {
 	// 1. Explicit flag
-	if (flagUrl) return normalizeToHttp(flagUrl);
+	if (flagUrl) return normalizeCoderHubHttpUrl(flagUrl);
 
 	// 2. Env var (explicit)
 	const envUrl = process.env.AGENTUITY_CODER_HUB_URL;
-	if (envUrl) return normalizeToHttp(envUrl);
+	if (envUrl) return normalizeCoderHubHttpUrl(envUrl);
+
+	// 3. Stored profile config
+	const storedUrl = await getStoredCoderHubUrl(config);
+	if (storedUrl) return storedUrl;
 
-	// 3. Dev mode URL (tunnel)
+	// 4. Dev mode URL (tunnel)
 	const devUrl = process.env.AGENTUITY_DEVMODE_URL;
-	if (devUrl) return normalizeToHttp(devUrl);
+	if (devUrl) return normalizeCoderHubHttpUrl(devUrl);
 
 	return null;
 }
@@ -38,74 +61,145 @@ export async function resolveHubUrl(flagUrl?: string): Promise<string | null> {
  * @param flagUrl  Optional --hub-url flag value
  * @returns WebSocket URL (e.g. "ws://127.0.0.1:3500/api/ws") or null
  */
-export async function resolveHubWsUrl(flagUrl?: string): Promise<string | null> {
-	const httpUrl = await resolveHubUrl(flagUrl);
+export async function resolveHubWsUrl(
+	flagUrl?: string,
+	config?: Config | null
+): Promise<string | null> {
+	const httpUrl = await resolveHubUrl(flagUrl, config);
 	if (!httpUrl) return null;
 	return toHubWsUrl(httpUrl);
 }
 
 export function toHubWsUrl(hubHttpUrl: string): string {
-	return normalizeToWs(hubHttpUrl);
+	return toCoderHubWsUrl(hubHttpUrl);
 }
 
 /**
- * Convert any URL form to an HTTP base URL (strip paths, convert ws->http).
+ * Resolve the API key for Hub authentication.
  */
-function normalizeToHttp(url: string): string {
-	let normalized = url.trim().replace(/\/+$/, '');
+function resolveEnvApiKey(): string | null {
+	return process.env.AGENTUITY_CODER_API_KEY || null;
+}
 
-	// ws:// -> http://
-	if (normalized.startsWith('ws://')) normalized = 'http://' + normalized.slice(5);
-	else if (normalized.startsWith('wss://')) normalized = 'https://' + normalized.slice(6);
+export async function resolveHubApiKey(config?: Config | null): Promise<ResolvedHubApiKey> {
+	const envApiKey = resolveEnvApiKey();
+	if (envApiKey) {
+		return {
+			apiKey: envApiKey,
+			source: 'env',
+		};
+	}
 
-	// Strip known Hub transport/helper paths to get the HTTP base URL.
-	// Accept `/ws` as a convenience alias because users often copy the raw route name.
-	normalized = normalized.replace(/\/api\/ws\b.*$/, '');
-	normalized = normalized.replace(/\/ws\b.*$/, '');
-	normalized = normalized.replace(/\/api\/hub\b.*$/, '');
+	const storedApiKey = await getStoredCoderApiKey(config);
+	if (storedApiKey) {
+		return {
+			apiKey: storedApiKey,
+			source: 'stored',
+		};
+	}
 
-	return normalized.replace(/\/+$/, '');
+	return {
+		apiKey: null,
+		source: 'none',
+	};
 }
 
 /**
- * Convert an HTTP base URL to a WebSocket URL with /api/ws path.
+ * Build headers object with API key if available.
  */
-function normalizeToWs(httpUrl: string): string {
-	let wsUrl = httpUrl;
-	if (wsUrl.startsWith('http://')) wsUrl = 'ws://' + wsUrl.slice(7);
-	else if (wsUrl.startsWith('https://')) wsUrl = 'wss://' + wsUrl.slice(8);
+export function hubFetchHeaders(
+	extra?: Record<string, string>,
+	apiKey?: string | null
+): Record<string, string> {
+	const headers: Record<string, string> = { ...extra };
+	headers['User-Agent'] = `Agentuity Coder/${getVersion()}`;
+	const resolvedApiKey = apiKey === undefined ? resolveEnvApiKey() : apiKey;
+	if (resolvedApiKey) headers['x-agentuity-auth-api-key'] = resolvedApiKey;
+	return headers;
+}
 
-	try {
-		const parsed = new URL(wsUrl);
-		if (parsed.pathname !== '/api/ws') {
-			parsed.pathname = '/api/ws';
-			wsUrl = parsed.toString().replace(/\/$/, '');
-		}
-	} catch {
-		if (!wsUrl.endsWith('/api/ws')) {
-			wsUrl = wsUrl.replace(/\/?$/, '/api/ws');
-		}
+export function isHubUnauthorizedStatus(status: number): boolean {
+	return status === 401 || status === 403;
+}
+
+export async function clearStoredHubApiKeyOnUnauthorized(
+	status: number,
+	resolvedApiKey: ResolvedHubApiKey,
+	config?: Config | null,
+	clearStoredApiKey: (config?: Config | null) => Promise<unknown> = clearStoredCoderApiKey
+): Promise<boolean> {
+	if (!isHubUnauthorizedStatus(status) || resolvedApiKey.source !== 'stored') {
+		return false;
 	}
 
-	return wsUrl;
+	await clearStoredApiKey(config);
+	return true;
 }
 
-/**
- * Resolve the API key for Hub authentication.
- * TODO: Remove/Change when we get Agentuity service level auth enabled, this is just temporary
- */
-export function resolveApiKey(): string | null {
-	return process.env.AGENTUITY_CODER_API_KEY || null;
+export function getHubUrlSetupGuidance(): string {
+	return (
+		`Set a default Hub URL with:\n` +
+		`  ${getCommand('coder config set url <url>')}\n\n` +
+		`Or pass --hub-url for a one-off override, or use AGENTUITY_CODER_HUB_URL.`
+	);
 }
 
-/**
- * Build headers object with API key if available.
- * TODO: Remove/Change when we get Agentuity service level auth enabled, this is just temporary
- */
-export function hubFetchHeaders(extra?: Record<string, string>): Record<string, string> {
-	const headers: Record<string, string> = { ...extra };
-	headers['User-Agent'] = `Agentuity Coder/${getVersion()}`;
-	const apiKey = resolveApiKey();
-	if (apiKey) headers['x-agentuity-auth-api-key'] = apiKey;
-	return headers;
+export function getHubApiKeySetupGuidance(): string {
+	return (
+		`Set a Hub API key with:\n` +
+		`  ${getCommand('coder config set apikey <apikey>')}\n\n` +
+		`Or use AGENTUITY_CODER_API_KEY as an override.`
+	);
+}
+
+export function formatMissingHubUrlMessage(): string {
+	return `Could not find a configured Coder Hub URL.\n\n${getHubUrlSetupGuidance()}`;
+}
+
+export function formatHubUnauthorizedMessage(
+	hubUrl: string,
+	serverMessage: string,
+	options?: {
+		clearedStoredKey?: boolean;
+	}
+): string {
+	const clearedStoredKey = options?.clearedStoredKey ? 'Stored Hub API key cleared.\n\n' : '';
+
+	return (
+		`Coder Hub at ${hubUrl} requires a valid API key.\n\n` +
+		`${clearedStoredKey}${getHubApiKeySetupGuidance()}\n\n` +
+		`Server said: ${serverMessage}`
+	);
+}
+
+export async function getHubResponseErrorMessage(response: Response): Promise<string> {
+	const fallback = `${response.status} ${response.statusText}`;
+
+	try {
+		const payload = (await response.clone().json()) as {
+			error?: unknown;
+			message?: unknown;
+			details?: unknown;
+		};
+		if (typeof payload.error === 'string' && payload.error.trim()) {
+			return payload.error.trim();
+		}
+		if (typeof payload.message === 'string' && payload.message.trim()) {
+			return payload.message.trim();
+		}
+		if (typeof payload.details === 'string' && payload.details.trim()) {
+			return payload.details.trim();
+		}
+	} catch {
+		// Fall back to the response text below.
+	}
+
+	try {
+		const text = (await response.text()).trim();
+		if (text) return text;
+	} catch {
+		// Fall back to the status text below.
+	}
+
+	return fallback;
 }

package/src/cmd/coder/index.ts

@@ -1,4 +1,5 @@
 import { createCommand } from '../../types';
+import { configSubcommand } from './config';
 import { listSubcommand } from './list';
 import { inspectSubcommand } from './inspect';
 import { startSubcommand } from './start';
@@ -21,7 +22,11 @@ export const command = createCommand({
 			command: getCommand('coder inspect <session-id>'),
 			description: 'Show detailed session information',
 		},
+		{
+			command: getCommand('coder config set url https://hub.example.com'),
+			description: 'Set the default Coder Hub URL for this profile',
+		},
 	],
-	subcommands: [startSubcommand, listSubcommand, inspectSubcommand],
+	subcommands: [startSubcommand, listSubcommand, inspectSubcommand, configSubcommand],
 	optional: { auth: true },
 });

package/src/cmd/coder/inspect.ts

@@ -3,7 +3,17 @@ import { createSubcommand } from '../../types';
 import * as tui from '../../tui';
 import { getCommand } from '../../command-prefix';
 import { ErrorCode } from '../../errors';
-import { resolveHubUrl, hubFetchHeaders } from './hub-url';
+import {
+	clearStoredHubApiKeyOnUnauthorized,
+	formatHubUnauthorizedMessage,
+	formatMissingHubUrlMessage,
+	getHubResponseErrorMessage,
+	getHubUrlSetupGuidance,
+	hubFetchHeaders,
+	isHubUnauthorizedStatus,
+	resolveHubApiKey,
+	resolveHubUrl,
+} from './hub-url';
 
 function formatRelativeTime(isoDate: string): string {
 	const diffMs = Date.now() - new Date(isoDate).getTime();
@@ -52,18 +62,17 @@ export const inspectSubcommand = createSubcommand({
 		}),
 	},
 	async handler(ctx) {
-		const { args, options, opts } = ctx;
+		const { args, options, opts, config } = ctx;
 		const sessionId = args.session_id;
-		const hubUrl = await resolveHubUrl(opts?.hubUrl);
+		const hubUrl = await resolveHubUrl(opts?.hubUrl, config);
 
 		if (!hubUrl) {
-			tui.fatal(
-				'Could not find a running Coder Hub.\n\nEither:\n  - Start the Hub with: bun run dev\n  - Set AGENTUITY_CODER_HUB_URL environment variable\n  - Pass --hub-url flag',
-				ErrorCode.NETWORK_ERROR
-			);
+			tui.fatal(formatMissingHubUrlMessage(), ErrorCode.NETWORK_ERROR);
 			return;
 		}
 
+		const resolvedHubApiKey = await resolveHubApiKey(config);
+
 		let data: {
 			sessionId: string;
 			label: string;
@@ -104,9 +113,22 @@ export const inspectSubcommand = createSubcommand({
 
 		try {
 			const resp = await fetch(`${hubUrl}/api/hub/session/${encodeURIComponent(sessionId)}`, {
-				headers: hubFetchHeaders(),
+				headers: hubFetchHeaders(undefined, resolvedHubApiKey.apiKey),
 				signal: AbortSignal.timeout(10_000),
 			});
+			if (isHubUnauthorizedStatus(resp.status)) {
+				const message = await getHubResponseErrorMessage(resp);
+				const clearedStoredKey = await clearStoredHubApiKeyOnUnauthorized(
+					resp.status,
+					resolvedHubApiKey,
+					config
+				);
+				tui.fatal(
+					formatHubUnauthorizedMessage(hubUrl, message, { clearedStoredKey }),
+					ErrorCode.API_ERROR
+				);
+				return;
+			}
 			if (resp.status === 404) {
 				tui.fatal(`Session not found: ${sessionId}`, ErrorCode.RESOURCE_NOT_FOUND);
 				return;
@@ -116,8 +138,9 @@ export const inspectSubcommand = createSubcommand({
 				return;
 			}
 			if (!resp.ok) {
+				const message = await getHubResponseErrorMessage(resp);
 				tui.fatal(
-					`Hub returned ${resp.status}: ${resp.statusText}. Is the Coder Hub running at ${hubUrl}?`,
+					`Hub returned ${resp.status}: ${message}. Is the Coder Hub running at ${hubUrl}?`,
 					ErrorCode.API_ERROR
 				);
 				return;
@@ -126,7 +149,7 @@ export const inspectSubcommand = createSubcommand({
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : String(err);
 			tui.fatal(
-				`Could not connect to Coder Hub at ${hubUrl}: ${msg}\n\nSet AGENTUITY_CODER_HUB_URL or start the Hub with: bun run dev`,
+				`Could not connect to Coder Hub at ${hubUrl}: ${msg}\n\n${getHubUrlSetupGuidance()}`,
 				ErrorCode.NETWORK_ERROR
 			);
 			return;

package/src/cmd/coder/list.ts

@@ -3,7 +3,17 @@ import { createSubcommand } from '../../types';
 import * as tui from '../../tui';
 import { getCommand } from '../../command-prefix';
 import { ErrorCode } from '../../errors';
-import { resolveHubUrl, hubFetchHeaders } from './hub-url';
+import {
+	clearStoredHubApiKeyOnUnauthorized,
+	formatHubUnauthorizedMessage,
+	formatMissingHubUrlMessage,
+	getHubResponseErrorMessage,
+	getHubUrlSetupGuidance,
+	hubFetchHeaders,
+	isHubUnauthorizedStatus,
+	resolveHubApiKey,
+	resolveHubUrl,
+} from './hub-url';
 
 function formatRelativeTime(isoDate: string): string {
 	const diffMs = Date.now() - new Date(isoDate).getTime();
@@ -54,17 +64,16 @@ export const listSubcommand = createSubcommand({
 		response: SessionListResponseSchema,
 	},
 	async handler(ctx) {
-		const { options, opts } = ctx;
-		const hubUrl = await resolveHubUrl(opts?.hubUrl);
+		const { options, opts, config } = ctx;
+		const hubUrl = await resolveHubUrl(opts?.hubUrl, config);
 
 		if (!hubUrl) {
-			tui.fatal(
-				'Could not find a running Coder Hub.\n\nEither:\n  - Start the Hub with: bun run dev\n  - Set AGENTUITY_CODER_HUB_URL environment variable\n  - Pass --hub-url flag',
-				ErrorCode.NETWORK_ERROR
-			);
+			tui.fatal(formatMissingHubUrlMessage(), ErrorCode.NETWORK_ERROR);
 			return [];
 		}
 
+		const resolvedHubApiKey = await resolveHubApiKey(config);
+
 		let data: {
 			sessions: {
 				websocket: Array<{
@@ -85,12 +94,26 @@ export const listSubcommand = createSubcommand({
 
 		try {
 			const resp = await fetch(`${hubUrl}/api/hub/sessions`, {
-				headers: hubFetchHeaders(),
+				headers: hubFetchHeaders(undefined, resolvedHubApiKey.apiKey),
 				signal: AbortSignal.timeout(10_000),
 			});
 			if (!resp.ok) {
+				const message = await getHubResponseErrorMessage(resp);
+				if (isHubUnauthorizedStatus(resp.status)) {
+					const clearedStoredKey = await clearStoredHubApiKeyOnUnauthorized(
+						resp.status,
+						resolvedHubApiKey,
+						config
+					);
+					tui.fatal(
+						formatHubUnauthorizedMessage(hubUrl, message, { clearedStoredKey }),
+						ErrorCode.API_ERROR
+					);
+					return [];
+				}
+
 				tui.fatal(
-					`Hub returned ${resp.status}: ${resp.statusText}. Is the Coder Hub running at ${hubUrl}?`,
+					`Hub returned ${resp.status}: ${message}. Is the Coder Hub running at ${hubUrl}?`,
 					ErrorCode.API_ERROR
 				);
 				return [];
@@ -99,7 +122,7 @@ export const listSubcommand = createSubcommand({
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : String(err);
 			tui.fatal(
-				`Could not connect to Coder Hub at ${hubUrl}: ${msg}\n\nSet AGENTUITY_CODER_HUB_URL or start the Hub with: bun run dev`,
+				`Could not connect to Coder Hub at ${hubUrl}: ${msg}\n\n${getHubUrlSetupGuidance()}`,
 				ErrorCode.NETWORK_ERROR
 			);
 			return [];