@agentuity/cli 2.0.7 → 2.0.9

package/src/cmd/coder/start.ts

@@ -1,95 +1,75 @@
+import { dirname, resolve } from 'node:path';
 import { z } from 'zod';
-import { existsSync } from 'node:fs';
-import { resolve, dirname, join } from 'node:path';
+import { CoderClient, type CoderSessionListItem } from '@agentuity/core/coder';
+import { ValidationOutputError } from '@agentuity/core';
+import { toCoderHubWsUrl } from '../../coder-hub-url';
 import { createSubcommand } from '../../types';
 import * as tui from '../../tui';
 import { getCommand } from '../../command-prefix';
 import { ErrorCode } from '../../errors';
-import {
-	clearStoredHubApiKeyOnUnauthorized,
-	formatHubUnauthorizedMessage,
-	formatMissingHubUrlMessage,
-	getHubResponseErrorMessage,
-	hubFetchHeaders,
-	isHubUnauthorizedStatus,
-	resolveHubApiKey,
-	resolveHubUrl,
-	toHubWsUrl,
-} from './hub-url';
+import { resolveExtensionPath, resolveExtensionRuntimeModulePath } from './extension-path';
 import { probeHubInitAccess } from './tui-init';
 
-/**
- * Resolve the Coder extension path.
- *
- * Priority:
- *   1. --extension flag (explicit override)
- *   2. AGENTUITY_CODER_EXTENSION env var
- *   3. Installed @agentuity/coder package (node_modules)
- *   4. Local dev path relative to CLI package (SDK monorepo)
- */
-function resolveExtensionPath(flagPath?: string): string | null {
-	// 1. Explicit flag
-	if (flagPath) {
-		const resolved = resolve(flagPath);
-		if (existsSync(resolved)) return resolved;
-		return null;
-	}
-
-	// 2. Env var
-	const envPath = process.env.AGENTUITY_CODER_EXTENSION;
-	if (envPath) {
-		const resolved = resolve(envPath);
-		if (existsSync(resolved)) return resolved;
-	}
-
-	// 3. Installed npm package in cwd
-	const cwdNodeModules = resolve(process.cwd(), 'node_modules', '@agentuity', 'coder');
-	if (existsSync(cwdNodeModules)) return cwdNodeModules;
-
-	// 4. SDK monorepo sibling (for development)
-	// This file is at packages/cli/src/cmd/coder/start.ts — 5 levels up to SDK root
-	try {
-		const cliDir = dirname(new URL(import.meta.url).pathname);
-		const sdkRoot = resolve(cliDir, '..', '..', '..', '..', '..');
-		const coderPath = join(sdkRoot, 'packages', 'coder');
-		if (existsSync(join(coderPath, 'src', 'index.ts'))) return coderPath;
-	} catch {
-		// Not in SDK monorepo
-	}
-
-	return null;
-}
-
 /**
  * Find the `pi` binary.
  *
  * Priority:
  *   1. --pi flag (explicit override)
  *   2. AGENTUITY_CODER_PI_PATH env var
- *   3. `pi` on PATH (default)
+ *   3. Bundled pi from coder-tui's node_modules/.bin/pi
+ *   4. `pi` on PATH (fallback)
  */
-function resolvePiBinary(flagPath?: string): string {
+async function resolvePiBinary(flagPath?: string, extensionDir?: string): Promise<string> {
 	if (flagPath) return flagPath;
 	const envPath = process.env.AGENTUITY_CODER_PI_PATH;
 	if (envPath) return envPath;
+
+	// Look for pi bundled with the coder-tui extension
+	if (extensionDir) {
+		// Prefer require.resolve via package.json — handles hoisted deps, Bun's .bun cache, etc.
+		try {
+			const pkgJson = require.resolve('@mariozechner/pi-coding-agent/package.json', {
+				paths: [extensionDir],
+			});
+			const piCli = resolve(dirname(pkgJson), 'dist', 'cli.js');
+			if (await Bun.file(piCli).exists()) return piCli;
+		} catch {
+			// Fallback: direct .bin symlink check
+			const bundledPi = resolve(extensionDir, 'node_modules', '.bin', 'pi');
+			if (await Bun.file(bundledPi).exists()) return bundledPi;
+		}
+	}
+
 	return 'pi';
 }
 
+function logValidationIssues(
+	ctx: { logger: { trace: (...args: unknown[]) => void } },
+	err: unknown
+): void {
+	if (err instanceof ValidationOutputError) {
+		ctx.logger.trace('Validation response URL: %s', err.url ?? 'unknown');
+		ctx.logger.trace('Validation issues: %s', JSON.stringify(err.issues, null, 2));
+	}
+}
+
 export const startSubcommand = createSubcommand({
 	name: 'start',
+	aliases: ['run'],
 	description: 'Start a Pi coding session connected to the Coder Hub',
 	tags: ['fast', 'requires-auth'],
+	requires: { auth: true, org: true },
 	examples: [
 		{
 			command: getCommand('coder start'),
 			description: 'Start Pi with auto-detected Hub and extension',
 		},
 		{
-			command: getCommand('coder start --hub-url ws://127.0.0.1:3500/api/ws'),
+			command: getCommand('coder start --url ws://127.0.0.1:3500/api/ws'),
 			description: 'Start with explicit Hub URL',
 		},
 		{
-			command: getCommand('coder start --extension ~/repos/agentuity/sdk/packages/coder'),
+			command: getCommand('coder start --extension ~/repos/agentuity/sdk/packages/coder-tui'),
 			description: 'Start with explicit extension path',
 		},
 		{
@@ -97,7 +77,7 @@ export const startSubcommand = createSubcommand({
 			description: 'Start as a specific agent role',
 		},
 		{
-			command: getCommand('coder start --remote codesess_abc123'),
+			command: getCommand('coder start --remote codesess_abc123456789'),
 			description: 'Connect to an existing sandbox session remotely',
 		},
 		{
@@ -117,7 +97,7 @@ export const startSubcommand = createSubcommand({
 	],
 	schema: {
 		options: z.object({
-			hubUrl: z.string().optional().describe('Hub WebSocket URL override'),
+			url: z.string().optional().describe('Coder API URL override'),
 			extension: z.string().optional().describe('Coder extension path override'),
 			pi: z.string().optional().describe('Path to pi binary'),
 			agent: z.string().optional().describe('Agent role (e.g. scout, builder)'),
@@ -135,51 +115,25 @@ export const startSubcommand = createSubcommand({
 				.optional()
 				.describe('Git repo URL to clone in the sandbox (used with --sandbox)'),
 		}),
+		aliases: {
+			remote: ['session'],
+		},
 	},
 	async handler(ctx) {
-		const { opts, options, config } = ctx;
+		const { opts, options } = ctx;
+		const client = new CoderClient({
+			apiKey: ctx.auth.apiKey,
+			url: opts?.url,
+			orgId: ctx.orgId,
+		});
 
-		// Resolve Hub URL
-		const hubHttpUrl = await resolveHubUrl(opts?.hubUrl, config);
-		if (!hubHttpUrl) {
-			tui.fatal(formatMissingHubUrlMessage(), ErrorCode.NETWORK_ERROR);
-			return;
-		}
-		const hubWsUrl = toHubWsUrl(hubHttpUrl);
-		const resolvedHubApiKey = await resolveHubApiKey(config);
-
-		const handleUnauthorizedResponse = async (
-			response: Response,
-			errorCode: ErrorCode = ErrorCode.NETWORK_ERROR
-		): Promise<void> => {
-			const message = await getHubResponseErrorMessage(response);
-			const clearedStoredKey = await clearStoredHubApiKeyOnUnauthorized(
-				response.status,
-				resolvedHubApiKey,
-				config
-			);
-			tui.fatal(
-				formatHubUnauthorizedMessage(hubHttpUrl, message, { clearedStoredKey }),
-				errorCode
-			);
-		};
+		const hubHttpUrl = await client.getUrl();
+		const hubWsUrl = toCoderHubWsUrl(hubHttpUrl);
 
 		const initProbe = await probeHubInitAccess(hubHttpUrl, {
-			apiKey: resolvedHubApiKey.apiKey,
+			apiKey: ctx.auth.apiKey,
 		});
 		if (!initProbe.ok) {
-			if (initProbe.code === 'unauthorized') {
-				const clearedStoredKey =
-					resolvedHubApiKey.source === 'stored'
-						? await clearStoredHubApiKeyOnUnauthorized(401, resolvedHubApiKey, config)
-						: false;
-				tui.fatal(
-					formatHubUnauthorizedMessage(hubHttpUrl, initProbe.message, { clearedStoredKey }),
-					ErrorCode.NETWORK_ERROR
-				);
-				return;
-			}
-
 			tui.fatal(
 				`Could not bootstrap the Coder Hub at ${hubHttpUrl}: ${initProbe.message}`,
 				ErrorCode.NETWORK_ERROR
@@ -188,17 +142,27 @@ export const startSubcommand = createSubcommand({
 		}
 
 		// Resolve extension path
-		const extensionPath = resolveExtensionPath(opts?.extension);
+		const extensionPath = await resolveExtensionPath(opts?.extension);
 		if (!extensionPath) {
 			tui.fatal(
-				'Could not find the Agentuity Coder extension.\n\nEither:\n  - Install it: npm install @agentuity/coder\n  - Set AGENTUITY_CODER_EXTENSION environment variable\n  - Pass --extension flag',
+				'Could not find the Agentuity Coder extension.\n\nThis CLI install should include it automatically. Try:\n  - Reinstall or update @agentuity/cli\n  - Install it locally: npm install @agentuity/coder-tui\n  - Set AGENTUITY_CODER_EXTENSION environment variable\n  - Pass --extension flag',
 				ErrorCode.CONFIG_INVALID
 			);
 			return;
 		}
 
+		const loadRemoteTui = async () => {
+			const modulePath = await resolveExtensionRuntimeModulePath(extensionPath);
+			if (!modulePath) {
+				throw new Error(
+					`Coder extension at ${extensionPath} is missing the remote TUI entrypoint`
+				);
+			}
+			return import(modulePath);
+		};
+
 		// Resolve pi binary
-		const piBinary = resolvePiBinary(opts?.pi);
+		const piBinary = await resolvePiBinary(opts?.pi, extensionPath);
 
 		// ── Remote mode: resolve session ID ──
 		let remoteSessionId: string | undefined;
@@ -210,31 +174,9 @@ export const startSubcommand = createSubcommand({
 			} else {
 				// No session ID — fetch connectable sessions and show picker
 				try {
-					type SessionInfo = {
-						id: string;
-						label: string;
-						status: string;
-						task: string | null;
-						createdAt: string;
-					};
-
 					const sessions = await tui.spinner({
 						message: 'Fetching connectable sessions…',
-						callback: async () => {
-							const resp = await fetch(`${hubHttpUrl}/api/hub/sessions/connectable`, {
-								headers: hubFetchHeaders(undefined, resolvedHubApiKey.apiKey),
-								signal: AbortSignal.timeout(10_000),
-							});
-							if (isHubUnauthorizedStatus(resp.status)) {
-								await handleUnauthorizedResponse(resp);
-								throw new Error('Hub authentication failed');
-							}
-							if (!resp.ok) {
-								throw new Error(`${resp.status} ${await getHubResponseErrorMessage(resp)}`);
-							}
-							const data = (await resp.json()) as { sessions: SessionInfo[] };
-							return data.sessions;
-						},
+						callback: async () => (await client.listConnectableSessions()).sessions,
 					});
 
 					if (sessions.length === 0) {
@@ -248,22 +190,20 @@ export const startSubcommand = createSubcommand({
 					const prompt = tui.createPrompt();
 					remoteSessionId = await prompt.select<string>({
 						message: 'Select a sandbox session to connect to',
-						options: sessions.map((s) => {
+						options: sessions.map((s: CoderSessionListItem) => {
 							const age = timeSince(new Date(s.createdAt));
-							const taskPreview = s.task ? s.task.slice(0, 55) : null;
-							const label = taskPreview
-								? `${s.label} ${tui.muted(`(${s.status}, ${age})`)} — ${taskPreview}`
-								: `${s.label} ${tui.muted(`(${s.status}, ${age})`)}`;
+							const label = `${s.label} ${tui.muted(`(${s.status}, ${age})`)}`;
 							return {
-								value: s.id,
+								value: s.sessionId,
 								label,
-								hint: s.id,
+								hint: s.sessionId,
 							};
 						}),
 					});
 				} catch (err) {
+					logValidationIssues(ctx, err);
 					const msg = err instanceof Error ? err.message : String(err);
-					if (msg === 'User cancelled' || msg === 'Hub authentication failed') return;
+					if (msg === 'User cancelled') return;
 					tui.fatal(`Failed to fetch connectable sessions: ${msg}`, ErrorCode.NETWORK_ERROR);
 					return;
 				}
@@ -284,10 +224,12 @@ export const startSubcommand = createSubcommand({
 			}
 
 			try {
-				const { runRemoteTui } = await import(join(extensionPath, 'src', 'remote-tui.ts'));
+				const { runRemoteTui } = await loadRemoteTui();
 				await runRemoteTui({
 					hubWsUrl,
 					sessionId: remoteSessionId,
+					apiKey: ctx.auth.apiKey,
+					orgId: ctx.orgId,
 				});
 			} catch (err) {
 				const msg = err instanceof Error ? err.message : String(err);
@@ -308,7 +250,10 @@ export const startSubcommand = createSubcommand({
 			}
 
 			// Build request body
-			const body: Record<string, unknown> = { task };
+			const body: {
+				task: string;
+				repo?: { url: string };
+			} = { task };
 			if (opts?.repo) {
 				body.repo = { url: opts.repo };
 			}
@@ -319,29 +264,10 @@ export const startSubcommand = createSubcommand({
 
 			let sessionId: string;
 			try {
-				const resp = await fetch(`${hubHttpUrl}/api/hub/session`, {
-					method: 'POST',
-					headers: hubFetchHeaders(
-						{ 'Content-Type': 'application/json' },
-						resolvedHubApiKey.apiKey
-					),
-					body: JSON.stringify(body),
-					signal: AbortSignal.timeout(10_000),
-				});
-				if (isHubUnauthorizedStatus(resp.status)) {
-					await handleUnauthorizedResponse(resp);
-					return;
-				}
-				if (!resp.ok) {
-					tui.fatal(
-						`Failed to create sandbox session: ${resp.status} ${await getHubResponseErrorMessage(resp)}`,
-						ErrorCode.NETWORK_ERROR
-					);
-					return;
-				}
-				const sessionInfo = (await resp.json()) as { sessionId: string };
+				const sessionInfo = await client.createSession(body);
 				sessionId = sessionInfo.sessionId;
 			} catch (err) {
+				logValidationIssues(ctx, err);
 				const msg = err instanceof Error ? err.message : String(err);
 				tui.fatal(`Failed to create sandbox session: ${msg}`, ErrorCode.NETWORK_ERROR);
 				return;
@@ -361,22 +287,10 @@ export const startSubcommand = createSubcommand({
 			while (Date.now() - pollStart < POLL_TIMEOUT) {
 				await new Promise((r) => setTimeout(r, POLL_INTERVAL));
 				try {
-					const pollResp = await fetch(`${hubHttpUrl}/api/hub/session/${sessionId}`, {
-						headers: hubFetchHeaders(undefined, resolvedHubApiKey.apiKey),
-						signal: AbortSignal.timeout(5_000),
-					});
-					if (isHubUnauthorizedStatus(pollResp.status)) {
-						await handleUnauthorizedResponse(pollResp);
-						return;
-					}
-					if (pollResp.ok) {
-						const data = (await pollResp.json()) as {
-							participants?: Array<{ role: string }>;
-						};
-						if (data.participants?.some((p) => p.role === 'lead')) {
-							driverConnected = true;
-							break;
-						}
+					const data = await client.listParticipants(sessionId);
+					if (data.participants?.some((p) => p.role === 'lead')) {
+						driverConnected = true;
+						break;
 					}
 				} catch {
 					// Network blip — keep polling
@@ -395,10 +309,12 @@ export const startSubcommand = createSubcommand({
 			tui.newline();
 
 			try {
-				const { runRemoteTui } = await import(join(extensionPath, 'src', 'remote-tui.ts'));
+				const { runRemoteTui } = await loadRemoteTui();
 				await runRemoteTui({
 					hubWsUrl,
 					sessionId,
+					apiKey: ctx.auth.apiKey,
+					orgId: ctx.orgId,
 				});
 			} catch (err) {
 				const msg = err instanceof Error ? err.message : String(err);
@@ -412,7 +328,7 @@ export const startSubcommand = createSubcommand({
 			...(process.env as Record<string, string>),
 			AGENTUITY_CODER_HUB_URL: hubWsUrl,
 		};
-		if (resolvedHubApiKey.apiKey) env.AGENTUITY_CODER_API_KEY = resolvedHubApiKey.apiKey;
+		env.AGENTUITY_CODER_API_KEY = ctx.auth.apiKey;
 
 		if (opts?.agent) {
 			env.AGENTUITY_CODER_AGENT = opts.agent;
@@ -440,7 +356,18 @@ export const startSubcommand = createSubcommand({
 				stderr: 'inherit',
 			});
 
+			// Forward signals to the child process so Ctrl+C exits cleanly
+			const onSigInt = () => proc.kill(2);
+			const onSigTerm = () => proc.kill(15);
+			process.on('SIGINT', onSigInt);
+			process.on('SIGTERM', onSigTerm);
+
 			const exitCode = await proc.exited;
+
+			// Clean up only our signal handlers (preserve other modules' listeners)
+			process.removeListener('SIGINT', onSigInt);
+			process.removeListener('SIGTERM', onSigTerm);
+
 			process.exit(exitCode);
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : String(err);

package/src/cmd/coder/tui-init.ts

@@ -1,5 +1,3 @@
-import { hubFetchHeaders } from './hub-url';
-
 export type HubInitProbeResult =
 	| { ok: true }
 	| {
@@ -27,10 +25,16 @@ export async function probeHubInitAccess(
 	}
 ): Promise<HubInitProbeResult> {
 	const fetchImpl = options?.fetchImpl ?? fetch;
+	const headers: Record<string, string> = {
+		accept: 'application/json',
+	};
+	if (options?.apiKey) {
+		headers['x-agentuity-auth-api-key'] = options.apiKey;
+	}
 
 	try {
 		const response = await fetchImpl(`${hubHttpUrl}/api/hub/init`, {
-			headers: hubFetchHeaders({ accept: 'application/json' }, options?.apiKey),
+			headers,
 			signal: AbortSignal.timeout(5_000),
 		});
 

package/src/cmd/coder/update.ts

@@ -0,0 +1,128 @@
+import { z } from 'zod';
+import { CoderClient, normalizeVisibility } from '@agentuity/core/coder';
+import { ValidationOutputError } from '@agentuity/core';
+import { createSubcommand } from '../../types';
+import * as tui from '../../tui';
+import { getCommand } from '../../command-prefix';
+import { ErrorCode } from '../../errors';
+
+export const updateSubcommand = createSubcommand({
+	name: 'update',
+	description: 'Update a Coder session',
+	tags: ['mutating', 'requires-auth'],
+	requires: { auth: true, org: true },
+	aliases: ['set', 'edit'],
+	examples: [
+		{
+			command: getCommand('coder update codesess_abc123 --label "New Label"'),
+			description: 'Update the session label',
+		},
+		{
+			command: getCommand('coder update codesess_abc123 --visibility org'),
+			description: 'Make a session visible to the org',
+		},
+		{
+			command: getCommand('coder update codesess_abc123 --tags "urgent,frontend"'),
+			description: 'Update tags on a session',
+		},
+		{
+			command: getCommand(
+				'coder update codesess_abc123 --workflow-mode loop --loop-goal "Build it" --loop-max-iterations 20'
+			),
+			description: 'Switch a session to loop mode',
+		},
+	],
+	schema: {
+		args: z.object({
+			sessionId: z.string().describe('Session ID to update'),
+		}),
+		options: z.object({
+			url: z.string().optional().describe('Coder API URL override'),
+			label: z.string().optional().describe('Updated session label'),
+			agent: z.string().optional().describe('Updated default agent role'),
+			visibility: z
+				.string()
+				.optional()
+				.describe('Updated visibility: private, org, or collaborate'),
+			workflowMode: z.string().optional().describe('Updated workflow mode: standard or loop'),
+			loopGoal: z.string().optional().describe('Goal for loop mode'),
+			loopMaxIterations: z.number().optional().describe('Maximum loop iterations'),
+			loopAutoContinue: z.boolean().optional().describe('Auto-continue loop'),
+			loopAllowDetached: z.boolean().optional().describe('Allow detached loop execution'),
+			tags: z.string().optional().describe('Comma-separated tags (replaces existing)'),
+		}),
+	},
+	async handler(ctx) {
+		const { args, opts, options } = ctx;
+		const client = new CoderClient({
+			apiKey: ctx.auth.apiKey,
+			url: opts?.url,
+			orgId: ctx.orgId,
+		});
+
+		const body: Record<string, unknown> = {};
+
+		if (opts?.label) body.label = opts.label;
+		if (opts?.agent) body.agent = opts.agent;
+		if (opts?.visibility) body.visibility = normalizeVisibility(opts.visibility);
+		if (opts?.workflowMode) body.workflowMode = opts.workflowMode;
+		if (opts?.tags) {
+			body.tags = opts.tags
+				.split(',')
+				.map((t) => t.trim())
+				.filter(Boolean);
+		}
+
+		if (
+			opts?.loopGoal ||
+			opts?.loopMaxIterations ||
+			opts?.loopAutoContinue !== undefined ||
+			opts?.loopAllowDetached !== undefined
+		) {
+			const loop: Record<string, unknown> = {};
+			if (opts.loopGoal) loop.goal = opts.loopGoal;
+			if (opts.loopMaxIterations) loop.maxIterations = opts.loopMaxIterations;
+			if (opts.loopAutoContinue !== undefined) loop.autoContinue = opts.loopAutoContinue;
+			if (opts.loopAllowDetached !== undefined) loop.allowDetached = opts.loopAllowDetached;
+			body.loop = loop;
+			if (!body.workflowMode) body.workflowMode = 'loop';
+		}
+
+		if (Object.keys(body).length === 0) {
+			tui.fatal(
+				'No update fields provided. Use --label, --visibility, --tags, --agent, --workflow-mode, or loop options.',
+				ErrorCode.VALIDATION_FAILED
+			);
+		}
+
+		try {
+			const updated = await client.updateSession(args.sessionId, body as any);
+
+			if (options.json) {
+				return updated;
+			}
+
+			tui.success(`Session ${args.sessionId} updated.`);
+
+			const fields: string[] = [];
+			if (opts?.label) fields.push(`Label: ${opts.label}`);
+			if (opts?.visibility) fields.push(`Visibility: ${body.visibility}`);
+			if (opts?.tags) fields.push(`Tags: ${(body.tags as string[]).join(', ')}`);
+			if (opts?.agent) fields.push(`Agent: ${opts.agent}`);
+			if (opts?.workflowMode || body.loop) fields.push(`Workflow: ${body.workflowMode}`);
+
+			for (const f of fields) {
+				tui.output(`  ${f}`);
+			}
+
+			return updated;
+		} catch (err) {
+			if (err instanceof ValidationOutputError) {
+				ctx.logger.trace('Validation response URL: %s', err.url ?? 'unknown');
+				ctx.logger.trace('Validation issues: %s', JSON.stringify(err.issues, null, 2));
+			}
+			const msg = err instanceof Error ? err.message : String(err);
+			tui.fatal(`Failed to update session ${args.sessionId}: ${msg}`, ErrorCode.NETWORK_ERROR);
+		}
+	},
+});

package/src/cmd/coder/users.ts

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+import { CoderClient, type CoderUser } from '@agentuity/core/coder';
+import { ValidationOutputError } from '@agentuity/core';
+import { createSubcommand } from '../../types';
+import * as tui from '../../tui';
+import { getCommand } from '../../command-prefix';
+import { ErrorCode } from '../../errors';
+
+function formatRelativeTime(isoDate: string): string {
+	const parsed = new Date(isoDate).getTime();
+	if (Number.isNaN(parsed)) return 'unknown';
+	const diffMs = Math.max(0, Date.now() - parsed);
+	const seconds = Math.floor(diffMs / 1000);
+	if (seconds < 60) return `${seconds}s ago`;
+	const minutes = Math.floor(seconds / 60);
+	if (minutes < 60) return `${minutes}m ago`;
+	const hours = Math.floor(minutes / 60);
+	if (hours < 24) return `${hours}h ago`;
+	const days = Math.floor(hours / 24);
+	return `${days}d ago`;
+}
+
+export const usersSubcommand = createSubcommand({
+	name: 'users',
+	aliases: ['user'],
+	description: 'List known Coder Hub users',
+	tags: ['read-only', 'fast', 'requires-auth'],
+	idempotent: true,
+	requires: { auth: true, org: true },
+	examples: [
+		{
+			command: getCommand('coder users'),
+			description: 'List known users',
+		},
+		{
+			command: getCommand('coder users --search jenny'),
+			description: 'Filter users by display name',
+		},
+		{
+			command: getCommand('coder users --json'),
+			description: 'Return users as JSON',
+		},
+	],
+	schema: {
+		options: z.object({
+			search: z.string().optional().describe('Filter users by display name'),
+			url: z.string().optional().describe('Coder API URL override'),
+		}),
+	},
+	async handler(ctx) {
+		const { options, opts } = ctx;
+		const client = new CoderClient({
+			apiKey: ctx.auth.apiKey,
+			url: opts?.url,
+			orgId: ctx.orgId,
+		});
+
+		let users: CoderUser[] = [];
+		try {
+			const response = await client.listUsers({ search: opts?.search });
+			users = response.users;
+		} catch (err) {
+			if (err instanceof ValidationOutputError) {
+				ctx.logger.trace('Validation response URL: %s', err.url ?? 'unknown');
+				ctx.logger.trace('Validation issues: %s', JSON.stringify(err.issues, null, 2));
+			}
+			const msg = err instanceof Error ? err.message : String(err);
+			tui.fatal(`Failed to list Coder users: ${msg}`, ErrorCode.NETWORK_ERROR);
+		}
+
+		if (options.json) {
+			return users;
+		}
+
+		if (users.length === 0) {
+			tui.info('No Coder users found.');
+			return [];
+		}
+
+		tui.table(
+			users.map((u) => ({
+				User: u.displayName,
+				Email: u.email,
+				Provider: u.provider,
+				'Last Login': formatRelativeTime(u.lastLoginAt),
+				'Last Seen': formatRelativeTime(u.lastSeenAt),
+				Joined: formatRelativeTime(u.createdAt),
+			})),
+			[
+				{ name: 'User', alignment: 'left' },
+				{ name: 'Email', alignment: 'left' },
+				{ name: 'Provider', alignment: 'left' },
+				{ name: 'Last Login', alignment: 'right' },
+				{ name: 'Last Seen', alignment: 'right' },
+				{ name: 'Joined', alignment: 'right' },
+			]
+		);
+
+		return users;
+	},
+});