@agentuity/cli 1.0.34 → 1.0.36

package/src/cli.ts

@@ -291,12 +291,20 @@ function handleValidationError(
 					? errorMessages[0]
 					: 'Invalid options or arguments';
 
+			const suggestions = [`Run 'agentuity ${commandName} --help' for usage information`];
+			// Add agent-friendly hints when running from an AI agent
+			if (getExecutingAgent()) {
+				suggestions.push(
+					`Run 'agentuity ${commandName} --describe' to see the command schema as JSON`,
+					`Use --input '{...}' to pass arguments and options as a JSON object`
+				);
+			}
 			exitWithError(
 				{
 					code: ErrorCode.VALIDATION_FAILED,
 					message: primaryMessage,
 					details: errorMessages.length > 1 ? { errors: errorMessages } : undefined,
-					suggestions: [`Run 'agentuity ${commandName} --help' for usage information`],
+					suggestions,
 				},
 				baseCtx.logger,
 				baseCtx.options.errorFormat ?? 'text'
@@ -520,7 +528,13 @@ export async function createCLI(version: string): Promise<Command> {
 		.option('--explain', 'Show what the command would do without executing', false)
 		.option('--dry-run', 'Execute command without making changes', false)
 		.option('--validate', 'Validate arguments and options without executing', false)
-		.option('--ai-help', 'Show AI-optimized help in dashdash format', false);
+		.option('--ai-help', 'Show AI-optimized help in dashdash format', false)
+		.option('--input <json>', 'Pass arguments and options as a JSON object (for agents)')
+		.option('--describe', 'Output command schema as JSON for agent introspection', false)
+		.option(
+			'--fields <fields>',
+			'Filter JSON output to specified fields (comma-separated, dot notation for nested)'
+		);
 
 	const skipVersionCheckOption = program.createOption(
 		'--skip-version-check',
@@ -1035,6 +1049,18 @@ async function registerSubcommand(
 				cmd.help();
 			});
 
+		// Handle --describe for command-group nodes
+		cmd.action(async () => {
+			if (baseCtx.options.describe) {
+				const { extractSubcommandSchema } = await import('./schema-generator');
+				const schema = extractSubcommandSchema(subcommand);
+				const { outputJSON } = await import('./output');
+				outputJSON(schema);
+				return;
+			}
+			cmd.help();
+		});
+
 		// Don't add options to parent commands - only to leaf commands
 		return;
 	}
@@ -1216,6 +1242,28 @@ async function registerSubcommand(
 		const options = cmdObj.opts();
 		const args = rawArgs.slice(0, -1);
 
+		// Handle --describe mode: output command schema and exit
+		if (baseCtx.options.describe) {
+			const { extractSubcommandSchema } = await import('./schema-generator');
+			const schema = extractSubcommandSchema(subcommand);
+			const { outputJSON } = await import('./output');
+			outputJSON(schema);
+			return;
+		}
+
+		// One-time hint for agents about structured input/output features
+		// Emitted on stderr so it doesn't interfere with --json stdout
+		const detectedAgent = getExecutingAgent();
+		if (detectedAgent) {
+			const { hasAgentSeenInputHint, markAgentInputHintSeen } = await import('./cache');
+			if (!hasAgentSeenInputHint(detectedAgent)) {
+				markAgentInputHintSeen(detectedAgent);
+				console.error(
+					`[agent] This CLI supports structured I/O for agents: --input <json> (structured input), --describe (schema introspection), --fields (output filtering). Run --ai-help for details.`
+				);
+			}
+		}
+
 		// Merge global --org-id and --project-id into subcommand options when the schema
 		// defines these fields. Global options (program-level) capture the values first,
 		// so subcommand-level options may not have them. Only merge when the user
@@ -1415,9 +1463,13 @@ async function registerSubcommand(
 				try {
 					// Check if command uses stdin (don't auto-confirm if it does)
 					const usesStdin = subcommand.tags?.includes('uses-stdin') ?? false;
-					const input = await buildValidationInputAsync(subcommand.schema, args, options, {
-						usesStdin,
-					});
+					const input = await buildValidationInputAsync(
+						subcommand.schema,
+						args,
+						options,
+						{ usesStdin },
+						baseCtx.options.input
+					);
 					const ctx: Record<string, unknown> = {
 						...baseCtx,
 						config: {
@@ -1705,9 +1757,15 @@ async function registerSubcommand(
 				try {
 					// Check if command uses stdin (don't auto-confirm if it does)
 					const usesStdin = subcommand.tags?.includes('uses-stdin') ?? false;
-					const input = await buildValidationInputAsync(subcommand.schema, args, options, {
-						usesStdin,
-					});
+					const input = await buildValidationInputAsync(
+						subcommand.schema,
+						args,
+						options,
+						{
+							usesStdin,
+						},
+						baseCtx.options.input
+					);
 					const ctx: Record<string, unknown> = {
 						...baseCtx,
 						config: auth
@@ -1969,9 +2027,15 @@ async function registerSubcommand(
 				try {
 					// Check if command uses stdin (don't auto-confirm if it does)
 					const usesStdin = subcommand.tags?.includes('uses-stdin') ?? false;
-					const input = await buildValidationInputAsync(subcommand.schema, args, options, {
-						usesStdin,
-					});
+					const input = await buildValidationInputAsync(
+						subcommand.schema,
+						args,
+						options,
+						{
+							usesStdin,
+						},
+						baseCtx.options.input
+					);
 					const ctx: Record<string, unknown> = {
 						...baseCtx,
 					};
@@ -2157,6 +2221,15 @@ export async function registerCommands(
 
 			if (cmdDef.handler) {
 				cmd.action(async () => {
+					// Handle --describe mode: output command schema and exit
+					if (baseCtx.options.describe) {
+						const { extractCommandSchema } = await import('./schema-generator');
+						const schema = extractCommandSchema(cmdDef);
+						const { outputJSON } = await import('./output');
+						outputJSON(schema);
+						return;
+					}
+
 					if (cmdDef.banner) {
 						showBanner();
 					}

package/src/cmd/ai/intro.ts

@@ -31,6 +31,7 @@ The Agentuity CLI is designed to be agent-friendly. Here are the key commands:
 
 ### Discovery & Introspection
 \`\`\`bash
+${getCommand('<command> --describe')}     # Get command schema as JSON (args, options, response)
 ${getCommand('--help=json')}              # Get complete CLI schema as JSON
 ${getCommand('ai capabilities show')}     # List all capabilities and workflows
 ${getCommand('ai schema show')}           # Detailed command metadata
@@ -61,22 +62,41 @@ ${getCommand('env set KEY value --secret')} # Set secrets (encrypted)
 
 ## Best Practices for AI Agents
 
-1. **Always use \`--json\` for machine-readable output**
+1. **Use \`--input <json>\` to pass arguments and options as a single JSON object**
    \`\`\`bash
-   ${getCommand('--json project list')}
+   ${getCommand('cloud sandbox create --input \'{"runtime":"bun:1","memory":"1Gi","network":true}\'')}
+   ${getCommand('cloud kv set --input \'{"namespace":"ns","key":"k","value":"v","ttl":300}\'')}
+   \`\`\`
+   JSON keys must be the **camelCase schema keys** shown by \`--describe\` output (not kebab-case flag names). For example, the flag \`--dry-run\` becomes \`dryRun\` in JSON. CLI flags take precedence over --input values.
+
+2. **Use \`--describe\` to introspect what a command accepts before calling it**
+   \`\`\`bash
+   ${getCommand('cloud sandbox create --describe')}
    \`\`\`
+   Returns the full command schema as JSON: arguments, options (with types), response shape, requirements, and examples. No authentication required.
 
-2. **Use \`--explain\` before destructive operations**
+3. **Use \`--fields\` with \`--json\` to limit output and protect your context window**
    \`\`\`bash
-   ${getCommand('--explain cloud deployment delete <id>')}
+   ${getCommand('--json --fields "id,name,status" cloud deployment list')}
    \`\`\`
+   Comma-separated field names, supports dot notation for nested fields (e.g., \`properties.title\`).
 
-3. **Use \`--dry-run\` to test commands safely**
+4. **Always use \`--json\` for machine-readable output**
+   \`\`\`bash
+   ${getCommand('--json project list')}
+   \`\`\`
+
+5. **Use \`--dry-run\` to test commands safely before mutating**
    \`\`\`bash
    ${getCommand('--dry-run cloud deploy')}
    \`\`\`
 
-4. **Check requirements before running commands**
+6. **Use \`--validate\` to check inputs without executing**
+   \`\`\`bash
+   ${getCommand('--validate cloud kv set --input \'{"namespace":"ns","key":"k","value":"v"}\'')}
+   \`\`\`
+
+7. **Check requirements before running commands**
    - Many commands require authentication (\`${getCommand('auth login')}\`)
    - Project commands require an \`agentuity.json\` file in the current directory
 

package/src/cmd/cloud/deploy.ts

@@ -1226,6 +1226,11 @@ export const deploySubcommand = createSubcommand({
 				});
 			}
 
+			// Trigger TLS certificate provisioning for custom domains (fire-and-forget)
+			if (project.deployment?.domains?.length) {
+				void domain.triggerTLSProvisioning(project.deployment.domains);
+			}
+
 			// Write final report on success
 			if (opts.reportFile) {
 				await collector.forceWrite();

package/src/cmd/cloud/keyvalue/create-namespace.ts

@@ -13,14 +13,14 @@ export const createNamespaceSubcommand = createCommand({
 	optional: { project: true },
 	examples: [
 		{
-			command: getCommand('kv create-namespace production'),
+			command: getCommand('cloud kv create-namespace production'),
 			description: 'Create production namespace',
 		},
 		{
-			command: getCommand('kv create staging'),
+			command: getCommand('cloud kv create staging'),
 			description: 'Create staging namespace (using alias)',
 		},
-		{ command: getCommand('kv create cache'), description: 'Create cache namespace' },
+		{ command: getCommand('cloud kv create cache'), description: 'Create cache namespace' },
 	],
 	schema: {
 		args: z.object({

package/src/cmd/cloud/keyvalue/delete-namespace.ts

@@ -14,21 +14,23 @@ export const deleteNamespaceSubcommand = createCommand({
 	optional: { project: true },
 	examples: [
 		{
-			command: getCommand('kv delete-namespace staging'),
+			command: getCommand('cloud kv delete-namespace staging'),
 			description: 'Delete staging namespace (interactive)',
 		},
 		{
-			command: getCommand('kv rm-namespace cache --confirm'),
+			command: getCommand('cloud kv rm-namespace cache --confirm'),
 			description: 'Delete cache without confirmation',
 		},
 		{
-			command: getCommand('kv delete-namespace production --confirm'),
+			command: getCommand('cloud kv delete-namespace production --confirm'),
 			description: 'Force delete production',
 		},
 	],
 	schema: {
 		args: z.object({
 			name: z.string().min(1).max(64).describe('the namespace name'),
+		}),
+		options: z.object({
 			confirm: z
 				.boolean()
 				.optional()
@@ -43,10 +45,10 @@ export const deleteNamespaceSubcommand = createCommand({
 	},
 
 	async handler(ctx) {
-		const { args } = ctx;
+		const { args, opts } = ctx;
 		const kv = await createStorageAdapter(ctx);
 
-		if (!args.confirm) {
+		if (!opts?.confirm) {
 			if (!process.stdin.isTTY) {
 				tui.fatal(
 					'No TTY and --confirm is not set. Refusing to delete',

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

@@ -19,10 +19,16 @@ export const deleteSubcommand = createCommand({
 	requires: { auth: true, region: true },
 	optional: { project: true },
 	examples: [
-		{ command: getCommand('kv delete production user:123'), description: 'Delete user data' },
-		{ command: getCommand('kv delete cache session:abc'), description: 'Delete cached session' },
 		{
-			command: getCommand('kv rm staging cache:homepage'),
+			command: getCommand('cloud kv delete production user:123'),
+			description: 'Delete user data',
+		},
+		{
+			command: getCommand('cloud kv delete cache session:abc'),
+			description: 'Delete cached session',
+		},
+		{
+			command: getCommand('cloud kv rm staging cache:homepage'),
 			description: 'Delete homepage cache (using alias)',
 		},
 	],

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

@@ -18,9 +18,12 @@ export const getSubcommand = createCommand({
 	requires: { auth: true, region: true },
 	optional: { project: true },
 	examples: [
-		{ command: getCommand('kv get production user:123'), description: 'Get user data' },
-		{ command: getCommand('kv get cache session:abc'), description: 'Get cached session' },
-		{ command: getCommand('kv get staging cache:homepage'), description: 'Get homepage cache' },
+		{ command: getCommand('cloud kv get production user:123'), description: 'Get user data' },
+		{ command: getCommand('cloud kv get cache session:abc'), description: 'Get cached session' },
+		{
+			command: getCommand('cloud kv get staging cache:homepage'),
+			description: 'Get homepage cache',
+		},
 	],
 	schema: {
 		args: z.object({

package/src/cmd/cloud/keyvalue/keys.ts

@@ -17,9 +17,15 @@ export const keysSubcommand = createCommand({
 	optional: { project: true },
 	idempotent: true,
 	examples: [
-		{ command: getCommand('kv keys production'), description: 'List all keys in production' },
-		{ command: getCommand('kv ls cache'), description: 'List all cached keys (using alias)' },
-		{ command: getCommand('kv list staging'), description: 'List all staging keys' },
+		{
+			command: getCommand('cloud kv keys production'),
+			description: 'List all keys in production',
+		},
+		{
+			command: getCommand('cloud kv ls cache'),
+			description: 'List all cached keys (using alias)',
+		},
+		{ command: getCommand('cloud kv list staging'), description: 'List all staging keys' },
 	],
 	schema: {
 		args: z.object({

package/src/cmd/cloud/keyvalue/list-namespaces.ts

@@ -13,9 +13,9 @@ export const listNamespacesSubcommand = createCommand({
 	requires: { auth: true, region: true },
 	optional: { project: true },
 	examples: [
-		{ command: getCommand('kv list-namespaces'), description: 'List all namespaces' },
-		{ command: getCommand('kv namespaces'), description: 'List namespaces (using alias)' },
-		{ command: getCommand('kv ns'), description: 'List namespaces (short alias)' },
+		{ command: getCommand('cloud kv list-namespaces'), description: 'List all namespaces' },
+		{ command: getCommand('cloud kv namespaces'), description: 'List namespaces (using alias)' },
+		{ command: getCommand('cloud kv ns'), description: 'List namespaces (short alias)' },
 	],
 	schema: {
 		options: z.object({

package/src/cmd/cloud/keyvalue/repl.ts

@@ -13,7 +13,9 @@ export const replSubcommand = createCommand({
 	idempotent: false,
 	requires: { auth: true, region: true },
 	optional: { project: true },
-	examples: [{ command: getCommand('kv repl'), description: 'Start interactive KV session' }],
+	examples: [
+		{ command: getCommand('cloud kv repl'), description: 'Start interactive KV session' },
+	],
 
 	async handler(ctx) {
 		showBanner(undefined, true);

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

@@ -25,14 +25,17 @@ export const searchSubcommand = createCommand({
 	idempotent: true,
 	examples: [
 		{
-			command: getCommand('kv search production user'),
+			command: getCommand('cloud kv search production user'),
 			description: 'Find all user-related keys',
 		},
 		{
-			command: getCommand('kv search cache session'),
+			command: getCommand('cloud kv search cache session'),
 			description: 'Find all session keys in cache',
 		},
-		{ command: getCommand('kv search staging config'), description: 'Find all config keys' },
+		{
+			command: getCommand('cloud kv search staging config'),
+			description: 'Find all config keys',
+		},
 	],
 	schema: {
 		args: z.object({

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

@@ -24,16 +24,16 @@ export const setSubcommand = createCommand({
 	examples: [
 		{
 			command: getCommand(
-				'kv set production user:123 \'{"name":"Alice","email":"alice@example.com"}\''
+				'cloud kv set production user:123 \'{"name":"Alice","email":"alice@example.com"}\''
 			),
 			description: 'Store user data',
 		},
 		{
-			command: getCommand('kv set cache session:abc "session-data-here" --ttl 3600'),
+			command: getCommand('cloud kv set cache session:abc "session-data-here" --ttl 3600'),
 			description: 'Store session with 1h TTL',
 		},
 		{
-			command: getCommand('kv set staging cache:homepage "<!DOCTYPE html>..." --ttl 600'),
+			command: getCommand('cloud kv set staging cache:homepage "<!DOCTYPE html>..." --ttl 600'),
 			description: 'Cache homepage for 10m',
 		},
 	],
@@ -42,6 +42,8 @@ export const setSubcommand = createCommand({
 			namespace: z.string().min(1).max(64).describe('the namespace name'),
 			key: z.string().min(1).max(64).describe('the key name'),
 			value: z.string().min(1).describe('the value'),
+		}),
+		options: z.object({
 			ttl: z.coerce
 				.number()
 				.refine((val) => val >= 0, {
@@ -54,11 +56,11 @@ export const setSubcommand = createCommand({
 	},
 
 	async handler(ctx) {
-		const { args, options } = ctx;
+		const { args, opts, options } = ctx;
 		const started = Date.now();
 		const storage = await createStorageAdapter(ctx);
 		const contentType = isPossiblyJSON(args.value) ? 'application/json' : 'text/plain';
-		const ttl = args.ttl;
+		const ttl = opts?.ttl;
 		await storage.set(args.namespace, args.key, args.value, {
 			contentType,
 			ttl,

package/src/cmd/cloud/keyvalue/stats.ts

@@ -40,12 +40,15 @@ export const statsSubcommand = createCommand({
 	optional: { project: true },
 	idempotent: true,
 	examples: [
-		{ command: getCommand('kv stats'), description: 'Show stats for all namespaces' },
+		{ command: getCommand('cloud kv stats'), description: 'Show stats for all namespaces' },
 		{
-			command: getCommand('kv stats production'),
+			command: getCommand('cloud kv stats production'),
 			description: 'Show stats for production namespace',
 		},
-		{ command: getCommand('kv stats cache'), description: 'Show stats for cache namespace' },
+		{
+			command: getCommand('cloud kv stats cache'),
+			description: 'Show stats for cache namespace',
+		},
 	],
 	schema: {
 		args: z.object({

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

@@ -3,6 +3,7 @@ import { createSubcommand, createCommand } from '../../../types';
 import { getCommand } from '../../../command-prefix';
 import { saveRegion, clearRegion } from '../../../config';
 import * as tui from '../../../tui';
+import { listSubcommand } from './list';
 
 const selectCommand = createSubcommand({
 	name: 'select',
@@ -150,8 +151,9 @@ export const regionSubcommand = createCommand({
 	description: 'Manage default cloud region preference',
 	tags: ['fast'],
 	examples: [
+		{ command: getCommand('cloud region list'), description: 'List available regions' },
 		{ command: getCommand('cloud region select'), description: 'Set default region' },
 		{ command: getCommand('cloud region current'), description: 'Show current default' },
 	],
-	subcommands: [selectCommand, unselectCommand, currentCommand],
+	subcommands: [listSubcommand, selectCommand, unselectCommand, currentCommand],
 });

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

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import { createSubcommand } from '../../../types';
+import { getCommand } from '../../../command-prefix';
+import * as tui from '../../../tui';
+
+const RegionSchema = z.object({
+	region: z.string().describe('Region code'),
+	description: z.string().describe('Human-readable region description'),
+	default: z.boolean().describe('Whether this is the default region'),
+});
+
+export const listSubcommand = createSubcommand({
+	name: 'list',
+	description: 'List available cloud regions',
+	aliases: ['ls'],
+	tags: ['read-only', 'fast', 'requires-auth'],
+	requires: { auth: true, regions: true },
+	idempotent: true,
+	examples: [
+		{ command: getCommand('cloud region list'), description: 'List all available regions' },
+		{
+			command: getCommand('cloud region ls'),
+			description: 'List all available regions (short alias)',
+		},
+		{
+			command: getCommand('--json cloud region list'),
+			description: 'List regions in JSON format',
+		},
+	],
+	schema: {
+		response: z.array(RegionSchema),
+	},
+
+	async handler(ctx) {
+		const { regions, options, config } = ctx;
+		const defaultRegion = config?.preferences?.region ?? null;
+
+		const result = regions.map((r) => ({
+			region: r.region,
+			description: r.description,
+			default: r.region === defaultRegion,
+		}));
+
+		if (!options.json) {
+			tui.info(`Regions (${regions.length})`);
+
+			const tableData = regions.map((r) => ({
+				Code: r.region,
+				Description: r.description,
+				Default: r.region === defaultRegion ? 'Yes' : '',
+			}));
+
+			tui.table(tableData, [
+				{ name: 'Code', alignment: 'left' },
+				{ name: 'Description', alignment: 'left' },
+				{ name: 'Default', alignment: 'center' },
+			]);
+		}
+
+		return result;
+	},
+});

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

@@ -18,6 +18,10 @@ const TaskCreateResponseSchema = z.object({
 		status: z.string().describe('Task status'),
 		priority: z.string().describe('Task priority'),
 		created_at: z.string().describe('Creation timestamp'),
+		tags: z
+			.array(z.object({ id: z.string(), name: z.string() }))
+			.optional()
+			.describe('Tags attached to the task'),
 	}),
 	attachment: z
 		.object({
@@ -47,6 +51,12 @@ export const createSubcommand = createCommand({
 			),
 			description: 'Create a feature with priority and description',
 		},
+		{
+			command: getCommand(
+				'cloud task create "Fix login bug" --type bug --tag sandbox --tag regression'
+			),
+			description: 'Create a task with tags (auto-creates tags that do not exist)',
+		},
 		{
 			command: getCommand(
 				'cloud task create "Q1 Planning" --type epic --created-id agent_001 --metadata \'{"team":"engineering"}\''
@@ -90,6 +100,10 @@ export const createSubcommand = createCommand({
 				.describe('initial task status (default: open)'),
 			parentId: z.string().optional().describe('parent task ID for subtasks'),
 			assignedId: z.string().optional().describe('ID of the assigned agent or user'),
+			tag: z
+				.array(z.string())
+				.optional()
+				.describe('tag name to attach (repeatable, auto-creates missing tags)'),
 			metadata: z.string().optional().describe('JSON metadata object'),
 			file: z.string().optional().describe('file path to attach to the task'),
 		}),
@@ -172,6 +186,7 @@ export const createSubcommand = createCommand({
 			status: opts.status as TaskStatus,
 			parent_id: opts.parentId,
 			assigned_id: opts.assignedId,
+			tag_ids: opts.tag,
 			metadata,
 		});
 
@@ -228,6 +243,10 @@ export const createSubcommand = createCommand({
 				tableData['Description'] = task.description;
 			}
 
+			if (task.tags?.length) {
+				tableData['Tags'] = task.tags.map((t) => t.name).join(', ');
+			}
+
 			if (project) {
 				tableData['Project'] = project.name;
 			}
@@ -248,6 +267,9 @@ export const createSubcommand = createCommand({
 				status: task.status,
 				priority: task.priority,
 				created_at: task.created_at,
+				...(task.tags?.length
+					? { tags: task.tags.map((t) => ({ id: t.id, name: t.name })) }
+					: {}),
 			},
 			...(attachmentInfo ? { attachment: attachmentInfo } : {}),
 			durationMs,

package/src/cmd/project/domain/check.ts

@@ -7,7 +7,6 @@ import { isJSONMode } from '../../../output';
 import {
 	checkCustomDomainForDNS,
 	isSuccess,
-	isPending,
 	isMissing,
 	isMisconfigured,
 	isError,
@@ -92,9 +91,6 @@ export const checkSubcommand = createSubcommand({
 				status = tui.colorSuccess(`${tui.ICONS.success} Configured`);
 				statusRaw = 'configured';
 				success = true;
-			} else if (isPending(r)) {
-				status = tui.colorWarning('⏳ Pending');
-				statusRaw = 'pending';
 			} else if (isMisconfigured(r)) {
 				status = tui.colorWarning(`${tui.ICONS.warning} ${r.misconfigured}`);
 				statusRaw = 'misconfigured';