@agentuity/cli 0.0.48 → 0.0.50

package/src/cmd/env/import.ts

@@ -13,14 +13,32 @@ import {
 } from '../../env-util';
 import { getCommand } from '../../command-prefix';
 
+const EnvImportResponseSchema = z.object({
+	success: z.boolean().describe('Whether import succeeded'),
+	imported: z.number().describe('Number of items imported'),
+	skipped: z.number().describe('Number of items skipped'),
+	path: z.string().describe('Local file path where variables were saved'),
+	file: z.string().describe('Source file path'),
+});
+
 export const importSubcommand = createSubcommand({
 	name: 'import',
 	description: 'Import environment variables from a file to cloud and local .env.production',
+	tags: [
+		'mutating',
+		'creates-resource',
+		'slow',
+		'api-intensive',
+		'requires-auth',
+		'requires-project',
+	],
+	idempotent: false,
 	requires: { auth: true, project: true, apiClient: true },
 	schema: {
 		args: z.object({
 			file: z.string().describe('path to the .env file to import'),
 		}),
+		response: EnvImportResponseSchema,
 	},
 
 	async handler(ctx) {
@@ -31,7 +49,13 @@ export const importSubcommand = createSubcommand({
 
 		if (Object.keys(importedEnv).length === 0) {
 			tui.warning(`No environment variables found in ${args.file}`);
-			return;
+			return {
+				success: false,
+				imported: 0,
+				skipped: 0,
+				path: '',
+				file: args.file,
+			};
 		}
 
 		// Filter out AGENTUITY_ prefixed keys
@@ -39,7 +63,13 @@ export const importSubcommand = createSubcommand({
 
 		if (Object.keys(filteredEnv).length === 0) {
 			tui.warning('No valid environment variables to import (all were AGENTUITY_ prefixed)');
-			return;
+			return {
+				success: false,
+				imported: 0,
+				skipped: Object.keys(importedEnv).length,
+				path: '',
+				file: args.file,
+			};
 		}
 
 		// Check for potential secrets in the imported variables
@@ -69,7 +99,13 @@ export const importSubcommand = createSubcommand({
 				tui.info(
 					`Cancelled. Use "${getCommand('secret import')}" to store these as secrets instead.`
 				);
-				return;
+				return {
+					success: false,
+					imported: 0,
+					skipped: Object.keys(filteredEnv).length,
+					path: '',
+					file: args.file,
+				};
 			}
 		}
 
@@ -98,5 +134,13 @@ export const importSubcommand = createSubcommand({
 		tui.success(
 			`Imported ${count} environment variable${count !== 1 ? 's' : ''} from ${args.file} to cloud and ${localEnvPath}`
 		);
+
+		return {
+			success: true,
+			imported: count,
+			skipped: Object.keys(importedEnv).length - count,
+			path: localEnvPath,
+			file: args.file,
+		};
 	},
 });

package/src/cmd/env/index.ts

@@ -10,6 +10,7 @@ import { listSubcommand } from './list';
 export const command = createCommand({
 	name: 'env',
 	description: 'Manage environment variables for your project',
+	tags: ['fast', 'requires-auth', 'requires-project'],
 	subcommands: [
 		listSubcommand,
 		pullSubcommand,

package/src/cmd/env/list.ts

@@ -3,12 +3,21 @@ import { createSubcommand } from '../../types';
 import * as tui from '../../tui';
 import { projectGet } from '@agentuity/server';
 import { maskSecret } from '../../env-util';
+import { getCommand } from '../../command-prefix';
+
+const EnvListResponseSchema = z.record(
+	z.string(),
+	z.string().describe('Environment variable value')
+);
 
 export const listSubcommand = createSubcommand({
 	name: 'list',
 	aliases: ['ls'],
 	description: 'List all environment variables',
+	tags: ['read-only', 'fast', 'requires-auth', 'requires-project'],
+	examples: [getCommand('env list'), getCommand('env list --mask')],
 	requires: { auth: true, project: true, apiClient: true },
+	idempotent: true,
 	schema: {
 		options: z.object({
 			mask: z
@@ -16,6 +25,7 @@ export const listSubcommand = createSubcommand({
 				.default(false)
 				.describe('mask the values in output (default: false for env vars)'),
 		}),
+		response: EnvListResponseSchema,
 	},
 
 	async handler(ctx) {
@@ -30,7 +40,7 @@ export const listSubcommand = createSubcommand({
 
 		if (Object.keys(env).length === 0) {
 			tui.info('No environment variables found');
-			return;
+			return {};
 		}
 
 		// Display the variables
@@ -52,5 +62,7 @@ export const listSubcommand = createSubcommand({
 				console.log(`${key}=${displayValue}`);
 			}
 		}
+
+		return env;
 	},
 });

package/src/cmd/env/pull.ts

@@ -10,15 +10,28 @@ import {
 	writeEnvFile,
 	mergeEnvVars,
 } from '../../env-util';
+import { getCommand } from '../../command-prefix';
+
+const EnvPullResponseSchema = z.object({
+	success: z.boolean().describe('Whether pull succeeded'),
+	pulled: z.number().describe('Number of items pulled'),
+	path: z.string().describe('Local file path where variables were saved'),
+	force: z.boolean().describe('Whether force mode was used'),
+});
 
 export const pullSubcommand = createSubcommand({
 	name: 'pull',
 	description: 'Pull environment variables from cloud to local .env.production file',
+	tags: ['slow', 'requires-auth', 'requires-project'],
+	idempotent: true,
+	examples: [getCommand('env pull'), getCommand('env pull --force')],
 	requires: { auth: true, project: true, apiClient: true },
+	prerequisites: ['cloud deploy'],
 	schema: {
 		options: z.object({
 			force: z.boolean().default(false).describe('overwrite local values with cloud values'),
 		}),
+		response: EnvPullResponseSchema,
 	},
 
 	async handler(ctx) {
@@ -76,5 +89,12 @@ export const pullSubcommand = createSubcommand({
 		tui.success(
 			`Pulled ${count} environment variable${count !== 1 ? 's' : ''} to ${targetEnvPath}`
 		);
+
+		return {
+			success: true,
+			pulled: count,
+			path: targetEnvPath,
+			force: opts?.force ?? false,
+		};
 	},
 });

package/src/cmd/env/push.ts

@@ -1,12 +1,34 @@
+import { z } from 'zod';
 import { createSubcommand } from '../../types';
 import * as tui from '../../tui';
 import { projectEnvUpdate } from '@agentuity/server';
 import { findExistingEnvFile, readEnvFile, filterAgentuitySdkKeys } from '../../env-util';
+import { getCommand } from '../../command-prefix';
+
+const EnvPushResponseSchema = z.object({
+	success: z.boolean().describe('Whether push succeeded'),
+	pushed: z.number().describe('Number of items pushed'),
+	source: z.string().describe('Source file path'),
+});
 
 export const pushSubcommand = createSubcommand({
 	name: 'push',
 	description: 'Push environment variables from local .env.production file to cloud',
+	tags: [
+		'mutating',
+		'updates-resource',
+		'slow',
+		'api-intensive',
+		'requires-auth',
+		'requires-project',
+	],
+	idempotent: true,
+	examples: [getCommand('env push')],
 	requires: { auth: true, project: true, apiClient: true },
+	prerequisites: ['env set'],
+	schema: {
+		response: EnvPushResponseSchema,
+	},
 
 	async handler(ctx) {
 		const { apiClient, project, projectDir } = ctx;
@@ -20,7 +42,11 @@ export const pushSubcommand = createSubcommand({
 
 		if (Object.keys(filteredEnv).length === 0) {
 			tui.warning('No environment variables to push');
-			return;
+			return {
+				success: false,
+				pushed: 0,
+				source: envFilePath,
+			};
 		}
 
 		// Push to cloud
@@ -33,5 +59,11 @@ export const pushSubcommand = createSubcommand({
 
 		const count = Object.keys(filteredEnv).length;
 		tui.success(`Pushed ${count} environment variable${count !== 1 ? 's' : ''} to cloud`);
+
+		return {
+			success: true,
+			pushed: count,
+			source: envFilePath,
+		};
 	},
 });

package/src/cmd/env/set.ts

@@ -11,15 +11,29 @@ import {
 } from '../../env-util';
 import { getCommand } from '../../command-prefix';
 
+const EnvSetResponseSchema = z.object({
+	success: z.boolean().describe('Whether the operation succeeded'),
+	key: z.string().describe('Environment variable key'),
+	path: z.string().describe('Local file path where env var was saved'),
+});
+
 export const setSubcommand = createSubcommand({
 	name: 'set',
 	description: 'Set an environment variable',
+	tags: ['mutating', 'updates-resource', 'slow', 'requires-auth', 'requires-project'],
+	idempotent: true,
 	requires: { auth: true, project: true, apiClient: true },
+	examples: [
+		getCommand('env set NODE_ENV production'),
+		getCommand('env set PORT 3000'),
+		getCommand('env set LOG_LEVEL debug'),
+	],
 	schema: {
 		args: z.object({
 			key: z.string().describe('the environment variable key'),
 			value: z.string().describe('the environment variable value'),
 		}),
+		response: EnvSetResponseSchema,
 	},
 
 	async handler(ctx) {
@@ -45,7 +59,11 @@ export const setSubcommand = createSubcommand({
 				tui.info(
 					`Cancelled. Use "${getCommand('secret set')}" to store this as a secret instead.`
 				);
-				return;
+				return {
+					success: false,
+					key: args.key,
+					path: '',
+				};
 			}
 		}
 
@@ -67,5 +85,11 @@ export const setSubcommand = createSubcommand({
 		await writeEnvFile(envFilePath, filteredEnv);
 
 		tui.success(`Environment variable '${args.key}' set successfully (cloud + ${envFilePath})`);
+
+		return {
+			success: true,
+			key: args.key,
+			path: envFilePath,
+		};
 	},
 });

package/src/cmd/index.ts

@@ -22,7 +22,8 @@ export async function discoverCommands(): Promise<CommandDefinition[]> {
 					if (cmd.subcommands) {
 						for (const subcommand of cmd.subcommands) {
 							if (subcommand.toplevel) {
-								const alias: CommandDefinition = {
+								// eslint-disable-next-line @typescript-eslint/no-explicit-any
+								const alias: any = {
 									name: subcommand.name,
 									description: subcommand.description,
 									aliases: subcommand.aliases,
@@ -31,8 +32,14 @@ export async function discoverCommands(): Promise<CommandDefinition[]> {
 									optional: subcommand.optional,
 									schema: subcommand.schema,
 									handler: subcommand.handler,
+									// eslint-disable-next-line @typescript-eslint/no-explicit-any
+									idempotent: (subcommand as any).idempotent,
+									// eslint-disable-next-line @typescript-eslint/no-explicit-any
+									prerequisites: (subcommand as any).prerequisites,
+									// eslint-disable-next-line @typescript-eslint/no-explicit-any
+									tags: (subcommand as any).tags,
 								};
-								commands.push(alias);
+								commands.push(alias as CommandDefinition);
 							}
 						}
 					}

package/src/cmd/kv/create-namespace.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import { createCommand } from '../../types';
+import * as tui from '../../tui';
+import { createStorageAdapter } from './util';
+import { getCommand } from '../../command-prefix';
+
+export const createNamespaceSubcommand = createCommand({
+	name: 'create-namespace',
+	aliases: ['create'],
+	description: 'Create a new keyvalue namespace',
+	tags: ['mutating', 'creates-resource', 'slow', 'requires-auth'],
+	idempotent: false,
+	requires: { auth: true, project: true },
+	examples: [
+		`${getCommand('kv create-namespace production')} - Create production namespace`,
+		`${getCommand('kv create staging')} - Create staging namespace (using alias)`,
+		`${getCommand('kv create cache')} - Create cache namespace`,
+	],
+	schema: {
+		args: z.object({
+			name: z.string().min(1).max(64).describe('the namespace name'),
+		}),
+		response: z.object({
+			success: z.boolean().describe('Whether the operation succeeded'),
+			namespace: z.string().describe('Namespace name'),
+			message: z.string().optional().describe('Success message'),
+		}),
+	},
+
+	async handler(ctx) {
+		const { args } = ctx;
+		const kv = await createStorageAdapter(ctx);
+
+		await kv.createNamespace(args.name);
+		tui.success(`Namespace ${tui.bold(args.name)} created`);
+
+		return {
+			success: true,
+			namespace: args.name,
+			message: `Namespace ${args.name} created`,
+		};
+	},
+});
+
+export default createNamespaceSubcommand;

package/src/cmd/kv/delete-namespace.ts

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+import { createCommand } from '../../types';
+import { ErrorCode } from '../../errors';
+import * as tui from '../../tui';
+import { createStorageAdapter } from './util';
+import { getCommand } from '../../command-prefix';
+
+export const deleteNamespaceSubcommand = createCommand({
+	name: 'delete-namespace',
+	aliases: ['rm-namespace'],
+	description: 'Delete a keyvalue namespace and all its keys',
+	tags: ['destructive', 'deletes-resource', 'slow', 'requires-auth', 'requires-project'],
+	idempotent: true,
+	requires: { auth: true, project: true },
+	examples: [
+		`${getCommand('kv delete-namespace staging')} - Delete staging namespace (interactive)`,
+		`${getCommand('kv rm-namespace cache --confirm')} - Delete cache without confirmation`,
+		`${getCommand('kv delete-namespace production --confirm')} - Force delete production`,
+	],
+	schema: {
+		args: z.object({
+			name: z.string().min(1).max(64).describe('the namespace name'),
+			confirm: z
+				.boolean()
+				.optional()
+				.default(false)
+				.describe('if true will not prompt for confirmation'),
+		}),
+		response: z.object({
+			success: z.boolean().describe('Whether the deletion succeeded'),
+			namespace: z.string().describe('Deleted namespace name'),
+			message: z.string().optional().describe('Confirmation message'),
+		}),
+	},
+
+	async handler(ctx) {
+		const { args } = ctx;
+		const kv = await createStorageAdapter(ctx);
+
+		if (!args.confirm) {
+			if (!process.stdin.isTTY) {
+				tui.fatal(
+					'No TTY and --confirm is not set. Refusing to delete',
+					ErrorCode.VALIDATION_FAILED
+				);
+			}
+			tui.warning(`This will delete namespace ${tui.bold(args.name)} and ALL its keys.`);
+			const confirm = await new Promise<boolean>((resolve) => {
+				process.stdout.write('Are you sure? (yes/no): ');
+				process.stdin.once('data', (data) => {
+					const answer = data.toString().trim().toLowerCase();
+					resolve(answer === 'yes' || answer === 'y');
+				});
+			});
+
+			if (!confirm) {
+				tui.info('Cancelled');
+				return { success: false, namespace: args.name, message: 'Cancelled' };
+			}
+		}
+
+		await kv.deleteNamespace(args.name);
+		tui.success(`Namespace ${tui.bold(args.name)} deleted`);
+
+		return {
+			success: true,
+			namespace: args.name,
+			message: `Namespace ${args.name} deleted`,
+		};
+	},
+});
+
+export default deleteNamespaceSubcommand;

package/src/cmd/kv/delete.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+import { createCommand } from '../../types';
+import * as tui from '../../tui';
+import { createStorageAdapter } from './util';
+import { getCommand } from '../../command-prefix';
+
+const KVDeleteResponseSchema = z.object({
+	success: z.boolean().describe('Whether the operation succeeded'),
+	namespace: z.string().describe('Namespace name'),
+	key: z.string().describe('Key name'),
+	durationMs: z.number().describe('Operation duration in milliseconds'),
+});
+
+export const deleteSubcommand = createCommand({
+	name: 'delete',
+	aliases: ['del', 'rm', 'remove'],
+	description: 'Delete a key from the keyvalue storage',
+	tags: ['destructive', 'deletes-resource', 'slow', 'requires-auth'],
+	idempotent: true,
+	requires: { auth: true, project: true },
+	examples: [
+		`${getCommand('kv delete production user:123')} - Delete user data`,
+		`${getCommand('kv delete cache session:abc')} - Delete cached session`,
+		`${getCommand('kv rm staging cache:homepage')} - Delete homepage cache (using alias)`,
+	],
+	schema: {
+		args: z.object({
+			namespace: z.string().min(1).describe('the namespace name'),
+			key: z.string().min(1).describe('the key name'),
+		}),
+		response: KVDeleteResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { args } = ctx;
+		const started = Date.now();
+		const storage = await createStorageAdapter(ctx);
+		await storage.delete(args.namespace, args.key);
+		const durationMs = Date.now() - started;
+		tui.success(`deleted in ${durationMs.toFixed(1)}ms`);
+
+		return {
+			success: true,
+			namespace: args.namespace,
+			key: args.key,
+			durationMs,
+		};
+	},
+});
+
+export default deleteSubcommand;

package/src/cmd/kv/get.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+import { createCommand } from '../../types';
+import * as tui from '../../tui';
+import { tryParseJSON } from '../../json';
+import { createStorageAdapter } from './util';
+import { getCommand } from '../../command-prefix';
+
+const KVGetResponseSchema = z.object({
+	exists: z.boolean().describe('Whether the key exists'),
+	data: z.union([z.string(), z.any()]).optional().describe('Value data (string or binary)'),
+	contentType: z.string().optional().describe('Content type'),
+});
+
+export const getSubcommand = createCommand({
+	name: 'get',
+	description: 'Get a value from the keyvalue storage',
+	tags: ['read-only', 'fast', 'requires-auth'],
+	requires: { auth: true, project: true },
+	examples: [
+		`${getCommand('kv get production user:123')} - Get user data`,
+		`${getCommand('kv get cache session:abc')} - Get cached session`,
+		`${getCommand('kv get staging cache:homepage')} - Get homepage cache`,
+	],
+	schema: {
+		args: z.object({
+			namespace: z.string().min(1).describe('the namespace name'),
+			key: z.string().min(1).describe('the key name'),
+		}),
+		response: KVGetResponseSchema,
+	},
+	idempotent: true,
+
+	async handler(ctx) {
+		const { args } = ctx;
+		const storage = await createStorageAdapter(ctx);
+		const started = Date.now();
+		const res = await storage.get(args.namespace, args.key);
+		if (res.exists) {
+			if (res.data) {
+				if (res.contentType?.includes('json')) {
+					const val = tryParseJSON(res.data as unknown as string);
+					tui.json(val);
+				} else if (res.contentType?.includes('text')) {
+					console.log(String(res.data));
+				} else {
+					const b = res.data as ArrayBuffer;
+					tui.info(`Read ${b.byteLength} bytes (${res.contentType})`);
+				}
+				tui.success(`retrieved in ${(Date.now() - started).toFixed(1)}ms (${res.contentType})`);
+			} else {
+				tui.warning(`${args.key} returned empty data for ${args.namespace}`);
+			}
+		} else {
+			tui.warning(`${args.key} does not exist in ${args.namespace}`);
+		}
+
+		return {
+			exists: res.exists,
+			data: res.data,
+			contentType: res.exists ? res.contentType : undefined,
+		};
+	},
+});
+
+export default getSubcommand;

package/src/cmd/kv/index.ts

@@ -0,0 +1,31 @@
+import { createCommand } from '../../types';
+import { createNamespaceSubcommand } from './create-namespace';
+import { deleteSubcommand } from './delete';
+import { deleteNamespaceSubcommand } from './delete-namespace';
+import { getSubcommand } from './get';
+import { keysSubcommand } from './keys';
+import { listNamespacesSubcommand } from './list-namespaces';
+import { replSubcommand } from './repl';
+import { searchSubcommand } from './search';
+import { setSubcommand } from './set';
+import { statsSubcommand } from './stats';
+
+export const command = createCommand({
+	name: 'keyvalue',
+	aliases: ['kv'],
+	description: 'Manage keyvalue storage for your projects',
+	tags: ['read-only', 'fast', 'requires-auth'],
+	subcommands: [
+		replSubcommand,
+		getSubcommand,
+		setSubcommand,
+		deleteSubcommand,
+		statsSubcommand,
+		searchSubcommand,
+		keysSubcommand,
+		listNamespacesSubcommand,
+		createNamespaceSubcommand,
+		deleteNamespaceSubcommand,
+	],
+	requires: { auth: true, project: true },
+});

package/src/cmd/kv/keys.ts

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+import { createCommand } from '../../types';
+import * as tui from '../../tui';
+import { createStorageAdapter } from './util';
+import { getCommand } from '../../command-prefix';
+
+const KVKeysResponseSchema = z.object({
+	namespace: z.string().describe('Namespace name'),
+	keys: z.array(z.string()).describe('List of keys in the namespace'),
+});
+
+export const keysSubcommand = createCommand({
+	name: 'keys',
+	aliases: ['ls', 'list'],
+	description: 'List all keys in a keyvalue namespace',
+	tags: ['read-only', 'slow', 'requires-auth'],
+	requires: { auth: true, project: true },
+	idempotent: true,
+	examples: [
+		`${getCommand('kv keys production')} - List all keys in production`,
+		`${getCommand('kv ls cache')} - List all cached keys (using alias)`,
+		`${getCommand('kv list staging')} - List all staging keys`,
+	],
+	schema: {
+		args: z.object({
+			name: z.string().min(1).describe('the namespace name'),
+		}),
+		response: KVKeysResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { args } = ctx;
+		const kv = await createStorageAdapter(ctx);
+
+		const keys = await kv.getKeys(args.name);
+
+		if (keys.length === 0) {
+			tui.info(`No keys found in namespace ${tui.bold(args.name)}`);
+			return {
+				namespace: args.name,
+				keys: [],
+			};
+		}
+
+		tui.info(`Found ${keys.length} key(s) in ${tui.bold(args.name)}:`);
+		for (const key of keys) {
+			tui.info(`  ${key}`);
+		}
+
+		return {
+			namespace: args.name,
+			keys,
+		};
+	},
+});
+
+export default keysSubcommand;