@agentuity/cli 0.0.61 → 0.0.62

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agentuity/cli",
-	"version": "0.0.61",
+	"version": "0.0.62",
 	"license": "Apache-2.0",
 	"author": "Agentuity employees and contributors",
 	"type": "module",
@@ -35,8 +35,9 @@
 		"prepublishOnly": "bun run clean && bun run build"
 	},
 	"dependencies": {
-		"@agentuity/core": "0.0.61",
-		"@agentuity/server": "0.0.61",
+		"@agentuity/core": "0.0.62",
+		"@agentuity/server": "0.0.62",
+		"@datasert/cronjs-parser": "^1.4.0",
 		"@terascope/fetch-github-release": "^2.2.1",
 		"acorn-loose": "^8.5.2",
 		"adm-zip": "^0.5.16",

package/src/banner.ts

@@ -46,7 +46,7 @@ export function generateBanner(version?: string, compact?: true): string {
 		CYAN + '╰────────────────────────────────────────────────────╯' + RESET,
 	].filter(Boolean) as string[];
 
-	return lines.map((line) => console.log(line)).join('');
+	return lines.join('\n');
 }
 
 export function showBanner(version?: string, compact?: true): void {

package/src/cmd/ai/capabilities/show.ts

@@ -53,7 +53,7 @@ export const showSubcommand = createSubcommand({
 	description: 'Display CLI capabilities',
 	tags: ['read-only', 'fast'],
 	examples: [
-		{ command: getCommand('capabilities show'), description: 'Show details' },
+		{ command: getCommand('capabilities show'), description: 'Show CLI AI capabilities' },
 		{
 			command: getCommand('--json capabilities show'),
 			description: 'Show output in JSON format',

package/src/cmd/ai/schema/show.ts

@@ -9,7 +9,7 @@ export const showSubcommand = createSubcommand({
 	idempotent: true,
 	examples: [
 		{ command: getCommand('schema show'), description: 'Show details' },
-		{ command: getCommand('--help=json'), description: 'Show help information' },
+		{ command: getCommand('--json schema show'), description: 'Show output in JSON format' },
 	],
 	async handler(ctx: CommandContext) {
 		const { logger } = ctx;

package/src/cmd/build/ast.ts

@@ -1,5 +1,6 @@
 import * as acornLoose from 'acorn-loose';
 import { basename, dirname, relative } from 'node:path';
+import { parse as parseCronExpression } from '@datasert/cronjs-parser';
 import { generate } from 'astring';
 import type { BuildMetadata } from '../../types';
 import { createLogger } from '@agentuity/server';
@@ -192,7 +193,7 @@ function augmentAgentMetadataNode(
 ): [string, Map<string, string>] {
 	const metadata = parseObjectExpressionToMap(propvalue);
 	if (!metadata.has('name')) {
-		const location = ast.loc?.start ? ` on line ${ast.loc.start}` : '';
+		const location = ast.loc?.start?.line ? ` on line ${ast.loc.start.line}` : '';
 		throw new MetadataError({
 			filename,
 			line: ast.loc?.start?.line,
@@ -201,7 +202,7 @@ function augmentAgentMetadataNode(
 	}
 	const name = metadata.get('name')!;
 	if (metadata.has('identifier') && identifier !== metadata.get('identifier')) {
-		const location = ast.loc?.start ? ` on line ${ast.loc.start}` : '';
+		const location = ast.loc?.start?.line ? ` on line ${ast.loc.start.line}` : '';
 		throw new MetadataError({
 			filename,
 			line: ast.loc?.start?.line,
@@ -414,7 +415,11 @@ export function parseEvalMetadata(
 		| 'error';
 	const logger = createLogger(logLevel);
 	logger.trace(`Parsing evals from ${filename}`);
-	const ast = acornLoose.parse(contents, { ecmaVersion: 'latest', sourceType: 'module' });
+	const ast = acornLoose.parse(contents, {
+		locations: true,
+		ecmaVersion: 'latest',
+		sourceType: 'module',
+	});
 	const rel = relative(rootDir, filename);
 	const version = hash(contents);
 	const evals: Array<{
@@ -609,7 +614,11 @@ export async function parseAgentMetadata(
 	projectId: string,
 	deploymentId: string
 ): Promise<[string, Map<string, string>]> {
-	const ast = acornLoose.parse(contents, { ecmaVersion: 'latest', sourceType: 'module' });
+	const ast = acornLoose.parse(contents, {
+		locations: true,
+		ecmaVersion: 'latest',
+		sourceType: 'module',
+	});
 	let exportName: string | undefined;
 	const rel = relative(rootDir, filename);
 	const name = basename(dirname(filename));
@@ -784,7 +793,11 @@ export async function parseRoute(
 ): Promise<BuildMetadata['routes']> {
 	const contents = await Bun.file(filename).text();
 	const version = hash(contents);
-	const ast = acornLoose.parse(contents, { ecmaVersion: 'latest', sourceType: 'module' });
+	const ast = acornLoose.parse(contents, {
+		locations: true,
+		ecmaVersion: 'latest',
+		sourceType: 'module',
+	});
 	let exportName: string | undefined;
 	let variableName: string | undefined;
 	for (const body of ast.body) {
@@ -878,8 +891,8 @@ export async function parseRoute(
 								} else {
 									throw new InvalidRouterConfigError({
 										filename,
-										line: body.start,
-										message: `unsupported HTTP method ${method} in ${filename} at line ${body.start}`,
+										line: body.loc?.start?.line,
+										message: `unsupported HTTP method ${method} in ${filename} at line ${body.loc?.start?.line}`,
 									});
 								}
 								break;
@@ -933,8 +946,19 @@ export async function parseRoute(
 								method = 'post';
 								const theaction = action as ASTLiteral;
 								if (theaction.type === 'Literal') {
-									const number = theaction.value;
-									suffix = hash(number);
+									const expression = theaction.value;
+									try {
+										parseCronExpression(expression, { hasSeconds: false });
+									} catch (ex) {
+										throw new InvalidRouterConfigError({
+											filename,
+											cause: ex,
+											line: body.loc?.start?.line,
+											message: `invalid cron expression "${expression}" in ${filename} at line ${body.loc?.start?.line}`,
+										});
+									}
+									suffix = hash(expression);
+									config = { expression };
 									break;
 								}
 								break;
@@ -942,8 +966,8 @@ export async function parseRoute(
 							default: {
 								throw new InvalidRouterConfigError({
 									filename,
-									line: body.start,
-									message: `unsupported router method ${method} in ${filename} at line ${body.start}`,
+									line: body.loc?.start?.line,
+									message: `unsupported router method ${method} in ${filename} at line ${body.loc?.start?.line}`,
 								});
 							}
 						}

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/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,