@agentuity/cli 0.0.48 → 0.0.49

package/src/cli.ts

@@ -9,6 +9,7 @@ import type {
 	Optional,
 	Logger,
 	AuthData,
+	GlobalOptions,
 } from './types';
 import { showBanner } from './banner';
 import { requireAuth, optionalAuth, requireOrg, optionalOrg as selectOptionalOrg } from './auth';
@@ -18,6 +19,9 @@ import * as tui from './tui';
 import { parseArgsSchema, parseOptionsSchema, buildValidationInput } from './schema-parser';
 import { defaultProfileName, loadProjectConfig } from './config';
 import { APIClient, getAPIBaseURL, type APIClient as APIClientType } from './api';
+import { ErrorCode, ExitCode, createError, exitWithError } from './errors';
+import { getCommand } from './command-prefix';
+import { isValidateMode, outputValidation, type ValidationResult } from './output';
 
 function createAPIClient(baseCtx: CommandContext, config: Config | null): APIClient {
 	try {
@@ -41,6 +45,71 @@ function createAPIClient(baseCtx: CommandContext, config: Config | null): APICli
 	}
 }
 
+/**
+ * Execute handler or output validation result based on mode
+ */
+async function executeOrValidate(
+	ctx: CommandContext,
+	commandName: string,
+	handler?: (ctx: CommandContext) => unknown | Promise<unknown>
+): Promise<void> {
+	if (isValidateMode(ctx.options)) {
+		// In validate mode, just output success (validation already passed via Zod)
+		const result: ValidationResult = {
+			valid: true,
+			command: commandName,
+		};
+		outputValidation(result, ctx.options);
+	} else if (handler) {
+		// Normal execution
+		await handler(ctx);
+	}
+}
+
+/**
+ * Handle validation error - output structured result in validate mode, otherwise log and exit
+ */
+function handleValidationError(
+	error: unknown,
+	commandName: string,
+	baseCtx: { options: GlobalOptions; logger: Logger }
+): never {
+	if (error && typeof error === 'object' && 'issues' in error) {
+		const issues = (error as { issues: Array<{ path: string[]; message: string }> }).issues;
+
+		if (isValidateMode(baseCtx.options)) {
+			// In validate mode, output structured validation result
+			const result: ValidationResult = {
+				valid: false,
+				command: commandName,
+				errors: issues.map((issue) => ({
+					field: issue.path?.length ? issue.path.join('.') : 'unknown',
+					message: issue.message,
+				})),
+			};
+			outputValidation(result, baseCtx.options);
+			process.exit(ExitCode.VALIDATION_ERROR);
+		} else {
+			// Use centralized error handling
+			exitWithError(
+				{
+					code: ErrorCode.VALIDATION_FAILED,
+					message: 'Validation error',
+					details: {
+						issues: issues.map((issue) => ({
+							field: issue.path?.length ? issue.path.join('.') : 'unknown',
+							message: issue.message,
+						})),
+					},
+				},
+				baseCtx.logger,
+				baseCtx.options.errorFormat ?? 'text'
+			);
+		}
+	}
+	throw error;
+}
+
 type Normalized = {
 	requiresAuth: boolean;
 	optionalAuth: false | string;
@@ -97,7 +166,12 @@ function normalizeReqs(def: CommandDefinition | SubcommandDefinition): Normalize
 	};
 }
 
-function handleProjectConfigError(error: unknown, requiresProject: boolean, logger: Logger): never {
+function handleProjectConfigError(
+	error: unknown,
+	requiresProject: boolean,
+	logger: Logger,
+	errorFormat?: 'json' | 'text'
+): never {
 	if (
 		requiresProject &&
 		error &&
@@ -105,8 +179,14 @@ function handleProjectConfigError(error: unknown, requiresProject: boolean, logg
 		'name' in error &&
 		error.name === 'ProjectConfigNotFoundExpection'
 	) {
-		logger.fatal(
-			'invalid project folder. use --dir to specify a different directory or change to a project folder'
+		exitWithError(
+			createError(ErrorCode.PROJECT_NOT_FOUND, 'Invalid project folder', undefined, [
+				'Use --dir to specify a different directory',
+				'Change to a directory containing agentuity.json',
+				`Run "${getCommand('project init')}" to create a new project`,
+			]),
+			logger,
+			errorFormat ?? 'text'
 		);
 	}
 	throw error;
@@ -117,11 +197,11 @@ export async function createCLI(version: string): Promise<Command> {
 
 	program
 		.name('agentuity')
-		.description('Agentuity CLI')
 		.version(version, '-V, --version', 'Display version')
-		.helpOption('-h, --help', 'Display help')
+		.helpOption('-h, --help=[json]', 'Display help (with optional JSON output)')
 		.allowUnknownOption(false)
-		.allowExcessArguments(false);
+		.allowExcessArguments(false)
+		.showHelpAfterError(true);
 
 	program
 		.option('--config <path>', 'Config file path')
@@ -133,7 +213,15 @@ export async function createCLI(version: string): Promise<Command> {
 			'Use a specific organization when performing operations',
 			process.env.AGENTUITY_CLOUD_ORG_ID
 		)
-		.option('--color-scheme <scheme>', 'Color scheme: light or dark');
+		.option('--color-scheme <scheme>', 'Color scheme: light or dark')
+		.option('--color <mode>', 'Color output: auto, always, never', 'auto')
+		.option('--error-format <format>', 'Error output format: json or text', 'text')
+		.option('--json', 'Output in JSON format (machine-readable)', false)
+		.option('--quiet', 'Suppress non-essential output', false)
+		.option('--no-progress', 'Disable progress indicators', false)
+		.option('--explain', 'Show what the command would do without executing', false)
+		.option('--dry-run', 'Execute command without making changes', false)
+		.option('--validate', 'Validate arguments and options without executing', false);
 
 	const skipVersionCheckOption = program.createOption(
 		'--skip-version-check',
@@ -160,7 +248,7 @@ export async function createCLI(version: string): Promise<Command> {
 			});
 		}
 		console.error();
-		console.error(`Run 'agentuity --help' for usage information.`);
+		console.error(`Run '${getCommand('--help')}' for usage information.`);
 		process.exit(1);
 	});
 
@@ -173,7 +261,7 @@ export async function createCLI(version: string): Promise<Command> {
 				const match = str.match(/got (\d+)/);
 				if (match) {
 					write(`error: unknown command or subcommand\n`);
-					write(`\nRun 'agentuity --help' for available commands.\n`);
+					write(`\nRun '${getCommand('--help')}' for available commands.\n`);
 				} else {
 					write(str);
 				}
@@ -219,7 +307,17 @@ async function resolveRegion(opts: ResolveRegionOptions): Promise<string | undef
 	// No regions available
 	if (regions.length === 0) {
 		if (required) {
-			logger.fatal('No cloud regions available');
+			const errorFormat = (options as Record<string, unknown>).errorFormat as
+				| 'json'
+				| 'text'
+				| undefined;
+			exitWithError(
+				createError(ErrorCode.NO_REGIONS_AVAILABLE, 'No cloud regions available', undefined, [
+					'Contact support if you need access to cloud regions',
+				]),
+				logger,
+				errorFormat ?? 'text'
+			);
 		}
 		return undefined;
 	}
@@ -231,8 +329,19 @@ async function resolveRegion(opts: ResolveRegionOptions): Promise<string | undef
 	if (region) {
 		const found = regions.find((r) => r.region === region);
 		if (!found) {
-			logger.fatal(
-				`Invalid region '${region}'. Use one of: ${regions.map((r) => r.region).join(', ')}`
+			const errorFormat = (options as Record<string, unknown>).errorFormat as
+				| 'json'
+				| 'text'
+				| undefined;
+			exitWithError(
+				createError(
+					ErrorCode.REGION_NOT_FOUND,
+					`Invalid region '${region}'`,
+					{ region, availableRegions: regions.map((r) => r.region) },
+					[`Use one of: ${regions.map((r) => r.region).join(', ')}`]
+				),
+				logger,
+				errorFormat ?? 'text'
 			);
 		}
 		return region;
@@ -249,7 +358,20 @@ async function resolveRegion(opts: ResolveRegionOptions): Promise<string | undef
 
 	// No flag provided - handle TTY vs non-TTY
 	if (required && !process.stdin.isTTY) {
-		logger.fatal('--region flag is required in non-interactive mode');
+		const errorFormat = (options as Record<string, unknown>).errorFormat as
+			| 'json'
+			| 'text'
+			| undefined;
+		exitWithError(
+			createError(
+				ErrorCode.REGION_REQUIRED,
+				'--region flag is required in non-interactive mode',
+				{ availableRegions: regions.map((r) => r.region) },
+				[`Use --region with one of: ${regions.map((r) => r.region).join(', ')}`]
+			),
+			logger,
+			errorFormat ?? 'text'
+		);
 	}
 
 	if (process.stdin.isTTY) {
@@ -274,6 +396,13 @@ async function registerSubcommand(
 		cmd.aliases(subcommand.aliases);
 	}
 
+	// Add examples to help text
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	const examples = (subcommand as any).examples as string[] | undefined;
+	if (examples && examples.length > 0) {
+		cmd.addHelpText('after', '\nExamples:\n' + examples.map((ex) => `  ${ex}`).join('\n'));
+	}
+
 	// Check if this subcommand has its own subcommands (nested subcommands)
 	const subDef = subcommand as unknown as { subcommands?: SubcommandDefinition[] };
 	if (subDef.subcommands && subDef.subcommands.length > 0) {
@@ -368,8 +497,14 @@ async function registerSubcommand(
 						'name' in error &&
 						error.name === 'ProjectConfigNotFoundExpection'
 					) {
-						baseCtx.logger.fatal(
-							'invalid project folder. use --dir to specify a different directory or change to a project folder'
+						exitWithError(
+							createError(ErrorCode.PROJECT_NOT_FOUND, 'Invalid project folder', undefined, [
+								'Use --dir to specify a different directory',
+								'Change to a directory containing agentuity.json',
+								`Run "${getCommand('project init')}" to create a new project`,
+							]),
+							baseCtx.logger,
+							baseCtx.options.errorFormat
 						);
 					}
 					throw error;
@@ -448,22 +583,21 @@ async function registerSubcommand(
 							ctx.region = region;
 						}
 					}
-					if (subcommand.handler) {
-						await subcommand.handler(ctx as CommandContext);
-					}
+					await executeOrValidate(
+						ctx as CommandContext,
+						`${parent.name()} ${subcommand.name}`,
+						subcommand.handler
+					);
 				} catch (error) {
 					if (error && typeof error === 'object' && 'issues' in error) {
-						baseCtx.logger.error('Validation error:');
-						const issues = (error as { issues: Array<{ path: string[]; message: string }> })
-							.issues;
-						for (const issue of issues) {
-							baseCtx.logger.error(
-								`  ${issue.path?.length ? issue.path.join('.') + ': ' : ''}${issue.message}`
-							);
-						}
-						process.exit(1);
+						handleValidationError(error, `${parent.name()} ${subcommand.name}`, baseCtx);
 					}
-					handleProjectConfigError(error, normalized.requiresProject, baseCtx.logger);
+					handleProjectConfigError(
+						error,
+						normalized.requiresProject,
+						baseCtx.logger,
+						baseCtx.options.errorFormat
+					);
 				}
 			} else {
 				const ctx: Record<string, unknown> = {
@@ -596,22 +730,21 @@ async function registerSubcommand(
 							ctx.region = region;
 						}
 					}
-					if (subcommand.handler) {
-						await subcommand.handler(ctx as CommandContext);
-					}
+					await executeOrValidate(
+						ctx as CommandContext,
+						`${parent.name()} ${subcommand.name}`,
+						subcommand.handler
+					);
 				} catch (error) {
 					if (error && typeof error === 'object' && 'issues' in error) {
-						baseCtx.logger.error('Validation error:');
-						const issues = (error as { issues: Array<{ path: string[]; message: string }> })
-							.issues;
-						for (const issue of issues) {
-							baseCtx.logger.error(
-								`  ${issue.path?.length ? issue.path.join('.') + ': ' : ''}${issue.message}`
-							);
-						}
-						process.exit(1);
+						handleValidationError(error, `${parent.name()} ${subcommand.name}`, baseCtx);
 					}
-					handleProjectConfigError(error, normalized.requiresProject, baseCtx.logger);
+					handleProjectConfigError(
+						error,
+						normalized.requiresProject,
+						baseCtx.logger,
+						baseCtx.options.errorFormat
+					);
 				}
 			} else {
 				const ctx: Record<string, unknown> = {
@@ -694,22 +827,21 @@ async function registerSubcommand(
 							ctx as CommandContext & { apiClient: APIClientType }
 						);
 					}
-					if (subcommand.handler) {
-						await subcommand.handler(ctx as CommandContext);
-					}
+					await executeOrValidate(
+						ctx as CommandContext,
+						`${parent.name()} ${subcommand.name}`,
+						subcommand.handler
+					);
 				} catch (error) {
 					if (error && typeof error === 'object' && 'issues' in error) {
-						baseCtx.logger.error('Validation error:');
-						const issues = (error as { issues: Array<{ path: string[]; message: string }> })
-							.issues;
-						for (const issue of issues) {
-							baseCtx.logger.error(
-								`  ${issue.path?.length ? issue.path.join('.') + ': ' : ''}${issue.message}`
-							);
-						}
-						process.exit(1);
+						handleValidationError(error, `${parent.name()} ${subcommand.name}`, baseCtx);
 					}
-					handleProjectConfigError(error, normalized.requiresProject, baseCtx.logger);
+					handleProjectConfigError(
+						error,
+						normalized.requiresProject,
+						baseCtx.logger,
+						baseCtx.options.errorFormat
+					);
 				}
 			} else {
 				const ctx: Record<string, unknown> = {

package/src/cmd/auth/index.ts

@@ -8,5 +8,6 @@ import { sshSubcommand } from './ssh';
 export const command = createCommand({
 	name: 'auth',
 	description: 'Authentication and authorization related commands',
+	tags: ['read-only', 'fast'],
 	subcommands: [loginCommand, logoutCommand, signupCommand, whoamiCommand, sshSubcommand],
 });

package/src/cmd/auth/login.ts

@@ -4,12 +4,17 @@ import { getAppBaseURL } from '../../api';
 import { saveAuth } from '../../config';
 import { generateLoginOTP, pollForLoginCompletion } from './api';
 import * as tui from '../../tui';
+import { getCommand } from '../../command-prefix';
+import { ErrorCode } from '../../errors';
 
 export const loginCommand = createSubcommand({
 	name: 'login',
 	description: 'Login to the Agentuity Platform using a browser-based authentication flow',
+	tags: ['mutating', 'creates-resource', 'slow', 'api-intensive'],
 	toplevel: true,
+	idempotent: false,
 	requires: { apiClient: true },
+	examples: [getCommand('auth login'), getCommand('login')],
 	async handler(ctx) {
 		const { logger, config, apiClient } = ctx;
 
@@ -78,9 +83,9 @@ export const loginCommand = createSubcommand({
 				error.issues.map((i) => tui.arrow(`${i.message} for ${i.path}`));
 				process.exit(1);
 			} else if (error instanceof Error) {
-				logger.fatal(`Login failed: ${error.message}`);
+				logger.fatal(`Login failed: ${error.message}`, ErrorCode.AUTH_FAILED);
 			} else {
-				logger.fatal('Login failed');
+				logger.fatal('Login failed', ErrorCode.AUTH_FAILED);
 			}
 		}
 	},

package/src/cmd/auth/logout.ts

@@ -1,11 +1,15 @@
 import { createSubcommand } from '../../types';
 import { clearAuth } from '../../config';
 import * as tui from '../../tui';
+import { getCommand } from '../../command-prefix';
 
 export const logoutCommand = createSubcommand({
 	name: 'logout',
 	description: 'Logout of the Agentuity Cloud Platform',
+	tags: ['mutating', 'deletes-resource', 'fast', 'requires-auth'],
 	toplevel: true,
+	idempotent: false,
+	examples: [getCommand('auth logout'), getCommand('logout')],
 
 	async handler() {
 		await clearAuth();

package/src/cmd/auth/signup.ts

@@ -3,12 +3,17 @@ import { getAppBaseURL, UpgradeRequiredError } from '@agentuity/server';
 import { saveAuth } from '../../config';
 import { generateSignupOTP, pollForSignupCompletion } from './api';
 import * as tui from '../../tui';
+import { getCommand } from '../../command-prefix';
+import { ErrorCode } from '../../errors';
 
 export const signupCommand = createSubcommand({
 	name: 'signup',
 	description: 'Create a new Agentuity Cloud Platform account',
+	tags: ['mutating', 'creates-resource', 'slow', 'api-intensive'],
 	toplevel: true,
+	idempotent: false,
 	requires: { apiClient: true },
+	examples: [getCommand('auth signup'), getCommand('signup')],
 
 	async handler(ctx) {
 		const { logger, config, apiClient } = ctx;
@@ -46,9 +51,9 @@ export const signupCommand = createSubcommand({
 				tui.banner('CLI Upgrade Required', bannerBody);
 				process.exit(1);
 			} else if (error instanceof Error) {
-				logger.fatal(`Signup failed: ${error.message}`);
+				logger.fatal(`Signup failed: ${error.message}`, ErrorCode.AUTH_FAILED);
 			} else {
-				logger.fatal('Signup failed');
+				logger.fatal('Signup failed', ErrorCode.AUTH_FAILED);
 			}
 		}
 	},

package/src/cmd/auth/ssh/add.ts

@@ -7,11 +7,19 @@ import { readFileSync, readdirSync, statSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 import { z } from 'zod';
+import { ErrorCode } from '../../../errors';
 
 const optionsSchema = z.object({
 	file: z.string().optional().describe('File containing the public key'),
 });
 
+const SSHAddResponseSchema = z.object({
+	success: z.boolean().describe('Whether the operation succeeded'),
+	fingerprint: z.string().describe('SSH key fingerprint'),
+	keyType: z.string().describe('SSH key type (e.g., ssh-rsa, ssh-ed25519)'),
+	added: z.number().describe('Number of keys added'),
+});
+
 interface SSHKeyOption {
 	path: string;
 	filename: string;
@@ -107,15 +115,24 @@ export const addCommand = createSubcommand({
 	name: 'add',
 	aliases: ['create'],
 	description: 'Add an SSH public key to your account (reads from file or stdin)',
+	tags: ['mutating', 'creates-resource', 'slow', 'requires-auth'],
+	idempotent: false,
 	requires: { apiClient: true, auth: true },
+	examples: [
+		getCommand('auth ssh add'),
+		getCommand('auth ssh add --file ~/.ssh/id_ed25519.pub'),
+		getCommand('auth ssh add --file ./deploy_key.pub'),
+		'cat ~/.ssh/id_rsa.pub | ' + getCommand('auth ssh add'),
+	],
 	schema: {
 		options: optionsSchema,
+		response: SSHAddResponseSchema,
 	},
 	async handler(ctx) {
 		const { logger, apiClient, opts } = ctx;
 
 		if (!apiClient) {
-			logger.fatal('API client is not available');
+			logger.fatal('API client is not available', ErrorCode.INTERNAL_ERROR);
 		}
 
 		try {
@@ -254,9 +271,9 @@ export const addCommand = createSubcommand({
 		} catch (error) {
 			logger.trace(error);
 			if (error instanceof Error) {
-				logger.fatal(`Failed to add SSH key: ${error.message}`);
+				logger.fatal(`Failed to add SSH key: ${error.message}`, ErrorCode.API_ERROR);
 			} else {
-				logger.fatal('Failed to add SSH key');
+				logger.fatal('Failed to add SSH key', ErrorCode.API_ERROR);
 			}
 		}
 	},

package/src/cmd/auth/ssh/delete.ts

@@ -3,12 +3,29 @@ import { removeSSHKey, listSSHKeys } from './api';
 import * as tui from '../../../tui';
 import enquirer from 'enquirer';
 import { z } from 'zod';
+import { isExplainMode, isDryRunMode, outputExplain, outputDryRun } from '../../../explain';
+import { getCommand } from '../../../command-prefix';
+import { ErrorCode } from '../../../errors';
+
+const SSHDeleteResponseSchema = z.object({
+	success: z.boolean().describe('Whether the operation succeeded'),
+	removed: z.number().describe('Number of keys removed'),
+	fingerprints: z.array(z.string()).describe('Fingerprints of removed keys'),
+});
 
 export const deleteCommand = createSubcommand({
 	name: 'delete',
 	aliases: ['rm', 'del', 'remove'],
 	description: 'Delete an SSH key from your account',
+	tags: ['destructive', 'deletes-resource', 'slow', 'requires-auth'],
 	requires: { apiClient: true, auth: true },
+	idempotent: false,
+	examples: [
+		getCommand('auth ssh delete'),
+		getCommand('auth ssh delete <fingerprint>'),
+		getCommand('--explain auth ssh delete abc123'),
+		getCommand('--dry-run auth ssh delete abc123'),
+	],
 	schema: {
 		args: z.object({
 			fingerprints: z.array(z.string()).optional().describe('SSH key fingerprint(s) to remove'),
@@ -16,12 +33,13 @@ export const deleteCommand = createSubcommand({
 		options: z.object({
 			confirm: z.boolean().default(true).describe('prompt for confirmation before deletion'),
 		}),
+		response: SSHDeleteResponseSchema,
 	},
 	async handler(ctx) {
-		const { logger, apiClient, args, opts } = ctx;
+		const { logger, apiClient, args, opts, options } = ctx;
 
 		if (!apiClient) {
-			logger.fatal('API client is not available');
+			logger.fatal('API client is not available', ErrorCode.INTERNAL_ERROR);
 		}
 
 		const shouldConfirm = process.stdin.isTTY ? opts.confirm : false;
@@ -67,6 +85,22 @@ export const deleteCommand = createSubcommand({
 				}
 			}
 
+			// If in explain mode, show what would happen
+			if (isExplainMode(options)) {
+				outputExplain(
+					{
+						command: 'auth ssh delete',
+						description: 'Delete SSH keys from your account',
+						steps: fingerprintsToRemove.map((fp) => ({
+							action: `Remove SSH key with fingerprint: ${fp}`,
+						})),
+						warnings: ['This action cannot be undone'],
+					},
+					options
+				);
+				return;
+			}
+
 			if (shouldConfirm) {
 				tui.newline();
 				const confirmed = await tui.confirm(
@@ -80,6 +114,19 @@ export const deleteCommand = createSubcommand({
 				}
 			}
 
+			// Handle dry-run mode
+			if (isDryRunMode(options)) {
+				for (const fingerprint of fingerprintsToRemove) {
+					outputDryRun(`Would remove SSH key: ${fingerprint}`, options);
+				}
+				tui.newline();
+				tui.info(
+					`[DRY RUN] Would remove ${fingerprintsToRemove.length} SSH key${fingerprintsToRemove.length > 1 ? 's' : ''}`
+				);
+				return;
+			}
+
+			// Actually execute the deletion
 			for (const fingerprint of fingerprintsToRemove) {
 				await tui.spinner(`Removing SSH key ${fingerprint}...`, () =>
 					removeSSHKey(apiClient, fingerprint)
@@ -90,12 +137,18 @@ export const deleteCommand = createSubcommand({
 			tui.success(
 				`Removed ${fingerprintsToRemove.length} SSH key${fingerprintsToRemove.length > 1 ? 's' : ''}`
 			);
+
+			return {
+				success: true,
+				removed: fingerprintsToRemove.length,
+				fingerprints: fingerprintsToRemove,
+			};
 		} catch (error) {
 			logger.trace(error);
 			if (error instanceof Error) {
-				logger.fatal(`Failed to remove SSH key: ${error.message}`);
+				logger.fatal(`Failed to remove SSH key: ${error.message}`, ErrorCode.API_ERROR);
 			} else {
-				logger.fatal('Failed to remove SSH key');
+				logger.fatal('Failed to remove SSH key', ErrorCode.API_ERROR);
 			}
 		}
 	},

package/src/cmd/auth/ssh/index.ts

@@ -1,10 +1,11 @@
-import type { SubcommandDefinition } from '../../../types';
+import { createCommand } from '../../../types';
 import { listCommand } from './list';
 import { addCommand } from './add';
 import { deleteCommand } from './delete';
 
-export const sshSubcommand: SubcommandDefinition = {
+export const sshSubcommand = createCommand({
 	name: 'ssh',
 	description: 'Manage SSH keys',
+	tags: ['fast', 'requires-auth'],
 	subcommands: [listCommand, addCommand, deleteCommand],
-};
+});