@agentuity/cli 0.0.59 → 0.0.61

package/src/cmd/dev/agents.ts

@@ -3,6 +3,7 @@ import { createSubcommand } from '../../types';
 import * as tui from '../../tui';
 import { APIResponseSchema } from '@agentuity/server';
 import { abbreviate, abbreviateDescription } from '../../utils/format';
+import { getCommand } from '../../command-prefix';
 
 const AgentSchema = z.object({
 	id: z.string(),
@@ -35,6 +36,10 @@ const AgentsResponseSchema = APIResponseSchema(z.array(AgentSchema));
 export const agentsSubcommand = createSubcommand({
 	name: 'agents',
 	description: 'Show devmode agent results',
+	examples: [
+		{ command: getCommand('dev agents'), description: 'Show all development mode agents' },
+		{ command: getCommand('dev agents --verbose'), description: 'Show agents with full details' },
+	],
 	requires: { auth: true, apiClient: true, project: true },
 	schema: {
 		options: z.object({
@@ -88,7 +93,7 @@ export const agentsSubcommand = createSubcommand({
 			if (agents.length === 0) {
 				tui.muted('No agents found');
 			} else {
-				console.table(
+				tui.table(
 					agents.map((agent) => ({
 						name: agent.name,
 						id: verbose ? agent.id : abbreviate(agent.id, 20),
@@ -107,7 +112,7 @@ export const agentsSubcommand = createSubcommand({
 				for (const agent of agents) {
 					if (agent.evals.length > 0) {
 						console.log(`\n  Evals for ${agent.name}:`);
-						console.table(
+						tui.table(
 							agent.evals.map((evalItem) => ({
 								name: evalItem.name,
 								id: verbose ? evalItem.id : abbreviate(evalItem.id, 20),

package/src/cmd/dev/api.ts

@@ -1,6 +1,7 @@
 import { APIResponseSchema } from '@agentuity/server';
 import { z } from 'zod';
 import type { APIClient } from '../../api';
+import { StructuredError } from '@agentuity/core';
 
 const DevmodeRequestSchema = z.object({
 	hostname: z.string().optional().describe('the hostname for the endpoint'),
@@ -17,6 +18,8 @@ export type DevmodeResponse = z.infer<typeof DevmodeResponseSchema>;
 const DevmodeResponseAPISchema = APIResponseSchema(DevmodeResponseSchema);
 type DevmodeResponseAPI = z.infer<typeof DevmodeResponseAPISchema>;
 
+const DevmodeEndpointError = StructuredError('DevmodeEndpointError');
+
 /**
  * Generate an Endpoint ID and Hostname
  *
@@ -39,7 +42,7 @@ export async function generateEndpoint(
 	);
 
 	if (!resp.success) {
-		throw new Error(resp.message);
+		throw new DevmodeEndpointError({ message: resp.message });
 	}
 
 	return resp.data;

package/src/cmd/dev/index.ts

@@ -22,20 +22,28 @@ import { getDevmodeDeploymentId } from '../build/ast';
 import { BuildMetadata } from '@agentuity/server';
 import { getCommand } from '../../command-prefix';
 
+const shouldDisableInteractive = (interactive?: boolean) => {
+	if (!interactive) {
+		return true;
+	}
+	return process.env.TERM_PROGRAM === 'vscode';
+};
+
 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'),
+		{ command: getCommand('dev'), description: 'Start development server' },
+		{ command: getCommand('dev --port 8080'), description: 'Specify custom port' },
+		{ command: getCommand('dev --local'), description: 'Run in local mode' },
+		{ command: getCommand('dev --no-public'), description: 'Disable public URL' },
 	],
 	schema: {
 		options: z.object({
 			local: z.boolean().optional().describe('Turn on local services (instead of cloud)'),
+			interactive: z.boolean().default(true).optional().describe('Turn on interactive mode'),
 			public: z
 				.boolean()
 				.optional()
@@ -66,6 +74,8 @@ export const command = createCommand({
 		const mustHaves = [join(rootDir, 'package.json'), appTs, srcDir];
 		const missing: string[] = [];
 
+		const interactive = !shouldDisableInteractive(opts.interactive);
+
 		for (const filename of mustHaves) {
 			if (!existsSync(filename)) {
 				missing.push(filename);
@@ -137,7 +147,8 @@ export const command = createCommand({
 			}
 		}
 
-		const canDoInput = !!(process.stdin.isTTY && process.stdout.isTTY && !process.env.CI);
+		const canDoInput =
+			interactive && !!(process.stdin.isTTY && process.stdout.isTTY && !process.env.CI);
 
 		const devmodebody =
 			tui.muted(tui.padRight('Local:', 10)) +

package/src/cmd/help/index.ts

@@ -0,0 +1,40 @@
+import { createCommand } from '../../types';
+import { getCommand } from '../../command-prefix';
+
+export const command = createCommand({
+	name: 'help',
+	description: 'Display help information',
+	hidden: true,
+	tags: ['read-only', 'fast'],
+	examples: [
+		{ command: getCommand('help'), description: 'Run help command' },
+		{ command: getCommand('--help'), description: 'Show help information' },
+	],
+	idempotent: true,
+
+	async handler() {
+		// Spawn the CLI with no arguments to show help
+		let spawnArgs: string[];
+
+		if (process.env.AGENTUITY_CLI_VERSION) {
+			// Compiled binary: spawn only the binary executable with no additional args
+			spawnArgs = [process.argv[0]];
+		} else {
+			// Script mode: spawn runtime and script, omitting the 'help' argument
+			spawnArgs = [process.argv[0], ...(process.argv.length > 1 ? [process.argv[1]] : [])];
+		}
+
+		const proc = Bun.spawn(spawnArgs, {
+			stdio: ['inherit', 'inherit', 'inherit'],
+			env: process.env,
+		});
+
+		const exitCode = await proc.exited;
+
+		if (exitCode !== 0) {
+			throw new Error(`Help command exited with code ${exitCode}`);
+		}
+
+		return undefined;
+	},
+});

package/src/cmd/index.ts

@@ -8,6 +8,7 @@ export async function discoverCommands(): Promise<CommandDefinition[]> {
 		import('./build').then((m) => m.command),
 		import('./cloud').then((m) => m.command),
 		import('./dev').then((m) => m.command),
+		import('./help').then((m) => m.command),
 		import('./profile').then((m) => m.command),
 		import('./project').then((m) => m.command),
 		import('./repl').then((m) => m.command),

package/src/cmd/profile/create.ts

@@ -24,9 +24,9 @@ export const createCommand = createSubcommand({
 	aliases: ['new'],
 	idempotent: false,
 	examples: [
-		getCommand('profile create production'),
-		getCommand('profile create staging --switch'),
-		getCommand('profile create development'),
+		{ command: getCommand('profile create production'), description: 'Create new item' },
+		{ command: getCommand('profile create staging --switch'), description: 'Use switch option' },
+		{ command: getCommand('profile create development'), description: 'Create new item' },
 	],
 	schema: {
 		args: z

package/src/cmd/profile/delete.ts

@@ -13,9 +13,12 @@ export const deleteCommand = createSubcommand({
 	idempotent: false,
 	aliases: ['remove', 'rm', 'del'],
 	examples: [
-		getCommand('profile delete staging'),
-		getCommand('profile delete old-dev --confirm'),
-		getCommand('profile delete'),
+		{ command: getCommand('profile delete staging'), description: 'Delete item' },
+		{
+			command: getCommand('profile delete old-dev --confirm'),
+			description: 'Use confirm option',
+		},
+		{ command: getCommand('profile delete'), description: 'Delete item' },
 	],
 	schema: {
 		args: z.object({

package/src/cmd/profile/index.ts

@@ -4,11 +4,19 @@ import { useCommand } from './use';
 import { listCommand } from './list';
 import { showCommand } from './show';
 import { deleteCommand } from './delete';
+import { getCommand } from '../../command-prefix';
 
 export const command = createCommand({
 	name: 'profile',
 	description: 'Manage configuration profiles',
 	tags: ['read-only', 'fast'],
 	hidden: true,
+	examples: [
+		{ command: getCommand('profile list'), description: 'List all profiles' },
+		{
+			command: getCommand('profile use production'),
+			description: 'Switch to production profile',
+		},
+	],
 	subcommands: [createProfileCmd, useCommand, listCommand, showCommand, deleteCommand],
 });

package/src/cmd/profile/list.ts

@@ -19,7 +19,10 @@ export const listCommand = createSubcommand({
 	tags: ['read-only', 'fast'],
 	idempotent: true,
 	aliases: ['ls'],
-	examples: [getCommand('profile list'), getCommand('profile ls')],
+	examples: [
+		{ command: getCommand('profile list'), description: 'List items' },
+		{ command: getCommand('profile ls'), description: 'List items' },
+	],
 	schema: {
 		response: ProfileListResponseSchema,
 	},

package/src/cmd/profile/show.ts

@@ -14,9 +14,12 @@ export const showCommand = createSubcommand({
 	tags: ['read-only', 'fast'],
 	aliases: ['current'],
 	examples: [
-		getCommand('profile show'),
-		getCommand('profile show production'),
-		getCommand('profile show staging --json'),
+		{ command: getCommand('profile show'), description: 'Show details' },
+		{ command: getCommand('profile show production'), description: 'Show details' },
+		{
+			command: getCommand('profile show staging --json'),
+			description: 'Show output in JSON format',
+		},
 	],
 	schema: {
 		args: z

package/src/cmd/profile/use.ts

@@ -11,9 +11,9 @@ export const useCommand = createSubcommand({
 	aliases: ['switch'],
 	idempotent: true,
 	examples: [
-		getCommand('profile use production'),
-		getCommand('profile switch staging'),
-		getCommand('profile use'),
+		{ 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' },
 	],
 	schema: {
 		args: z.object({

package/src/cmd/project/create.ts

@@ -24,11 +24,17 @@ export const createProjectSubcommand = createSubcommand({
 	optional: { auth: true, org: true, region: true },
 	requires: { apiClient: true },
 	examples: [
-		getCommand('project create'),
-		getCommand('project create --name my-ai-agent'),
-		getCommand('project create --name customer-service-bot --dir ~/projects/agent'),
-		getCommand('project create --template basic --no-install'),
-		getCommand('project new --no-register'),
+		{ command: getCommand('project create'), description: 'Create new item' },
+		{ command: getCommand('project create --name my-ai-agent'), description: 'Create new item' },
+		{
+			command: getCommand('project create --name customer-service-bot --dir ~/projects/agent'),
+			description: 'Create new item',
+		},
+		{
+			command: getCommand('project create --template basic --no-install'),
+			description: 'Use no install option',
+		},
+		{ command: getCommand('project new --no-register'), description: 'Use no register option' },
 	],
 	schema: {
 		options: z.object({

package/src/cmd/project/delete.ts

@@ -13,12 +13,21 @@ export const deleteSubcommand = createSubcommand({
 	requires: { auth: true, apiClient: true },
 	idempotent: false,
 	examples: [
-		getCommand('project delete'),
-		getCommand('project delete proj_abc123def456'),
-		getCommand('project delete proj_abc123def456 --confirm'),
-		getCommand('project rm proj_abc123def456'),
-		getCommand('--explain project delete proj_abc123def456'),
-		getCommand('--dry-run project delete proj_abc123def456'),
+		{ command: getCommand('project delete'), description: 'Delete item' },
+		{ command: getCommand('project delete proj_abc123def456'), description: 'Delete item' },
+		{
+			command: getCommand('project delete proj_abc123def456 --confirm'),
+			description: 'Use confirm option',
+		},
+		{ command: getCommand('project rm proj_abc123def456'), description: 'Delete item' },
+		{
+			command: getCommand('--explain project delete proj_abc123def456'),
+			description: 'Delete item',
+		},
+		{
+			command: getCommand('--dry-run project delete proj_abc123def456'),
+			description: 'Delete item',
+		},
 	],
 	schema: {
 		args: z.object({

package/src/cmd/project/download.ts

@@ -13,9 +13,13 @@ import { tmpdir } from 'node:os';
 import { finished } from 'node:stream/promises';
 import { createGunzip } from 'node:zlib';
 import { extract, type Headers } from 'tar-fs';
-import type { Logger } from '@agentuity/core';
+import { StructuredError, type Logger } from '@agentuity/core';
 import * as tui from '../../tui';
 import { downloadWithSpinner } from '../../download';
+import { generateLLMPrompt as generateCLIPrompt } from '../ai/prompt/llm';
+import { generateLLMPrompt as generateAgentPrompt } from '../ai/prompt/agent';
+import { generateLLMPrompt as generateWebPrompt } from '../ai/prompt/web';
+import { generateLLMPrompt as generateAPIPrompt } from '../ai/prompt/api';
 import type { TemplateInfo } from './templates';
 
 const GITHUB_REPO = 'agentuity/sdk';
@@ -38,9 +42,16 @@ interface SetupOptions {
 	logger: Logger;
 }
 
+const TemplateDirectoryNotFoundError = StructuredError('TemplateDirectoryNotFoundError')<{
+	directory: string;
+}>();
+
 async function cleanup(sourceDir: string, dest: string) {
 	if (!existsSync(sourceDir)) {
-		throw new Error(`Template directory not found: ${sourceDir}`);
+		throw new TemplateDirectoryNotFoundError({
+			directory: sourceDir,
+			message: `Template directory not found: ${sourceDir}`,
+		});
 	}
 
 	tui.spinner(`📦 Copying template files...`, async () => {
@@ -68,7 +79,10 @@ export async function downloadTemplate(options: DownloadOptions): Promise<void>
 		const sourceDir = resolve(join(templateDir, template.directory));
 
 		if (!existsSync(sourceDir)) {
-			throw new Error(`Template directory not found: ${sourceDir}`);
+			throw new TemplateDirectoryNotFoundError({
+				directory: sourceDir,
+				message: `Template directory not found: ${sourceDir}`,
+			});
 		}
 
 		return cleanup(sourceDir, dest);
@@ -258,6 +272,24 @@ export async function setupProject(options: SetupOptions): Promise<void> {
 			clearOnSuccess: true,
 		});
 	}
+
+	// generate and write the AGENTS.md for the cli
+	const cliDir = join(dest, 'node_modules', '@agentuity', 'cli');
+	if (existsSync(cliDir)) {
+		const agentFile = join(cliDir, 'AGENTS.md');
+		const prompt = generateCLIPrompt();
+		await Bun.write(agentFile, prompt);
+	}
+
+	// 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 agentsAPIsFile = join(dest, 'src', 'apis', 'AGENTS.md');
+	await Bun.write(agentsAPIsFile, generateAPIPrompt());
+
+	const agentsWebFile = join(dest, 'src', 'web', 'AGENTS.md');
+	await Bun.write(agentsWebFile, generateWebPrompt());
 }
 
 async function replaceInFiles(dir: string, projectName: string, dirName: string): Promise<void> {

package/src/cmd/project/index.ts

@@ -3,10 +3,15 @@ import { createProjectSubcommand } from './create';
 import { listSubcommand } from './list';
 import { deleteSubcommand } from './delete';
 import { showSubcommand } from './show';
+import { getCommand } from '../../command-prefix';
 
 export const command = createCommand({
 	name: 'project',
 	description: 'Project related commands',
 	tags: ['fast', 'requires-auth'],
+	examples: [
+		{ command: getCommand('project create my-agent'), description: 'Create a new project' },
+		{ command: getCommand('project list'), description: 'List all projects' },
+	],
 	subcommands: [createProjectSubcommand, listSubcommand, deleteSubcommand, showSubcommand],
 });

package/src/cmd/project/list.ts

@@ -24,9 +24,9 @@ export const listSubcommand = createSubcommand({
 		response: ProjectListResponseSchema,
 	},
 	examples: [
-		getCommand('project list'),
-		getCommand('--json project list'),
-		getCommand('project ls'),
+		{ 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' },
 	],
 
 	async handler(ctx) {

package/src/cmd/project/show.ts

@@ -19,9 +19,12 @@ export const showSubcommand = createSubcommand({
 	tags: ['read-only', 'fast', 'requires-auth', 'requires-project'],
 	requires: { auth: true, apiClient: true },
 	examples: [
-		getCommand('project show proj_abc123def456'),
-		getCommand('--json project show proj_abc123def456'),
-		getCommand('project get proj_abc123def456'),
+		{ command: getCommand('project show proj_abc123def456'), description: 'Show details' },
+		{
+			command: getCommand('--json project show proj_abc123def456'),
+			description: 'Show output in JSON format',
+		},
+		{ command: getCommand('project get proj_abc123def456'), description: 'Get item details' },
 	],
 	schema: {
 		args: z.object({

package/src/cmd/project/templates.ts

@@ -1,3 +1,5 @@
+import { StructuredError } from '@agentuity/core';
+
 const GITHUB_REPO = 'agentuity/sdk';
 const GITHUB_BRANCH = 'main';
 const TEMPLATES_JSON_PATH = 'templates/templates.json';
@@ -13,6 +15,9 @@ interface TemplatesManifest {
 	templates: TemplateInfo[];
 }
 
+const TemplateMissingConfigurationError = StructuredError('TemplateMissingConfigurationError');
+const TemplateDownloadError = StructuredError('TemplateDownloadError')<{ status: number }>();
+
 export async function fetchTemplates(localDir?: string, branch?: string): Promise<TemplateInfo[]> {
 	// Load from local directory if provided
 	if (localDir) {
@@ -22,7 +27,9 @@ export async function fetchTemplates(localDir?: string, branch?: string): Promis
 		const file = Bun.file(manifestPath);
 
 		if (!(await file.exists())) {
-			throw new Error(`templates.json not found at ${manifestPath}`);
+			throw new TemplateMissingConfigurationError({
+				message: `templates.json not found at ${manifestPath}`,
+			});
 		}
 
 		const manifest = (await file.json()) as TemplatesManifest;
@@ -40,7 +47,10 @@ export async function fetchTemplates(localDir?: string, branch?: string): Promis
 
 	const response = await fetch(url, { headers });
 	if (!response.ok) {
-		throw new Error(`Failed to fetch templates: ${response.statusText}`);
+		throw new TemplateDownloadError({
+			status: response.status,
+			message: `Failed to fetch templates: ${response.statusText}`,
+		});
 	}
 
 	const manifest = (await response.json()) as TemplatesManifest;

package/src/cmd/repl/index.ts

@@ -9,7 +9,7 @@ export const command = createCommand({
 	description: 'interactive REPL for testing',
 	tags: ['slow'],
 	idempotent: false,
-	examples: [getCommand('repl')],
+	examples: [{ command: getCommand('repl'), description: 'Run repl command' }],
 
 	async handler() {
 		// Define test commands

package/src/cmd/version/index.ts

@@ -11,7 +11,10 @@ export const command = createCommand({
 	name: 'version',
 	description: 'Display version information',
 	tags: ['read-only', 'fast'],
-	examples: [getCommand('version'), getCommand('--version')],
+	examples: [
+		{ command: getCommand('version'), description: 'Run version command' },
+		{ command: getCommand('--version'), description: 'Show version information' },
+	],
 	schema: {
 		response: VersionResponseSchema,
 	},

package/src/command-prefix.ts

@@ -17,11 +17,13 @@ export function getCommandPrefix(): string {
 	const scriptPath = process.argv[1] || '';
 	const normalized = path.normalize(scriptPath);
 
+	// If we have AGENTUITY_CLI_VERSION set we are running from compiled binary OR
 	// If the script is in node_modules/.bin or a global bin directory, it's likely global
 	const isGlobal =
-		normalized.includes(`${path.sep}bin${path.sep}`) &&
-		!normalized.includes(`${path.sep}node_modules${path.sep}`) &&
-		!normalized.includes(path.join('packages', 'cli', 'bin'));
+		process.env.AGENTUITY_CLI_VERSION ||
+		(normalized.includes(`${path.sep}bin${path.sep}`) &&
+			!normalized.includes(`${path.sep}node_modules${path.sep}`) &&
+			!normalized.includes(path.join('packages', 'cli', 'bin')));
 
 	if (isGlobal) {
 		cachedPrefix = 'agentuity';

package/src/config.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { existsSync, mkdirSync } from 'node:fs';
-import type { Logger } from '@agentuity/core';
+import { StructuredError, type Logger } from '@agentuity/core';
 import {
 	BuildMetadataSchema,
 	type BuildMetadata,
@@ -609,11 +609,13 @@ export async function createProjectConfig(dir: string, config: InitialProjectCon
 	await Bun.write(join(vscodeDir, 'settings.json'), JSON.stringify(settings, null, 2));
 }
 
+const BuildMetadataNotFoundError = StructuredError('BuildMetadataNotFoundError');
+
 export async function loadBuildMetadata(dir: string): Promise<BuildMetadata> {
 	const filename = join(dir, 'agentuity.metadata.json');
 	const file = Bun.file(filename);
 	if (!(await file.exists())) {
-		throw new Error(`couldn't find ${filename}`);
+		throw new BuildMetadataNotFoundError({ message: `couldn't find ${filename}` });
 	}
 	const buffer = await file.text();
 	const config = JSON.parse(buffer);