@agentuity/cli 0.0.48 → 0.0.50

package/src/cmd/profile/create.ts

@@ -12,13 +12,22 @@ import {
 	saveProfile,
 } from '../../config';
 import * as tui from '../../tui';
+import { getCommand } from '../../command-prefix';
+import { ErrorCode } from '../../errors';
 
 const PROFILE_NAME_REGEX = /^[\w_-]{3,}$/;
 
 export const createCommand = createSubcommand({
 	name: 'create',
 	description: 'Create a new configuration profile',
+	tags: ['mutating', 'creates-resource', 'fast'],
 	aliases: ['new'],
+	idempotent: false,
+	examples: [
+		getCommand('profile create production'),
+		getCommand('profile create staging --switch'),
+		getCommand('profile create development'),
+	],
 	schema: {
 		args: z
 			.object({
@@ -32,6 +41,11 @@ export const createCommand = createSubcommand({
 		options: z.object({
 			switch: z.boolean().optional().describe('switch to this profile (if more than one)'),
 		}),
+		response: z.object({
+			success: z.boolean().describe('Whether creation succeeded'),
+			name: z.string().describe('Profile name'),
+			path: z.string().describe('Profile file path'),
+		}),
 	},
 
 	async handler(ctx) {
@@ -42,7 +56,10 @@ export const createCommand = createSubcommand({
 		const existing = profiles.find((p) => p.name === name);
 
 		if (existing) {
-			return logger.fatal(`Profile "${name}" already exists at ${existing.filename}`);
+			return logger.fatal(
+				`Profile "${name}" already exists at ${existing.filename}`,
+				ErrorCode.RESOURCE_ALREADY_EXISTS
+			);
 		}
 
 		await ensureConfigDir();
@@ -77,10 +94,19 @@ export const createCommand = createSubcommand({
 			}
 
 			tui.success(`Created profile "${name}" at ${filename}`);
+
+			return {
+				success: true,
+				name,
+				path: filename,
+			};
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
 			const stack = error instanceof Error ? error.stack : undefined;
-			logger.fatal(`Failed to create profile: ${message}${stack ? `\n${stack}` : ''}`);
+			logger.fatal(
+				`Failed to create profile: ${message}${stack ? `\n${stack}` : ''}`,
+				ErrorCode.INTERNAL_ERROR
+			);
 		}
 	},
 });

package/src/cmd/profile/delete.ts

@@ -3,11 +3,20 @@ import { z } from 'zod';
 import { fetchProfiles } from '../../config';
 import { unlink } from 'node:fs/promises';
 import * as tui from '../../tui';
+import { getCommand } from '../../command-prefix';
+import { ErrorCode } from '../../errors';
 
 export const deleteCommand = createSubcommand({
 	name: 'delete',
 	description: 'Delete a configuration profile',
+	tags: ['destructive', 'deletes-resource', 'fast'],
+	idempotent: false,
 	aliases: ['remove', 'rm', 'del'],
+	examples: [
+		getCommand('profile delete staging'),
+		getCommand('profile delete old-dev --confirm'),
+		getCommand('profile delete'),
+	],
 	schema: {
 		args: z.object({
 			name: z.string().optional().describe('The name of the profile to delete'),
@@ -15,6 +24,10 @@ export const deleteCommand = createSubcommand({
 		options: z.object({
 			confirm: z.boolean().optional().describe('Skip confirmation prompt'),
 		}),
+		response: z.object({
+			success: z.boolean().describe('Whether deletion succeeded'),
+			name: z.string().describe('Deleted profile name'),
+		}),
 	},
 
 	async handler(ctx) {
@@ -30,7 +43,7 @@ export const deleteCommand = createSubcommand({
 		const profile = profiles.find((p) => p.name === name);
 
 		if (!profile) {
-			return logger.fatal(`Profile "${name}" not found`);
+			return logger.fatal(`Profile "${name}" not found`, ErrorCode.RESOURCE_NOT_FOUND);
 		}
 
 		// Ask for confirmation unless --confirm flag is passed
@@ -38,7 +51,7 @@ export const deleteCommand = createSubcommand({
 			const confirmed = await tui.confirm(`Delete profile "${name}"?`, false);
 			if (!confirmed) {
 				logger.info('Cancelled');
-				return;
+				return { success: false, name };
 			}
 		}
 
@@ -50,6 +63,8 @@ export const deleteCommand = createSubcommand({
 					'The active profile was deleted. Use "profile use <name>" to select a new default.'
 				);
 			}
+
+			return { success: true, name };
 		} catch (error) {
 			logger.fatal(`Failed to delete profile: ${error}`);
 		}

package/src/cmd/profile/index.ts

@@ -8,5 +8,6 @@ import { deleteCommand } from './delete';
 export const command = createCommand({
 	name: 'profile',
 	description: 'Manage configuration profiles',
+	tags: ['read-only', 'fast'],
 	subcommands: [createProfileCmd, useCommand, listCommand, showCommand, deleteCommand],
 });

package/src/cmd/profile/list.ts

@@ -1,12 +1,16 @@
-import type { SubcommandDefinition } from '../../types';
+import { createSubcommand } from '../../types';
 import { fetchProfiles } from '../../config';
 import { basename, dirname } from 'node:path';
 import * as tui from '../../tui';
+import { getCommand } from '../../command-prefix';
 
-export const listCommand: SubcommandDefinition = {
+export const listCommand = createSubcommand({
 	name: 'list',
 	description: 'List all available profiles',
+	tags: ['read-only', 'fast'],
+	idempotent: true,
 	aliases: ['ls'],
+	examples: [getCommand('profile list'), getCommand('profile ls')],
 
 	async handler() {
 		const profiles = await fetchProfiles();
@@ -24,4 +28,4 @@ export const listCommand: SubcommandDefinition = {
 			console.log(`${marker} ${name} ${tui.muted(path)}`);
 		}
 	},
-};
+});

package/src/cmd/profile/show.ts

@@ -1,13 +1,23 @@
-import { createSubcommand } from '../../types';
+import { createSubcommand, ConfigSchema } from '../../types';
 import { z } from 'zod';
 import { fetchProfiles, loadConfig } from '../../config';
 import { readFile } from 'node:fs/promises';
 import * as tui from '../../tui';
+import { getCommand } from '../../command-prefix';
+import { ErrorCode } from '../../errors';
+
+const ProfileShowResponseSchema = ConfigSchema;
 
 export const showCommand = createSubcommand({
 	name: 'show',
 	description: 'Show the configuration of a profile',
+	tags: ['read-only', 'fast'],
 	aliases: ['current'],
+	examples: [
+		getCommand('profile show'),
+		getCommand('profile show production'),
+		getCommand('profile show staging --json'),
+	],
 	schema: {
 		options: z.object({
 			json: z.boolean().optional().describe('Show the JSON config'),
@@ -17,7 +27,9 @@ export const showCommand = createSubcommand({
 				name: z.string().optional().describe('Profile name to show (optional)'),
 			})
 			.describe('Profile show arguments'),
+		response: ProfileShowResponseSchema,
 	},
+	idempotent: true,
 
 	async handler(ctx) {
 		const { logger, args, opts } = ctx;
@@ -35,7 +47,7 @@ export const showCommand = createSubcommand({
 			const profile = profiles.find((p) => p.name === name);
 
 			if (!profile) {
-				return logger.fatal(`Profile "${name}" not found`);
+				return logger.fatal(`Profile "${name}" not found`, ErrorCode.RESOURCE_NOT_FOUND);
 			}
 
 			const profilePath = profile.filename;
@@ -43,14 +55,17 @@ export const showCommand = createSubcommand({
 
 			tui.info(`Profile: ${profilePath}`);
 
+			const content = await loadConfig(current ? undefined : profilePath);
+
 			if (opts?.json) {
-				const content = await loadConfig(current ? undefined : profilePath);
 				console.log(JSON.stringify(content, null, 2));
 			} else {
 				tui.newline();
-				const content = await readFile(profilePath, 'utf-8');
-				console.log(content);
+				const textContent = await readFile(profilePath, 'utf-8');
+				console.log(textContent);
 			}
+
+			return content;
 		} catch (error) {
 			if (error instanceof Error) {
 				logger.fatal(`Failed to show profile: ${error.message}`);

package/src/cmd/profile/use.ts

@@ -2,11 +2,19 @@ import { createSubcommand } from '../../types';
 import { z } from 'zod';
 import { fetchProfiles, saveProfile } from '../../config';
 import * as tui from '../../tui';
+import { getCommand } from '../../command-prefix';
 
 export const useCommand = createSubcommand({
 	name: 'use',
 	description: 'Switch to a different configuration profile',
+	tags: ['mutating', 'updates-resource', 'fast'],
 	aliases: ['switch'],
+	idempotent: true,
+	examples: [
+		getCommand('profile use production'),
+		getCommand('profile switch staging'),
+		getCommand('profile use'),
+	],
 	schema: {
 		args: z.object({
 			name: z.string().optional().describe('The name of the profile to use'),

package/src/cmd/project/create.ts

@@ -1,15 +1,35 @@
 import { createSubcommand } from '../../types';
 import { z } from 'zod';
 import { runCreateFlow } from './template-flow';
+import { getCommand } from '../../command-prefix';
+
+const ProjectCreateResponseSchema = z.object({
+	success: z.boolean().describe('Whether the operation succeeded'),
+	name: z.string().describe('Project name'),
+	path: z.string().describe('Project directory path'),
+	projectId: z.string().optional().describe('Project ID if registered'),
+	template: z.string().describe('Template used'),
+	installed: z.boolean().describe('Whether dependencies were installed'),
+	built: z.boolean().describe('Whether the project was built'),
+});
 
 export const createProjectSubcommand = createSubcommand({
 	name: 'create',
 	description: 'Create a new project',
+	tags: ['mutating', 'creates-resource', 'slow', 'api-intensive', 'requires-auth'],
 	aliases: ['new'],
 	banner: true,
 	toplevel: true,
+	idempotent: false,
 	optional: { auth: true, org: true, region: true },
 	requires: { apiClient: true },
+	examples: [
+		getCommand('project create'),
+		getCommand('project create --name my-ai-agent'),
+		getCommand('project create --name customer-service-bot --dir ~/projects/agent'),
+		getCommand('project create --template basic --no-install'),
+		getCommand('project new --no-register'),
+	],
 	schema: {
 		options: z.object({
 			name: z.string().optional().describe('Project name'),
@@ -40,6 +60,7 @@ export const createProjectSubcommand = createSubcommand({
 				.optional()
 				.describe('Register the project, if authenticated (use --no-register to skip)'),
 		}),
+		response: ProjectCreateResponseSchema,
 	},
 
 	async handler(ctx) {
@@ -61,5 +82,15 @@ export const createProjectSubcommand = createSubcommand({
 			orgId,
 			region,
 		});
+
+		// Return best-effort response (runCreateFlow doesn't return values)
+		return {
+			success: true,
+			name: opts.name || 'project',
+			path: opts.dir || process.cwd(),
+			template: opts.template || 'default',
+			installed: opts.install !== false,
+			built: opts.build !== false,
+		};
 	},
 });

package/src/cmd/project/delete.ts

@@ -3,12 +3,23 @@ import { createSubcommand } from '../../types';
 import * as tui from '../../tui';
 import { projectDelete, projectList } from '@agentuity/server';
 import enquirer from 'enquirer';
+import { getCommand } from '../../command-prefix';
 
 export const deleteSubcommand = createSubcommand({
 	name: 'delete',
 	description: 'Delete a project',
+	tags: ['destructive', 'deletes-resource', 'slow', 'requires-auth'],
 	aliases: ['rm', 'del'],
 	requires: { auth: true, apiClient: true },
+	idempotent: false,
+	examples: [
+		getCommand('project delete'),
+		getCommand('project delete proj_abc123def456'),
+		getCommand('project delete proj_abc123def456 --confirm'),
+		getCommand('project rm proj_abc123def456'),
+		getCommand('--explain project delete proj_abc123def456'),
+		getCommand('--dry-run project delete proj_abc123def456'),
+	],
 	schema: {
 		args: z.object({
 			id: z.string().optional().describe('the project id'),
@@ -16,6 +27,11 @@ export const deleteSubcommand = createSubcommand({
 		options: z.object({
 			confirm: z.boolean().optional().describe('Skip confirmation prompts'),
 		}),
+		response: z.object({
+			success: z.boolean().describe('Whether the deletion succeeded'),
+			projectIds: z.array(z.string()).describe('Deleted project IDs'),
+			count: z.number().describe('Number of projects deleted'),
+		}),
 	},
 
 	async handler(ctx) {
@@ -67,7 +83,7 @@ export const deleteSubcommand = createSubcommand({
 
 		if (projectIds.length === 0) {
 			tui.info('No projects selected for deletion');
-			return;
+			return { success: false, projectIds: [], count: 0 };
 		}
 
 		const skipConfirm = opts?.confirm === true;
@@ -90,7 +106,7 @@ export const deleteSubcommand = createSubcommand({
 
 			if (!confirm.confirm) {
 				tui.info('Deletion cancelled');
-				return;
+				return { success: false, projectIds: [], count: 0 };
 			}
 		}
 
@@ -107,5 +123,11 @@ export const deleteSubcommand = createSubcommand({
 		} else {
 			tui.error('Failed to delete projects');
 		}
+
+		return {
+			success: deleted.length > 0,
+			projectIds: deleted,
+			count: deleted.length,
+		};
 	},
 });

package/src/cmd/project/index.ts

@@ -7,5 +7,6 @@ import { showSubcommand } from './show';
 export const command = createCommand({
 	name: 'project',
 	description: 'Manage Agentuity projects',
+	tags: ['fast', 'requires-auth'],
 	subcommands: [createProjectSubcommand, listSubcommand, deleteSubcommand, showSubcommand],
 });

package/src/cmd/project/list.ts

@@ -1,24 +1,36 @@
-import { z } from 'zod';
 import { createSubcommand } from '../../types';
 import * as tui from '../../tui';
 import { projectList } from '@agentuity/server';
+import { getCommand } from '../../command-prefix';
+import { z } from 'zod';
+
+const ProjectListResponseSchema = z.array(
+	z.object({
+		id: z.string().describe('Project ID'),
+		name: z.string().describe('Project name'),
+		orgId: z.string().describe('Organization ID'),
+		orgName: z.string().describe('Organization name'),
+	})
+);
 
 export const listSubcommand = createSubcommand({
 	name: 'list',
 	description: 'List all projects',
+	tags: ['read-only', 'slow', 'requires-auth'],
 	aliases: ['ls'],
 	requires: { auth: true, apiClient: true },
+	idempotent: true,
 	schema: {
-		options: z.object({
-			format: z
-				.enum(['json', 'table'])
-				.optional()
-				.describe('the output format: json, table (default)'),
-		}),
+		response: ProjectListResponseSchema,
 	},
+	examples: [
+		getCommand('project list'),
+		getCommand('--json project list'),
+		getCommand('project ls'),
+	],
 
 	async handler(ctx) {
-		const { apiClient, opts } = ctx;
+		const { apiClient, options } = ctx;
 
 		const projects = await tui.spinner({
 			message: 'Fetching projects',
@@ -35,10 +47,12 @@ export const listSubcommand = createSubcommand({
 			});
 		}
 
-		if (opts?.format === 'json') {
+		if (options.json) {
 			console.log(JSON.stringify(projects, null, 2));
 		} else {
-			console.table(projects, ['id', 'name', 'orgName']);
+			tui.table(projects, ['id', 'name', 'orgName']);
 		}
+
+		return projects ?? [];
 	},
 });

package/src/cmd/project/show.ts

@@ -2,26 +2,37 @@ import { z } from 'zod';
 import { createSubcommand } from '../../types';
 import * as tui from '../../tui';
 import { projectGet } from '@agentuity/server';
+import { getCommand } from '../../command-prefix';
+
+const ProjectShowResponseSchema = z.object({
+	id: z.string().describe('Project ID'),
+	orgId: z.string().describe('Organization ID'),
+	name: z.string().optional().describe('Project name'),
+	secrets: z.record(z.string(), z.string()).optional().describe('Project secrets (masked)'),
+	env: z.record(z.string(), z.string()).optional().describe('Environment variables'),
+});
 
 export const showSubcommand = createSubcommand({
 	name: 'show',
 	aliases: ['get'],
 	description: 'Show project detail',
+	tags: ['read-only', 'fast', 'requires-auth', 'requires-project'],
 	requires: { auth: true, apiClient: true },
+	examples: [
+		getCommand('project show proj_abc123def456'),
+		getCommand('--json project show proj_abc123def456'),
+		getCommand('project get proj_abc123def456'),
+	],
 	schema: {
 		args: z.object({
 			id: z.string().describe('the project id'),
 		}),
-		options: z.object({
-			format: z
-				.enum(['json', 'table'])
-				.optional()
-				.describe('the output format: json, table (default)'),
-		}),
+		response: ProjectShowResponseSchema,
 	},
+	idempotent: true,
 
 	async handler(ctx) {
-		const { opts, args, apiClient } = ctx;
+		const { args, apiClient, options } = ctx;
 
 		const project = await tui.spinner('Fetching project', () => {
 			return projectGet(apiClient, { id: args.id, mask: true });
@@ -31,10 +42,18 @@ export const showSubcommand = createSubcommand({
 			tui.fatal('Project not found');
 		}
 
-		if (opts?.format === 'json') {
+		if (options.json) {
 			console.log(JSON.stringify(project, null, 2));
 		} else {
-			console.table([project], ['id', 'orgId']);
+			tui.table([project], ['id', 'orgId']);
 		}
+
+		return {
+			id: project.id,
+			orgId: project.orgId,
+			name: undefined,
+			secrets: project.secrets,
+			env: project.env,
+		};
 	},
 });

package/src/cmd/project/template-flow.ts

@@ -19,7 +19,8 @@ import * as tui from '../../tui';
 import { playSound } from '../../sound';
 import { fetchTemplates, type TemplateInfo } from './templates';
 import { downloadTemplate, setupProject } from './download';
-import type { AuthData, Config } from '../../types';
+import { type AuthData, type Config } from '../../types';
+import { ErrorCode } from '../../errors';
 import type { APIClient } from '../../api';
 import { createProjectConfig } from '../../config';
 import {
@@ -78,7 +79,7 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<void> {
 	});
 
 	if (templates.length === 0) {
-		logger.fatal('No templates available');
+		logger.fatal('No templates available', ErrorCode.RESOURCE_NOT_FOUND);
 	}
 
 	// Get project name
@@ -154,13 +155,16 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<void> {
 			// Extra safety: refuse to delete root or home directories
 			const home = homedir();
 			if (dest === '/' || dest === home) {
-				logger.fatal(`Refusing to delete protected path: ${dest}`);
+				logger.fatal(`Refusing to delete protected path: ${dest}`, ErrorCode.VALIDATION_FAILED);
 				return;
 			}
 			rmSync(dest, { recursive: true, force: true });
 			tui.success(`Deleted ${dest}`);
 		} else {
-			logger.fatal(`Directory ${dest} already exists and is not empty.`, true);
+			logger.fatal(
+				`Directory ${dest} already exists and is not empty.`,
+				ErrorCode.RESOURCE_ALREADY_EXISTS
+			);
 		}
 	}
 
@@ -169,7 +173,7 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<void> {
 	if (initialTemplate) {
 		const found = templates.find((t) => t.id === initialTemplate);
 		if (!found) {
-			logger.fatal(`Template "${initialTemplate}" not found`);
+			logger.fatal(`Template "${initialTemplate}" not found`, ErrorCode.RESOURCE_NOT_FOUND);
 			return;
 		}
 		selectedTemplate = found;
@@ -187,7 +191,7 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<void> {
 		});
 		const found = templates.find((t) => t.id === response.template);
 		if (!found) {
-			logger.fatal('Template selection failed');
+			logger.fatal('Template selection failed', ErrorCode.USER_CANCELLED);
 			return;
 		}
 		selectedTemplate = found;

package/src/cmd/prompt/index.ts

@@ -0,0 +1,12 @@
+import type { CommandDefinition } from '../../types';
+import { createCommand } from '../../types';
+import { llmSubcommand } from './llm';
+
+export const promptCommand: CommandDefinition = createCommand({
+	name: 'prompt',
+	description: 'Generate prompts for LLMs and agents',
+	tags: ['read-only', 'fast'],
+	subcommands: [llmSubcommand],
+});
+
+export default promptCommand;