@agentuity/cli 0.0.59 → 0.0.61

package/src/cmd/cloud/storage/list.ts

@@ -0,0 +1,221 @@
+import { z } from 'zod';
+import { listResources } from '@agentuity/server';
+import { createSubcommand } from '../../../types';
+import * as tui from '../../../tui';
+import { getCatalystAPIClient } from '../../../config';
+import { getCommand } from '../../../command-prefix';
+import { ErrorCode } from '../../../errors';
+import { createS3Client } from './utils';
+
+const StorageListResponseSchema = z.object({
+	buckets: z
+		.array(
+			z.object({
+				bucket_name: z.string().describe('Storage bucket name'),
+				access_key: z.string().optional().describe('S3 access key'),
+				secret_key: z.string().optional().describe('S3 secret key'),
+				region: z.string().optional().describe('S3 region'),
+				endpoint: z.string().optional().describe('S3 endpoint URL'),
+			})
+		)
+		.optional()
+		.describe('List of storage resources'),
+	files: z
+		.array(
+			z.object({
+				key: z.string().describe('File key/path'),
+				size: z.number().describe('File size in bytes'),
+				lastModified: z.string().describe('Last modified timestamp'),
+			})
+		)
+		.optional()
+		.describe('List of files in bucket'),
+});
+
+export const listSubcommand = createSubcommand({
+	name: 'list',
+	aliases: ['ls'],
+	description: 'List storage resources or files in a bucket',
+	tags: ['read-only', 'fast', 'requires-auth'],
+	requires: { auth: true, org: true, region: true },
+	idempotent: true,
+	examples: [
+		{ command: getCommand('cloud storage list'), description: 'List items' },
+		{ command: getCommand('cloud storage list my-bucket'), description: 'List items' },
+		{
+			command: getCommand('cloud storage list my-bucket path/prefix'),
+			description: 'List items',
+		},
+		{
+			command: getCommand('--json cloud storage list'),
+			description: 'Show output in JSON format',
+		},
+		{ command: getCommand('cloud storage ls'), description: 'List items' },
+		{
+			command: getCommand('cloud storage list --show-credentials'),
+			description: 'Use show credentials option',
+		},
+	],
+	schema: {
+		args: z.object({
+			name: z.string().optional().describe('Bucket name to list files from'),
+			prefix: z.string().optional().describe('Path prefix to filter files'),
+		}),
+		options: z.object({
+			showCredentials: z
+				.boolean()
+				.optional()
+				.describe(
+					'Show credentials in plain text (default: masked in terminal, unmasked in JSON)'
+				),
+			nameOnly: z.boolean().optional().describe('Print the name only'),
+		}),
+		response: StorageListResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { logger, args, opts, options, orgId, region, config, auth } = ctx;
+
+		const catalystClient = getCatalystAPIClient(config, logger, auth);
+
+		const resources = await tui.spinner({
+			message: `Fetching storage for ${orgId} in ${region}`,
+			clearOnSuccess: true,
+			callback: async () => {
+				return listResources(catalystClient, orgId, region);
+			},
+		});
+
+		// If bucket name is provided, list files in the bucket
+		if (args.name) {
+			const bucket = resources.s3.find((s3) => s3.bucket_name === args.name);
+
+			if (!bucket) {
+				tui.fatal(`Storage bucket '${args.name}' not found`, ErrorCode.RESOURCE_NOT_FOUND);
+			}
+
+			if (!bucket.access_key || !bucket.secret_key || !bucket.endpoint) {
+				tui.fatal(
+					`Storage bucket '${args.name}' is missing credentials`,
+					ErrorCode.CONFIG_INVALID
+				);
+			}
+
+			const s3Client = createS3Client({
+				endpoint: bucket.endpoint,
+				access_key: bucket.access_key,
+				secret_key: bucket.secret_key,
+				region: bucket.region,
+			});
+
+			const result = await tui.spinner({
+				message: `Listing files in ${args.name}${args.prefix ? ` with prefix ${args.prefix}` : ''}`,
+				clearOnSuccess: true,
+				callback: async () => {
+					return s3Client.list(
+						args.prefix
+							? {
+									prefix: args.prefix,
+								}
+							: null
+					);
+				},
+			});
+
+			const objects = result.contents || [];
+
+			if (!options.json) {
+				if (objects.length === 0) {
+					tui.info('No files found');
+				} else {
+					if (opts.nameOnly) {
+						for (const obj of objects) {
+							console.log(obj.key);
+						}
+					} else {
+						tui.info(
+							tui.bold(
+								`Files in ${args.name}${args.prefix ? ` (prefix: ${args.prefix})` : ''}`
+							)
+						);
+						tui.newline();
+						for (const obj of objects) {
+							console.log(
+								`${obj.key}  ${tui.muted(`(${obj.size} bytes, ${obj.lastModified})`)}`
+							);
+						}
+					}
+				}
+			}
+
+			return {
+				files: objects.map((obj) => {
+					const lastModified = obj.lastModified;
+					let lastModifiedStr = '';
+					if (typeof lastModified === 'string') {
+						lastModifiedStr = lastModified;
+					} else if (
+						lastModified &&
+						typeof lastModified === 'object' &&
+						'toISOString' in lastModified
+					) {
+						lastModifiedStr = (lastModified as Date).toISOString();
+					}
+					return {
+						key: obj.key,
+						size: obj.size ?? 0,
+						lastModified: lastModifiedStr,
+					};
+				}),
+			};
+		}
+
+		// Otherwise, list buckets
+		// Mask credentials in terminal output by default, unless --show-credentials is passed
+		const shouldShowCredentials = opts.showCredentials === true;
+		const shouldMask = !options.json && !shouldShowCredentials;
+
+		if (!options.json) {
+			if (resources.s3.length === 0) {
+				tui.info('No storage buckets found');
+			} else {
+				if (!opts.nameOnly) {
+					tui.info(tui.bold('Storage'));
+					tui.newline();
+				}
+				for (const s3 of resources.s3) {
+					if (opts.nameOnly) {
+						console.log(s3.bucket_name);
+						continue;
+					}
+					console.log(tui.bold(s3.bucket_name));
+					if (s3.access_key) {
+						const displayAccessKey = shouldMask
+							? tui.maskSecret(s3.access_key)
+							: s3.access_key;
+						console.log(` Access Key: ${tui.muted(displayAccessKey)}`);
+					}
+					if (s3.secret_key) {
+						const displaySecretKey = shouldMask
+							? tui.maskSecret(s3.secret_key)
+							: s3.secret_key;
+						console.log(` Secret Key: ${tui.muted(displaySecretKey)}`);
+					}
+					if (s3.region) console.log(` Region:     ${tui.muted(s3.region)}`);
+					if (s3.endpoint) console.log(` Endpoint:   ${tui.muted(s3.endpoint)}`);
+					tui.newline();
+				}
+			}
+		}
+
+		return {
+			buckets: resources.s3.map((s3) => ({
+				bucket_name: s3.bucket_name,
+				access_key: s3.access_key ?? undefined,
+				secret_key: s3.secret_key ?? undefined,
+				region: s3.region ?? undefined,
+				endpoint: s3.endpoint ?? undefined,
+			})),
+		};
+	},
+});

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

@@ -0,0 +1,165 @@
+import { z } from 'zod';
+import { basename } from 'path';
+import { listResources } from '@agentuity/server';
+import { createSubcommand } from '../../../types';
+import * as tui from '../../../tui';
+import { getCatalystAPIClient } from '../../../config';
+import { getCommand } from '../../../command-prefix';
+import { ErrorCode } from '../../../errors';
+import { createS3Client } from './utils';
+
+export const uploadSubcommand = createSubcommand({
+	name: 'upload',
+	aliases: ['put'],
+	description: 'Upload a file to storage bucket',
+	tags: ['write', 'requires-auth'],
+	requires: { auth: true, org: true, region: true },
+	idempotent: false,
+	examples: [
+		{
+			command: `${getCommand('cloud storage upload')} my-bucket file.txt`,
+			description: 'Upload file to bucket',
+		},
+		{
+			command: `${getCommand('cloud storage put')} my-bucket file.txt --content-type text/plain`,
+			description: 'Upload file with content type',
+		},
+		{
+			command: `cat file.txt | ${getCommand('cloud storage upload')} my-bucket -`,
+			description: 'Upload from stdin',
+		},
+	],
+	schema: {
+		args: z.object({
+			name: z.string().describe('Bucket name'),
+			filename: z.string().describe('File path to upload or "-" for STDIN'),
+		}),
+		options: z.object({
+			contentType: z
+				.string()
+				.optional()
+				.describe('Content type (auto-detected if not provided)'),
+		}),
+		response: z.object({
+			success: z.boolean().describe('Whether upload succeeded'),
+			bucket: z.string().describe('Bucket name'),
+			filename: z.string().describe('Uploaded filename'),
+			size: z.number().describe('File size in bytes'),
+		}),
+	},
+
+	async handler(ctx) {
+		const { logger, args, opts, options, orgId, region, config, auth } = ctx;
+
+		const catalystClient = getCatalystAPIClient(config, logger, auth);
+
+		// Fetch bucket credentials
+		const resources = await tui.spinner({
+			message: `Fetching credentials for ${args.name}`,
+			clearOnSuccess: true,
+			callback: async () => {
+				return listResources(catalystClient, orgId, region);
+			},
+		});
+
+		const bucket = resources.s3.find((s3) => s3.bucket_name === args.name);
+
+		if (!bucket) {
+			tui.fatal(`Storage bucket '${args.name}' not found`, ErrorCode.RESOURCE_NOT_FOUND);
+		}
+
+		if (!bucket.access_key || !bucket.secret_key || !bucket.endpoint) {
+			tui.fatal(
+				`Storage bucket '${args.name}' is missing credentials`,
+				ErrorCode.CONFIG_INVALID
+			);
+		}
+
+		// TODO: we need to optimize this to not load the entire file in memory!
+
+		// Read file content
+		let fileContent: Buffer;
+		let actualFilename: string;
+
+		if (args.filename === '-') {
+			// Read from STDIN (binary-safe)
+			try {
+				const arrayBuffer = await Bun.readableStreamToArrayBuffer(Bun.stdin.stream());
+				fileContent = Buffer.from(arrayBuffer);
+				actualFilename = 'stdin';
+			} catch (error) {
+				tui.fatal(
+					`Cannot read from stdin: ${error instanceof Error ? error.message : String(error)}`,
+					ErrorCode.FILE_NOT_FOUND
+				);
+			}
+		} else {
+			// Read from file
+			const file = Bun.file(args.filename);
+			if (!(await file.exists())) {
+				tui.fatal(`File not found: ${args.filename}`, ErrorCode.FILE_NOT_FOUND);
+			}
+			fileContent = Buffer.from(await file.arrayBuffer());
+			actualFilename = basename(args.filename);
+		}
+
+		// Auto-detect content type
+		let contentType = opts.contentType;
+		if (!contentType && args.filename !== '-') {
+			const filename = basename(args.filename);
+			const dotIndex = filename.lastIndexOf('.');
+			const ext = dotIndex > 0 ? filename.substring(dotIndex + 1).toLowerCase() : undefined;
+			const mimeTypes: Record<string, string> = {
+				txt: 'text/plain',
+				html: 'text/html',
+				css: 'text/css',
+				yaml: 'application/x-yaml',
+				yml: 'application/x-yaml',
+				js: 'application/javascript',
+				json: 'application/json',
+				xml: 'application/xml',
+				pdf: 'application/pdf',
+				zip: 'application/zip',
+				jpg: 'image/jpeg',
+				jpeg: 'image/jpeg',
+				png: 'image/png',
+				gif: 'image/gif',
+				svg: 'image/svg+xml',
+				mp4: 'video/mp4',
+				mp3: 'audio/mpeg',
+			};
+			contentType = ext ? mimeTypes[ext] : 'application/octet-stream';
+		}
+
+		// Upload using Bun.s3
+		const s3Client = createS3Client({
+			endpoint: bucket.endpoint,
+			access_key: bucket.access_key,
+			secret_key: bucket.secret_key,
+			region: bucket.region,
+		});
+
+		await tui.spinner({
+			message: `Uploading ${actualFilename} to ${args.name}`,
+			clearOnSuccess: true,
+			callback: async () => {
+				await s3Client.write(actualFilename, fileContent, {
+					type: contentType,
+				});
+			},
+		});
+
+		if (!options.json) {
+			tui.success(
+				`Uploaded ${tui.bold(actualFilename)} to ${tui.bold(args.name)} (${fileContent.length} bytes)`
+			);
+		}
+
+		return {
+			success: true,
+			bucket: args.name,
+			filename: actualFilename,
+			size: fileContent.length,
+		};
+	},
+});

package/src/cmd/cloud/storage/utils.ts

@@ -0,0 +1,26 @@
+import { S3Client } from 'bun';
+
+/**
+ * Creates an S3Client configured for Agentuity storage buckets
+ *
+ * Agentuity provides bucket-specific endpoints in virtual-hosted-style format.
+ * The endpoint is already bucket-specific (e.g., bucket-name.agentuity.run),
+ * so we use virtualHostedStyle: true WITHOUT passing a bucket parameter.
+ *
+ * @param bucket - Bucket configuration with endpoint, credentials, and region
+ * @returns Configured S3Client instance
+ */
+export function createS3Client(bucket: {
+	endpoint: string;
+	access_key: string;
+	secret_key: string;
+	region?: string | null;
+}): S3Client {
+	return new S3Client({
+		endpoint: bucket.endpoint.startsWith('http') ? bucket.endpoint : `https://${bucket.endpoint}`,
+		accessKeyId: bucket.access_key,
+		secretAccessKey: bucket.secret_key,
+		region: bucket.region || 'auto',
+		virtualHostedStyle: true,
+	});
+}

package/src/cmd/cloud/stream/delete.ts

@@ -3,7 +3,6 @@ import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
 import { createStorageAdapter } from './util';
 import { getCommand } from '../../../command-prefix';
-
 const DeleteStreamResponseSchema = z.object({
 	id: z.string().describe('Stream ID'),
 });
@@ -16,9 +15,15 @@ export const deleteSubcommand = createCommand({
 	idempotent: true,
 	requires: { auth: true, project: true },
 	examples: [
-		`${getCommand('stream delete stream-id-123')} - Delete a stream`,
-		`${getCommand('stream rm stream-id-456')} - Delete stream (using alias)`,
-		`${getCommand('stream del stream-id-789')} - Delete stream (using alias)`,
+		{ command: getCommand('stream delete stream-id-123'), description: 'Delete a stream' },
+		{
+			command: getCommand('stream rm stream-id-456'),
+			description: 'Delete stream (using alias)',
+		},
+		{
+			command: getCommand('stream del stream-id-789'),
+			description: 'Delete stream (using alias)',
+		},
 	],
 	schema: {
 		args: z.object({

package/src/cmd/cloud/stream/get.ts

@@ -3,7 +3,6 @@ import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
 import { createStorageAdapter } from './util';
 import { getCommand } from '../../../command-prefix';
-
 function formatBytes(bytes: number): string {
 	if (bytes === 0) return '0 B';
 	if (bytes < 1024) return `${bytes} B`;
@@ -27,10 +26,16 @@ export const getSubcommand = createCommand({
 	requires: { auth: true, project: true },
 	idempotent: true,
 	examples: [
-		`${getCommand('stream get stream-id-123')} - Get stream details`,
-		`${getCommand('stream get stream-id-123 --json')} - Get stream as JSON`,
-		`${getCommand('stream get stream-id-123 --output stream.dat')} - Download stream to file`,
-		`${getCommand('stream get stream-id-123 -o stream.dat')} - Download stream (short flag)`,
+		{ command: getCommand('stream get stream-id-123'), description: 'Get stream details' },
+		{ command: getCommand('stream get stream-id-123 --json'), description: 'Get stream as JSON' },
+		{
+			command: getCommand('stream get stream-id-123 --output stream.dat'),
+			description: 'Download stream to file',
+		},
+		{
+			command: getCommand('stream get stream-id-123 -o stream.dat'),
+			description: 'Download stream (short flag)',
+		},
 	],
 	schema: {
 		args: z.object({

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

@@ -2,12 +2,17 @@ import { createCommand } from '../../../types';
 import listSubcommand from './list';
 import getSubcommand from './get';
 import deleteSubcommand from './delete';
+import { getCommand } from '../../../command-prefix';
 
 export const streamCommand = createCommand({
 	name: 'stream',
 	aliases: ['streams'],
 	description: 'Manage streams',
 	tags: ['slow', 'requires-auth'],
+	examples: [
+		{ command: getCommand('cloud stream list'), description: 'List all streams' },
+		{ command: getCommand('cloud stream get <id>'), description: 'Get stream details' },
+	],
 	subcommands: [listSubcommand, getSubcommand, deleteSubcommand],
 });
 

package/src/cmd/cloud/stream/list.ts

@@ -3,7 +3,6 @@ import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
 import { createStorageAdapter } from './util';
 import { getCommand } from '../../../command-prefix';
-
 function formatBytes(bytes: number): string {
 	if (bytes === 0) return '0 B';
 	if (bytes < 1024) return `${bytes} B`;
@@ -33,11 +32,14 @@ export const listSubcommand = createCommand({
 	requires: { auth: true, project: true },
 	idempotent: true,
 	examples: [
-		`${getCommand('stream list')} - List all streams`,
-		`${getCommand('stream ls --size 50')} - List 50 most recent streams`,
-		`${getCommand('stream list --name agent-logs')} - Filter by name`,
-		`${getCommand('stream list --metadata type=export')} - Filter by metadata`,
-		`${getCommand('stream ls --json')} - Output as JSON`,
+		{ command: getCommand('stream list'), description: 'List all streams' },
+		{ command: getCommand('stream ls --size 50'), description: 'List 50 most recent streams' },
+		{ command: getCommand('stream list --name agent-logs'), description: 'Filter by name' },
+		{
+			command: getCommand('stream list --metadata type=export'),
+			description: 'Filter by metadata',
+		},
+		{ command: getCommand('stream ls --json'), description: 'Output as JSON' },
 	],
 	schema: {
 		options: z.object({

package/src/cmd/cloud/vector/delete.ts

@@ -4,7 +4,6 @@ import { ErrorCode } from '../../../errors';
 import * as tui from '../../../tui';
 import { createStorageAdapter } from './util';
 import { getCommand } from '../../../command-prefix';
-
 const VectorDeleteResponseSchema = z.object({
 	success: z.boolean().describe('Whether the operation succeeded'),
 	namespace: z.string().describe('Namespace name'),
@@ -22,9 +21,18 @@ export const deleteSubcommand = createCommand({
 	requires: { auth: true, project: true },
 	idempotent: true,
 	examples: [
-		`${getCommand('vector delete products chair-001')} - Delete a single vector (interactive)`,
-		`${getCommand('vector rm knowledge-base doc-123 doc-456 --confirm')} - Delete multiple vectors without confirmation`,
-		`${getCommand('vector del embeddings old-profile-1 old-profile-2 --confirm')} - Bulk delete without confirmation`,
+		{
+			command: getCommand('vector delete products chair-001'),
+			description: 'Delete a single vector (interactive)',
+		},
+		{
+			command: getCommand('vector rm knowledge-base doc-123 doc-456 --confirm'),
+			description: 'Delete multiple vectors without confirmation',
+		},
+		{
+			command: getCommand('vector del embeddings old-profile-1 old-profile-2 --confirm'),
+			description: 'Bulk delete without confirmation',
+		},
 	],
 	schema: {
 		args: z.object({
@@ -51,8 +59,11 @@ export const deleteSubcommand = createCommand({
 					ErrorCode.VALIDATION_FAILED
 				);
 			}
-			const keyList = args.keys.length > 3 ? `${args.keys.slice(0, 3).join(', ')}...` : args.keys.join(', ');
-			tui.warning(`This will delete ${args.keys.length} vector(s) from ${tui.bold(args.namespace)}: ${keyList}`);
+			const keyList =
+				args.keys.length > 3 ? `${args.keys.slice(0, 3).join(', ')}...` : args.keys.join(', ');
+			tui.warning(
+				`This will delete ${args.keys.length} vector(s) from ${tui.bold(args.namespace)}: ${keyList}`
+			);
 			const confirm = await new Promise<boolean>((resolve) => {
 				process.stdout.write('Are you sure? (yes/no): ');
 				process.stdin.once('data', (data) => {

package/src/cmd/cloud/vector/get.ts

@@ -3,7 +3,6 @@ import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
 import { createStorageAdapter } from './util';
 import { getCommand } from '../../../command-prefix';
-
 const VectorGetResponseSchema = z.object({
 	exists: z.boolean().describe('Whether the vector exists'),
 	key: z.string().optional().describe('Vector key'),
@@ -20,9 +19,18 @@ export const getSubcommand = createCommand({
 	requires: { auth: true, project: true },
 	idempotent: true,
 	examples: [
-		`${getCommand('vector get products chair-001')} - Get a specific product vector`,
-		`${getCommand('vector get knowledge-base doc-123')} - Get a document from knowledge base`,
-		`${getCommand('vector get embeddings user-profile-456')} - Get user profile embedding`,
+		{
+			command: getCommand('vector get products chair-001'),
+			description: 'Get a specific product vector',
+		},
+		{
+			command: getCommand('vector get knowledge-base doc-123'),
+			description: 'Get a document from knowledge base',
+		},
+		{
+			command: getCommand('vector get embeddings user-profile-456'),
+			description: 'Get user profile embedding',
+		},
 	],
 	schema: {
 		args: z.object({

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

@@ -2,12 +2,20 @@ import { createCommand } from '../../../types';
 import { deleteSubcommand } from './delete';
 import { getSubcommand } from './get';
 import { searchSubcommand } from './search';
+import { getCommand } from '../../../command-prefix';
 
 export const vectorCommand = createCommand({
 	name: 'vector',
 	aliases: ['vec'],
 	description: 'Manage vector storage for your projects',
 	tags: ['requires-auth', 'destructive', 'deletes-resource', 'slow'],
+	examples: [
+		{
+			command: getCommand('cloud vector search "query text"'),
+			description: 'Search vector storage',
+		},
+		{ command: getCommand('cloud vec get <id>'), description: 'Get vector by ID' },
+	],
 	subcommands: [searchSubcommand, getSubcommand, deleteSubcommand],
 	requires: { auth: true, project: true },
 });

package/src/cmd/cloud/vector/search.ts

@@ -3,7 +3,6 @@ import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
 import { createStorageAdapter } from './util';
 import { getCommand } from '../../../command-prefix';
-
 const VectorSearchResultSchema = z.object({
 	id: z.string().describe('Vector ID'),
 	key: z.string().describe('Vector key'),
@@ -26,11 +25,26 @@ export const searchSubcommand = createCommand({
 	requires: { auth: true, project: true },
 	idempotent: true,
 	examples: [
-		`${getCommand('vector search products "comfortable office chair"')} - Search for similar products`,
-		`${getCommand('vector list knowledge-base "machine learning"')} - Search knowledge base`,
-		`${getCommand('vector search docs "API documentation" --limit 5')} - Limit results`,
-		`${getCommand('vector search products "ergonomic" --similarity 0.8')} - Set minimum similarity`,
-		`${getCommand('vector ls embeddings "neural networks" --metadata category=ai')} - Filter by metadata`,
+		{
+			command: getCommand('vector search products "comfortable office chair"'),
+			description: 'Search for similar products',
+		},
+		{
+			command: getCommand('vector list knowledge-base "machine learning"'),
+			description: 'Search knowledge base',
+		},
+		{
+			command: getCommand('vector search docs "API documentation" --limit 5'),
+			description: 'Limit results',
+		},
+		{
+			command: getCommand('vector search products "ergonomic" --similarity 0.8'),
+			description: 'Set minimum similarity',
+		},
+		{
+			command: getCommand('vector ls embeddings "neural networks" --metadata category=ai'),
+			description: 'Filter by metadata',
+		},
 	],
 	schema: {
 		args: z.object({