@agentuity/cli 0.0.48 → 0.0.49

package/src/cmd/cloud/scp/download.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { createSubcommand } from '../../../types';
 import * as tui from '../../../tui';
 import { getIONHost } from '../../../config';
+import { getCommand } from '../../../command-prefix';
 
 const args = z.object({
 	source: z.string().describe('the source file'),
@@ -16,9 +17,27 @@ export const downloadCommand = createSubcommand({
 	name: 'download',
 	aliases: ['get'],
 	description: 'Download a file using security copy',
+	tags: ['read-only', 'slow', 'requires-auth', 'requires-deployment'],
+	idempotent: true,
+	examples: [
+		`${getCommand('cloud scp download')} /var/log/app.log          # Download to current directory`,
+		`${getCommand('cloud scp download')} /var/log/app.log ./logs/  # Download to specific path`,
+		`${getCommand('cloud scp download')} /app/config.json --identifier=proj_abc123xyz`,
+		`${getCommand('cloud scp download')} ~/logs/*.log ./logs/      # Download multiple files`,
+	],
 	requires: { apiClient: true, auth: true },
 	optional: { project: true },
-	schema: { args, options },
+	prerequisites: ['cloud deploy'],
+	schema: {
+		args,
+		options,
+		response: z.object({
+			success: z.boolean().describe('Whether download succeeded'),
+			source: z.string().describe('Remote source path'),
+			destination: z.string().describe('Local destination path'),
+			identifier: z.string().describe('Project or deployment identifier'),
+		}),
+	},
 
 	async handler(ctx) {
 		const { apiClient, args, opts, project, projectDir, config } = ctx;
@@ -49,6 +68,13 @@ export const downloadCommand = createSubcommand({
 				);
 				process.exit(spawn.exitCode ?? 1);
 			}
+
+			return {
+				success: true,
+				source: args.source,
+				destination,
+				identifier,
+			};
 		} catch (error) {
 			tui.error(
 				`SCP download error: ${error instanceof Error ? error.message : 'Unknown error'}`

package/src/cmd/cloud/scp/index.ts

@@ -1,9 +1,10 @@
-import type { SubcommandDefinition } from '../../../types';
+import { createCommand } from '../../../types';
 import { downloadCommand } from './download';
 import { uploadCommand } from './upload';
 
-export const scpSubcommand: SubcommandDefinition = {
+export const scpSubcommand = createCommand({
 	name: 'scp',
 	description: 'Secure Copy commands',
+	tags: ['slow', 'requires-auth', 'requires-deployment'],
 	subcommands: [downloadCommand, uploadCommand],
-};
+});

package/src/cmd/cloud/scp/upload.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { createSubcommand } from '../../../types';
 import * as tui from '../../../tui';
 import { getIONHost } from '../../../config';
+import { getCommand } from '../../../command-prefix';
 
 const args = z.object({
 	source: z.string().describe('the source file'),
@@ -19,9 +20,27 @@ export const uploadCommand = createSubcommand({
 	name: 'upload',
 	aliases: ['cp', 'put'],
 	description: 'Upload a file using security copy',
+	tags: ['mutating', 'updates-resource', 'slow', 'requires-auth', 'requires-deployment'],
+	idempotent: false,
+	examples: [
+		`${getCommand('cloud scp upload')} ./config.json                # Upload to remote home directory`,
+		`${getCommand('cloud scp upload')} ./config.json /app/config.json # Upload to specific path`,
+		`${getCommand('cloud scp upload')} ./config.json --identifier=proj_abc123xyz`,
+		`${getCommand('cloud scp upload')} ./logs/*.log ~/logs/        # Upload multiple files`,
+	],
 	requires: { apiClient: true, auth: true },
-	schema: { args, options },
+	schema: {
+		args,
+		options,
+		response: z.object({
+			success: z.boolean().describe('Whether upload succeeded'),
+			source: z.string().describe('Local source path'),
+			destination: z.string().describe('Remote destination path'),
+			identifier: z.string().describe('Project or deployment identifier'),
+		}),
+	},
 	optional: { project: true },
+	prerequisites: ['cloud deploy'],
 
 	async handler(ctx) {
 		const { apiClient, args, opts, project, projectDir, config } = ctx;
@@ -52,6 +71,13 @@ export const uploadCommand = createSubcommand({
 				);
 				process.exit(spawn.exitCode ?? 1);
 			}
+
+			return {
+				success: true,
+				source: args.source,
+				destination,
+				identifier,
+			};
 		} catch (error) {
 			tui.error(`SCP upload error: ${error instanceof Error ? error.message : 'Unknown error'}`);
 			process.exit(1);

package/src/cmd/cloud/ssh.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { createSubcommand } from '../../types';
 import * as tui from '../../tui';
 import { getIONHost } from '../../config';
+import { getCommand } from '../../command-prefix';
 
 const args = z.object({
 	identifier: z.string().optional().describe('The project or deployment id to use'),
@@ -15,9 +16,20 @@ const options = z.object({
 export const sshSubcommand = createSubcommand({
 	name: 'ssh',
 	description: 'SSH into a cloud project',
+	tags: ['read-only', 'slow', 'requires-auth', 'requires-deployment'],
+	idempotent: true,
+	examples: [
+		`${getCommand('cloud ssh')}                          # SSH into current project`,
+		`${getCommand('cloud ssh')} proj_abc123xyz           # SSH into specific project`,
+		`${getCommand('cloud ssh')} deploy_abc123xyz         # SSH into specific deployment`,
+		`${getCommand('cloud ssh')} 'ps aux'                 # Run command and exit`,
+		`${getCommand('cloud ssh')} proj_abc123xyz 'tail -f /var/log/app.log'`,
+		`${getCommand('cloud ssh')} --show                   # Show SSH command without executing`,
+	],
 	toplevel: true,
 	requires: { auth: true, apiClient: true },
 	optional: { project: true },
+	prerequisites: ['cloud deploy'],
 	schema: { args, options },
 
 	async handler(ctx) {

package/src/cmd/dev/index.ts

@@ -5,22 +5,26 @@ import { resolve, join } from 'node:path';
 import { bundle } from '../bundle/bundler';
 import { getBuildMetadata } from '../bundle/plugin';
 import { existsSync, type FSWatcher, watch, statSync, readdirSync } from 'node:fs';
-import {
-	getDefaultConfigDir,
-	loadDevelopmentProjectSDKKey,
-	saveProjectDir,
-	saveConfig,
-} from '../../config';
+import { getDefaultConfigDir, loadProjectSDKKey, saveProjectDir, saveConfig } from '../../config';
 import { type Config, createCommand } from '../../types';
 import * as tui from '../../tui';
 import { createAgentTemplates, createAPITemplates } from './templates';
 import { generateEndpoint, type DevmodeResponse } from './api';
 import { APIClient, getAPIBaseURL } from '../../api';
 import { download } from './download';
+import { getCommand } from '../../command-prefix';
 
 export const command = createCommand({
 	name: 'dev',
 	description: 'Build and run the development server',
+	tags: ['mutating', 'slow', 'requires-project'],
+	idempotent: true,
+	examples: [
+		getCommand('dev'),
+		getCommand('dev --port 8080'),
+		getCommand('dev --local'),
+		getCommand('dev --no-public'),
+	],
 	schema: {
 		options: z.object({
 			local: z.boolean().optional().describe('Turn on local services (instead of cloud)'),
@@ -200,7 +204,7 @@ export const command = createCommand({
 		let gravityClient: Bun.Subprocess | undefined;
 
 		if (gravityBin && devmode && project) {
-			const sdkKey = await loadDevelopmentProjectSDKKey(rootDir);
+			const sdkKey = await loadProjectSDKKey(rootDir);
 			if (!sdkKey) {
 				tui.warning(`Couldn't find the AGENTUITY_SDK_KEY in ${rootDir} .env file`);
 			} else {

package/src/cmd/dev/templates.ts

@@ -8,7 +8,7 @@ import { z } from 'zod';
 const agent = createAgent({
 	metadata: {
         name: '${name}',
-        description: 'Add my agent description here',
+        description: 'Add your agent description here',
     },
 	schema: {
 		input: z.string(),

package/src/cmd/env/delete.ts

@@ -8,16 +8,27 @@ import {
 	writeEnvFile,
 	filterAgentuitySdkKeys,
 } from '../../env-util';
+import { getCommand } from '../../command-prefix';
+
+const EnvDeleteResponseSchema = z.object({
+	success: z.boolean().describe('Whether the operation succeeded'),
+	key: z.string().describe('Environment variable key that was deleted'),
+	path: z.string().describe('Local file path where env var was removed'),
+});
 
 export const deleteSubcommand = createSubcommand({
 	name: 'delete',
 	aliases: ['del', 'remove', 'rm'],
 	description: 'Delete an environment variable',
+	tags: ['destructive', 'deletes-resource', 'slow', 'requires-auth', 'requires-project'],
+	idempotent: true,
+	examples: [getCommand('env delete OLD_FEATURE_FLAG'), getCommand('env rm PORT')],
 	requires: { auth: true, project: true, apiClient: true },
 	schema: {
 		args: z.object({
 			key: z.string().describe('the environment variable key to delete'),
 		}),
+		response: EnvDeleteResponseSchema,
 	},
 
 	async handler(ctx) {
@@ -43,5 +54,11 @@ export const deleteSubcommand = createSubcommand({
 		tui.success(
 			`Environment variable '${args.key}' deleted successfully (cloud + ${envFilePath})`
 		);
+
+		return {
+			success: true,
+			key: args.key,
+			path: envFilePath,
+		};
 	},
 });

package/src/cmd/env/get.ts

@@ -3,10 +3,19 @@ import { createSubcommand } from '../../types';
 import * as tui from '../../tui';
 import { projectGet } from '@agentuity/server';
 import { maskSecret } from '../../env-util';
+import { getCommand } from '../../command-prefix';
+import { ErrorCode } from '../../errors';
+
+const EnvGetResponseSchema = z.object({
+	key: z.string().describe('Environment variable key name'),
+	value: z.string().describe('Environment variable value'),
+});
 
 export const getSubcommand = createSubcommand({
 	name: 'get',
 	description: 'Get an environment variable value',
+	tags: ['read-only', 'fast', 'requires-auth', 'requires-project'],
+	examples: [getCommand('env get NODE_ENV'), getCommand('env get LOG_LEVEL')],
 	requires: { auth: true, project: true, apiClient: true },
 	schema: {
 		args: z.object({
@@ -18,7 +27,9 @@ export const getSubcommand = createSubcommand({
 				.default(false)
 				.describe('mask the value in output (default: true in TTY, false otherwise)'),
 		}),
+		response: EnvGetResponseSchema,
 	},
+	idempotent: true,
 
 	async handler(ctx) {
 		const { args, opts, apiClient, project } = ctx;
@@ -32,7 +43,7 @@ export const getSubcommand = createSubcommand({
 		const value = projectData.env?.[args.key];
 
 		if (value === undefined) {
-			tui.fatal(`Environment variable '${args.key}' not found`);
+			tui.fatal(`Environment variable '${args.key}' not found`, ErrorCode.RESOURCE_NOT_FOUND);
 		}
 
 		// Display the value, masked if requested
@@ -49,5 +60,10 @@ export const getSubcommand = createSubcommand({
 				console.log(`${args.key}=${value}`);
 			}
 		}
+
+		return {
+			key: args.key,
+			value,
+		};
 	},
 });

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;