@agentuity/cli 0.0.61 → 0.0.63

package/src/cmd/cloud/index.ts

@@ -3,6 +3,7 @@ import { deploySubcommand } from './deploy';
 import { dbCommand } from './db';
 import { storageCommand } from './storage';
 import { sessionCommand } from './session';
+import { threadCommand } from './thread';
 import { sshSubcommand } from './ssh';
 import { scpSubcommand } from './scp';
 import { deploymentCommand } from './deployment';
@@ -37,6 +38,7 @@ export const command = createCommand({
 		dbCommand,
 		storageCommand,
 		sessionCommand,
+		threadCommand,
 		sshSubcommand,
 		scpSubcommand,
 		deploymentCommand,

package/src/cmd/cloud/secret/set.ts

@@ -19,11 +19,11 @@ export const setSubcommand = createSubcommand({
 	examples: [
 		{
 			command: getCommand('secret set DATABASE_URL "postgres://user:pass@host:5432/db"'),
-			description: 'Run "postgres://user:pass@host:5432/db" command',
+			description: 'Set the DATABASE_URL environment secret',
 		},
 		{
 			command: getCommand('secret set STRIPE_SECRET_KEY "sk_live_..."'),
-			description: 'Run "sk_live_..." command',
+			description: 'Set the STRIPE_SECRET_KEY environment secret',
 		},
 	],
 	requires: { auth: true, project: true, apiClient: true },

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

@@ -1,7 +1,13 @@
 import { z } from 'zod';
 import { createSubcommand } from '../../../types';
 import * as tui from '../../../tui';
-import { sessionGet, type SpanNode, type EvalRun, type AgentInfo } from '@agentuity/server';
+import {
+	sessionGet,
+	type SpanNode,
+	type EvalRun,
+	type AgentInfo,
+	APIError,
+} from '@agentuity/server';
 import { getCommand } from '../../../command-prefix';
 import { ErrorCode } from '../../../errors';
 import { getCatalystAPIClient } from '../../../config';
@@ -104,7 +110,12 @@ export const getSubcommand = createSubcommand({
 	name: 'get',
 	description: 'Get details about a specific session',
 	tags: ['read-only', 'fast', 'requires-auth'],
-	examples: [{ command: getCommand('cloud session get'), description: 'sess_abc123xyz' }],
+	examples: [
+		{
+			command: getCommand('cloud session get sess_abc123xyz'),
+			description: 'Get a session by ID',
+		},
+	],
 	requires: { auth: true },
 	idempotent: true,
 	schema: {
@@ -233,6 +244,9 @@ export const getSubcommand = createSubcommand({
 
 			return result;
 		} catch (ex) {
+			if (ex instanceof APIError && ex.status === 404) {
+				tui.fatal(`Session ${args.session_id} not found`, ErrorCode.RESOURCE_NOT_FOUND);
+			}
 			tui.fatal(
 				`Failed to get session: ${ex instanceof Error ? ex.message : String(ex)}`,
 				ErrorCode.API_ERROR

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

@@ -14,9 +14,18 @@ export const createSubcommand = defineSubcommand({
 	idempotent: false,
 	requires: { auth: true, org: true, region: true },
 	examples: [
-		{ command: getCommand('cloud storage create'), description: 'Create new item' },
-		{ command: getCommand('cloud storage new'), description: 'Run new command' },
-		{ command: getCommand('--dry-run cloud storage create'), description: 'Create new item' },
+		{
+			command: getCommand('cloud storage create'),
+			description: 'Create a new cloud storage bucket',
+		},
+		{
+			command: getCommand('cloud storage new'),
+			description: 'Alias for "cloud storage create" (shorthand "new")',
+		},
+		{
+			command: getCommand('--dry-run cloud storage create'),
+			description: 'Dry-run: display what would be created without making changes',
+		},
 	],
 	schema: {
 		response: z.object({

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

@@ -17,12 +17,21 @@ export const deleteSubcommand = createSubcommand({
 	idempotent: false,
 	requires: { auth: true, org: true, region: true },
 	examples: [
-		{ command: getCommand('cloud storage delete my-bucket'), description: 'Delete item' },
-		{ command: getCommand('cloud storage rm my-bucket file.txt'), description: 'Delete item' },
-		{ command: getCommand('cloud storage delete'), description: 'Delete item' },
+		{
+			command: getCommand('cloud storage delete my-bucket'),
+			description: 'Delete a storage bucket',
+		},
+		{
+			command: getCommand('cloud storage rm my-bucket file.txt'),
+			description: 'Delete a file from a bucket',
+		},
+		{
+			command: getCommand('cloud storage delete'),
+			description: 'Interactive selection to delete a bucket',
+		},
 		{
 			command: getCommand('--dry-run cloud storage delete my-bucket'),
-			description: 'Delete item',
+			description: 'Dry-run: show what would be deleted without making changes',
 		},
 	],
 	schema: {

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

@@ -32,14 +32,17 @@ export const listSubcommand = createCommand({
 	requires: { auth: true, project: true },
 	idempotent: true,
 	examples: [
-		{ 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('cloud stream list'), description: 'List all streams' },
 		{
-			command: getCommand('stream list --metadata type=export'),
+			command: getCommand('cloud stream ls --size 50'),
+			description: 'List 50 most recent streams',
+		},
+		{ command: getCommand('cloud stream list --name agent-logs'), description: 'Filter by name' },
+		{
+			command: getCommand('cloud stream list --metadata type=export'),
 			description: 'Filter by metadata',
 		},
-		{ command: getCommand('stream ls --json'), description: 'Output as JSON' },
+		{ command: getCommand('cloud stream ls --json'), description: 'Output as JSON' },
 	],
 	schema: {
 		options: z.object({

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

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import { createSubcommand } from '../../../types';
+import * as tui from '../../../tui';
+import { threadDelete, APIError } from '@agentuity/server';
+import { getCommand } from '../../../command-prefix';
+import { ErrorCode } from '../../../errors';
+import { getCatalystAPIClient } from '../../../config';
+
+export const deleteSubcommand = createSubcommand({
+	name: 'delete',
+	description: 'Delete a thread',
+	tags: ['destructive', 'requires-auth'],
+	examples: [
+		{
+			command: getCommand('cloud thread delete thrd_abc123xyz'),
+			description: 'Delete a thread by ID',
+		},
+	],
+	aliases: ['rm'],
+	requires: { auth: true },
+	schema: {
+		args: z.object({
+			thread_id: z.string().describe('Thread ID'),
+		}),
+	},
+	async handler(ctx) {
+		const { config, logger, auth, args } = ctx;
+		const catalystClient = getCatalystAPIClient(config, logger, auth);
+
+		try {
+			await threadDelete(catalystClient, { id: args.thread_id });
+			tui.success(`Thread ${args.thread_id} deleted successfully`);
+		} catch (ex) {
+			if (ex instanceof APIError && ex.status === 404) {
+				tui.fatal(`Thread ${args.thread_id} not found`, ErrorCode.RESOURCE_NOT_FOUND);
+				return;
+			}
+			tui.fatal(
+				`Failed to delete thread: ${ex instanceof Error ? ex.message : String(ex)}`,
+				ErrorCode.API_ERROR
+			);
+		}
+	},
+});

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

@@ -0,0 +1,88 @@
+import { z } from 'zod';
+import { createSubcommand } from '../../../types';
+import * as tui from '../../../tui';
+import { threadGet, APIError } from '@agentuity/server';
+import { getCommand } from '../../../command-prefix';
+import { ErrorCode } from '../../../errors';
+import { getCatalystAPIClient } from '../../../config';
+
+const ThreadGetResponseSchema = z.object({
+	id: z.string().describe('Thread ID'),
+	created_at: z.string().describe('Creation timestamp'),
+	updated_at: z.string().describe('Update timestamp'),
+	deleted: z.boolean().describe('Deleted status'),
+	deleted_at: z.string().nullable().describe('Deletion timestamp'),
+	deleted_by: z.string().nullable().describe('Deleted by'),
+	org_id: z.string().describe('Organization ID'),
+	project_id: z.string().describe('Project ID'),
+	user_data: z.string().nullable().optional().describe('User data as JSON'),
+});
+
+export const getSubcommand = createSubcommand({
+	name: 'get',
+	description: 'Get details about a specific thread',
+	tags: ['read-only', 'fast', 'requires-auth'],
+	examples: [
+		{
+			command: getCommand('cloud thread get thrd_abc123xyz'),
+			description: 'Get a thread by ID',
+		},
+	],
+	requires: { auth: true },
+	idempotent: true,
+	schema: {
+		args: z.object({
+			thread_id: z.string().describe('Thread ID'),
+		}),
+		response: ThreadGetResponseSchema,
+	},
+	async handler(ctx) {
+		const { config, logger, auth, args, options } = ctx;
+		const catalystClient = getCatalystAPIClient(config, logger, auth);
+
+		try {
+			const thread = await threadGet(catalystClient, { id: args.thread_id });
+
+			const result = {
+				id: thread.id,
+				created_at: thread.created_at,
+				updated_at: thread.updated_at,
+				deleted: thread.deleted,
+				deleted_at: thread.deleted_at,
+				deleted_by: thread.deleted_by,
+				org_id: thread.org_id,
+				project_id: thread.project_id,
+				user_data: thread.user_data,
+			};
+
+			if (options.json) {
+				return result;
+			}
+
+			console.log(tui.bold('ID:          ') + thread.id);
+			console.log(tui.bold('Project:     ') + thread.project_id);
+			console.log(tui.bold('Created:     ') + new Date(thread.created_at).toLocaleString());
+			console.log(tui.bold('Updated:     ') + new Date(thread.updated_at).toLocaleString());
+			console.log(tui.bold('Deleted:     ') + (thread.deleted ? 'Yes' : 'No'));
+			if (thread.deleted_at) {
+				console.log(tui.bold('Deleted At:  ') + new Date(thread.deleted_at).toLocaleString());
+			}
+			if (thread.deleted_by) {
+				console.log(tui.bold('Deleted By:  ') + thread.deleted_by);
+			}
+			if (thread.user_data) {
+				console.log(tui.bold('User Data:   ') + thread.user_data);
+			}
+
+			return result;
+		} catch (ex) {
+			if (ex instanceof APIError && ex.status === 404) {
+				tui.fatal(`Thread ${args.thread_id} not found`, ErrorCode.RESOURCE_NOT_FOUND);
+			}
+			tui.fatal(
+				`Failed to get thread: ${ex instanceof Error ? ex.message : String(ex)}`,
+				ErrorCode.API_ERROR
+			);
+		}
+	},
+});

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

@@ -0,0 +1,17 @@
+import { createCommand } from '../../../types';
+import { getSubcommand } from './get';
+import { listSubcommand } from './list';
+import { deleteSubcommand } from './delete';
+import { getCommand } from '../../../command-prefix';
+
+export const threadCommand = createCommand({
+	name: 'thread',
+	description: 'Manage threads',
+	tags: ['requires-auth'],
+	examples: [
+		{ command: getCommand('cloud thread list'), description: 'List all threads' },
+		{ command: getCommand('cloud thread get <id>'), description: 'Get thread details' },
+		{ command: getCommand('cloud thread delete <id>'), description: 'Delete a thread' },
+	],
+	subcommands: [getSubcommand, listSubcommand, deleteSubcommand],
+});

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

@@ -0,0 +1,125 @@
+import { z } from 'zod';
+import { createSubcommand } from '../../../types';
+import * as tui from '../../../tui';
+import { threadList, type Thread } from '@agentuity/server';
+import { getCommand } from '../../../command-prefix';
+import { ErrorCode } from '../../../errors';
+import { getCatalystAPIClient } from '../../../config';
+
+const ThreadListResponseSchema = z.array(
+	z.object({
+		id: z.string().describe('Thread ID'),
+		created_at: z.string().describe('Creation timestamp'),
+		updated_at: z.string().describe('Update timestamp'),
+		project_id: z.string().describe('Project ID'),
+		user_data: z.string().nullable().optional().describe('User data as JSON'),
+	})
+);
+
+export const listSubcommand = createSubcommand({
+	name: 'list',
+	description: 'List recent threads',
+	tags: ['read-only', 'fast', 'requires-auth'],
+	examples: [
+		{ command: getCommand('cloud thread list'), description: 'List 10 most recent threads' },
+		{
+			command: getCommand('cloud thread list --count=25'),
+			description: 'List 25 most recent threads',
+		},
+		{
+			command: getCommand('cloud thread list --project-id=proj_*'),
+			description: 'Filter by project',
+		},
+		{
+			command: getCommand('cloud thread list --org-id=org_*'),
+			description: 'Filter by organization',
+		},
+	],
+	aliases: ['ls'],
+	requires: { auth: true },
+	optional: { project: true },
+	idempotent: true,
+	pagination: {
+		supported: true,
+		defaultLimit: 10,
+		maxLimit: 100,
+		parameters: {
+			limit: 'count',
+		},
+	},
+	schema: {
+		options: z.object({
+			count: z.coerce
+				.number()
+				.int()
+				.min(1)
+				.max(100)
+				.default(10)
+				.describe('Number of threads to list (1–100)'),
+			orgId: z.string().optional().describe('Filter by organization ID'),
+			projectId: z.string().optional().describe('Filter by project ID'),
+		}),
+		response: ThreadListResponseSchema,
+	},
+	async handler(ctx) {
+		const { config, logger, auth, project, opts, options } = ctx;
+		const catalystClient = getCatalystAPIClient(config, logger, auth);
+
+		const projectId = opts.projectId || project?.projectId;
+		const orgId = opts.orgId;
+
+		try {
+			const threads = await threadList(catalystClient, {
+				count: opts.count,
+				orgId,
+				projectId,
+			});
+
+			const result = threads.map((t: Thread) => ({
+				id: t.id,
+				created_at: t.created_at,
+				updated_at: t.updated_at,
+				project_id: t.project_id,
+				user_data: t.user_data,
+			}));
+
+			if (options.json) {
+				return result;
+			}
+
+			if (threads.length === 0) {
+				tui.info('No threads found.');
+				return [];
+			}
+
+			const tableData = threads.map((t: Thread) => {
+				return {
+					ID: t.id,
+					Project: t.project_id,
+					Created: new Date(t.created_at).toLocaleString(),
+					Updated: new Date(t.updated_at).toLocaleString(),
+					'User Data': t.user_data
+						? t.user_data.length > 50
+							? t.user_data.substring(0, 47) + '...'
+							: t.user_data
+						: '-',
+				};
+			});
+
+			tui.table(tableData, [
+				{ name: 'ID', alignment: 'left' },
+				{ name: 'Project', alignment: 'left' },
+				{ name: 'Created', alignment: 'left' },
+				{ name: 'Updated', alignment: 'left' },
+				{ name: 'User Data', alignment: 'left' },
+			]);
+
+			return result;
+		} catch (ex) {
+			tui.fatal(
+				`Failed to list threads: ${ex instanceof Error ? ex.message : String(ex)}`,
+				ErrorCode.API_ERROR
+			);
+		}
+	},
+});

package/src/cmd/dev/templates.ts

@@ -1,6 +1,7 @@
 /* eslint-disable no-control-regex */
 import { writeFileSync } from 'node:fs';
 import { basename, join } from 'node:path';
+import { toCamelCase } from '../../utils/string';
 
 const newAgentTemplate = (name: string) => `import { createAgent } from '@agentuity/runtime';
 import { z } from 'zod';
@@ -23,19 +24,22 @@ const agent = createAgent({
 export default agent;
 `;
 
-const newAgentRouteTemplate = (name: string) => `import { createRouter } from '@agentuity/runtime';
+const newAgentRouteTemplate = (name: string) => {
+	const camelName = toCamelCase(name);
+	return `import { createRouter } from '@agentuity/runtime';
 
 const router = createRouter();
 
 router.get('/', async (c) => {
 	// TODO: add your code here
-	const output = await c.agent.${name}.run('hello world');
+	const output = await c.agent.${camelName}.run('hello world');
 	return c.text(output);
 });
 
 export default router;
 
 `;
+};
 
 const newAPIRouteTemplate = (_name: string) => `import { createRouter } from '@agentuity/runtime';
 

package/src/cmd/profile/use.ts

@@ -11,9 +11,18 @@ export const useCommand = createSubcommand({
 	aliases: ['switch'],
 	idempotent: true,
 	examples: [
-		{ command: getCommand('profile use production'), description: 'Run production command' },
-		{ command: getCommand('profile switch staging'), description: 'Run staging command' },
-		{ command: getCommand('profile use'), description: 'Run use command' },
+		{
+			command: getCommand('profile use production'),
+			description: 'Switch to the "production" profile',
+		},
+		{
+			command: getCommand('profile switch staging'),
+			description: 'Switch to the "staging" profile',
+		},
+		{
+			command: getCommand('profile use'),
+			description: 'Show interactive profile selection menu',
+		},
 	],
 	schema: {
 		args: z.object({

package/src/cmd/project/download.ts

@@ -282,14 +282,23 @@ export async function setupProject(options: SetupOptions): Promise<void> {
 	}
 
 	// generate and write AGENTS.md for each of the main folders
-	const agentsAPIFile = join(dest, 'src', 'agents', 'AGENTS.md');
-	await Bun.write(agentsAPIFile, generateAgentPrompt());
+	const agentsDir = join(dest, 'src', 'agents');
+	if (existsSync(agentsDir)) {
+		const agentsAPIFile = join(agentsDir, 'AGENTS.md');
+		await Bun.write(agentsAPIFile, generateAgentPrompt());
+	}
 
-	const agentsAPIsFile = join(dest, 'src', 'apis', 'AGENTS.md');
-	await Bun.write(agentsAPIsFile, generateAPIPrompt());
+	const apisDir = join(dest, 'src', 'apis');
+	if (existsSync(apisDir)) {
+		const agentsAPIsFile = join(apisDir, 'AGENTS.md');
+		await Bun.write(agentsAPIsFile, generateAPIPrompt());
+	}
 
-	const agentsWebFile = join(dest, 'src', 'web', 'AGENTS.md');
-	await Bun.write(agentsWebFile, generateWebPrompt());
+	const webDir = join(dest, 'src', 'web');
+	if (existsSync(webDir)) {
+		const agentsWebFile = join(webDir, 'AGENTS.md');
+		await Bun.write(agentsWebFile, generateWebPrompt());
+	}
 }
 
 async function replaceInFiles(dir: string, projectName: string, dirName: string): Promise<void> {

package/src/cmd/project/list.ts

@@ -24,9 +24,12 @@ export const listSubcommand = createSubcommand({
 		response: ProjectListResponseSchema,
 	},
 	examples: [
-		{ command: getCommand('project list'), description: 'List items' },
-		{ command: getCommand('--json project list'), description: 'Show output in JSON format' },
-		{ command: getCommand('project ls'), description: 'List items' },
+		{ command: getCommand('project list'), description: 'List projects (human-readable)' },
+		{ command: getCommand('--json project list'), description: 'List projects in JSON format' },
+		{
+			command: getCommand('project ls'),
+			description: 'Alias for "project list" — list projects (human-readable)',
+		},
 	],
 
 	async handler(ctx) {

package/src/cmd/version/index.ts

@@ -12,8 +12,11 @@ export const command = createCommand({
 	description: 'Display version information',
 	tags: ['read-only', 'fast'],
 	examples: [
-		{ command: getCommand('version'), description: 'Run version command' },
-		{ command: getCommand('--version'), description: 'Show version information' },
+		{ command: getCommand('version'), description: 'Show the CLI semantic version' },
+		{
+			command: getCommand('--version'),
+			description: 'Display the current installed CLI version and build metadata',
+		},
 	],
 	schema: {
 		response: VersionResponseSchema,

package/src/utils/string.ts

@@ -0,0 +1,6 @@
+/**
+ * String utility functions for identifier conversion
+ * Re-exported from @agentuity/core for convenience
+ */
+
+export { toCamelCase, toPascalCase } from '@agentuity/core';