@agentuity/cli 1.0.33 → 1.0.35

package/src/ai-help.ts

@@ -91,6 +91,7 @@ function buildContent(schema: CLISchema, config: DashdashConfig): string {
 	const sections = [
 		buildHeader(config),
 		buildWhenToUse(),
+		buildAgentOptimizedIO(),
 		buildQuickReference(schema),
 		buildCommandReference(schema),
 		buildGlobalOptions(schema),
@@ -127,6 +128,66 @@ Do NOT use this CLI for:
 - Direct database queries (use the SDK or cloud console)`;
 }
 
+/**
+ * Build Agent-Optimized Input/Output section
+ */
+function buildAgentOptimizedIO(): string {
+	return `## Agent-Optimized Input/Output
+
+This CLI provides structured input and output modes designed for AI agents:
+
+### Structured Input: \`--input <json>\`
+
+Pass all arguments and options as a single JSON object instead of individual flags:
+
+\`\`\`bash
+# Instead of individual flags:
+agentuity cloud sandbox create --runtime "bun:1" --memory "1Gi" --network --port 8080
+
+# Use structured JSON input:
+agentuity cloud sandbox create --input '{"runtime":"bun:1","memory":"1Gi","network":true,"port":8080}'
+\`\`\`
+
+JSON keys map to argument and option names from the command schema. CLI flags take precedence over \`--input\` values.
+
+### Schema Introspection: \`--describe\`
+
+Discover what any command accepts at runtime without executing it:
+
+\`\`\`bash
+agentuity cloud sandbox create --describe
+# Returns: { "name": "create", "options": [...], "arguments": [...], "response": {...} }
+\`\`\`
+
+No authentication required. Use this to self-serve command schemas instead of reading documentation.
+
+### Output Field Filtering: \`--fields <fields>\`
+
+Limit JSON output to only the fields you need (protects context window):
+
+\`\`\`bash
+agentuity --json --fields "id,name,status" cloud deployment list
+\`\`\`
+
+Supports dot notation for nested fields (e.g., \`properties.title\`). Applies to arrays automatically.
+
+### Input Validation: \`--validate\`
+
+Validate your input without executing the command:
+
+\`\`\`bash
+agentuity --validate cloud kv set --input '{"namespace":"ns","key":"k","value":"v"}'
+# Returns: { "valid": true, "command": "cloud kv set" }
+\`\`\`
+
+### Recommended Agent Workflow
+
+1. **Discover**: \`agentuity <command> --describe\` — learn what the command accepts
+2. **Validate**: \`agentuity --validate <command> --input '{...}'\` — check input before executing
+3. **Execute**: \`agentuity --json <command> --input '{...}' --fields "id,status"\` — run with structured I/O
+4. **Dry-run**: \`agentuity --dry-run <command> --input '{...}'\` — test mutating operations safely`;
+}
+
 /**
  * Build Quick Reference with 15-20 most common operations
  */

package/src/cache/agent-intro.ts

@@ -59,3 +59,57 @@ export function markAgentIntroSeen(agentId: string): void {
 		// Non-critical - intro tracking failure shouldn't block CLI
 	}
 }
+
+/**
+ * Ensure the agent_input_hint_seen table exists.
+ * Called lazily on first hint check.
+ */
+let hintTableCreated = false;
+function ensureHintTable(): void {
+	if (hintTableCreated) return;
+	try {
+		getDatabase().run(`
+			CREATE TABLE IF NOT EXISTS agent_input_hint_seen (
+				agent_id TEXT PRIMARY KEY,
+				first_seen_at INTEGER NOT NULL
+			)
+		`);
+		hintTableCreated = true;
+	} catch {
+		// Non-critical
+	}
+}
+
+/**
+ * Check if an agent has already seen the structured input hint.
+ * Returns true on error to avoid blocking CLI (assumes seen).
+ */
+export function hasAgentSeenInputHint(agentId: string): boolean {
+	try {
+		ensureHintTable();
+		const row = getDatabase()
+			.query<{ agent_id: string }, [string]>(
+				'SELECT agent_id FROM agent_input_hint_seen WHERE agent_id = ?'
+			)
+			.get(agentId);
+		return row !== null;
+	} catch {
+		return true;
+	}
+}
+
+/**
+ * Mark an agent as having seen the structured input hint.
+ * Silently fails on error (non-critical feature).
+ */
+export function markAgentInputHintSeen(agentId: string): void {
+	try {
+		ensureHintTable();
+		getDatabase().run(
+			'INSERT OR IGNORE INTO agent_input_hint_seen (agent_id, first_seen_at) VALUES (?, ?)',
+			[agentId, Date.now()]
+		);
+	} catch {
+		// Non-critical
+	}
+}

package/src/cache/index.ts

@@ -12,6 +12,11 @@ export {
 
 export { getCachedProject, setCachedProject, clearProjectCache } from './project-cache';
 
-export { hasAgentSeenIntro, markAgentIntroSeen } from './agent-intro';
+export {
+	hasAgentSeenIntro,
+	markAgentIntroSeen,
+	hasAgentSeenInputHint,
+	markAgentInputHintSeen,
+} from './agent-intro';
 
 export { getCachedUserInfo, setCachedUserInfo, clearCachedUserInfo } from './user-cache';

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/queue/consumers.ts

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+import { createCommand, createSubcommand } from '../../../types';
+import * as tui from '../../../tui';
+import { createQueueAPIClient, getQueueApiOptions } from './util';
+import { getCommand } from '../../../command-prefix';
+import { listConsumers, type Consumer } from '@agentuity/server';
+
+const ConsumersListResponseSchema = z.object({
+	consumers: z.array(
+		z.object({
+			id: z.string(),
+			client_id: z.string().nullable().optional(),
+			durable: z.boolean(),
+			connected: z.boolean(),
+			ip_address: z.string().nullable().optional(),
+			last_offset: z.number().nullable().optional(),
+		})
+	),
+});
+
+const listConsumersSubcommand = createSubcommand({
+	name: 'list',
+	aliases: ['ls'],
+	description: 'List consumers for a queue',
+	tags: ['read-only', 'fast', 'requires-auth'],
+	requires: { auth: true },
+	examples: [
+		{
+			command: getCommand('cloud queue consumers list my-queue'),
+			description: 'List queue consumers',
+		},
+	],
+	schema: {
+		args: z.object({
+			queue_name: z.string().min(1).describe('Queue name'),
+		}),
+		response: ConsumersListResponseSchema,
+	},
+	idempotent: true,
+
+	async handler(ctx) {
+		const { args, options } = ctx;
+		const client = await createQueueAPIClient(ctx);
+		const consumers = await listConsumers(client, args.queue_name, getQueueApiOptions(ctx));
+
+		if (!options.json) {
+			if (consumers.length === 0) {
+				tui.info('No consumers connected');
+			} else {
+				const tableData = consumers.map((c: Consumer) => ({
+					ID: c.id,
+					'Client ID': c.client_id || '-',
+					Durable: c.durable ? 'Yes' : 'No',
+					Connected: c.disconnected_at ? 'No' : 'Yes',
+					'IP Address': c.ip_address || '-',
+					'Last Offset': c.last_offset != null ? String(c.last_offset) : '-',
+				}));
+				tui.table(tableData, [
+					'ID',
+					'Client ID',
+					'Durable',
+					'Connected',
+					'IP Address',
+					'Last Offset',
+				]);
+			}
+		}
+
+		return {
+			consumers: consumers.map((c: Consumer) => ({
+				id: c.id,
+				client_id: c.client_id || null,
+				durable: c.durable,
+				connected: !c.disconnected_at,
+				ip_address: c.ip_address || null,
+				last_offset: c.last_offset ?? null,
+			})),
+		};
+	},
+});
+
+export const consumersSubcommand = createCommand({
+	name: 'consumers',
+	aliases: ['consumer'],
+	description: 'Manage queue consumers (WebSocket subscriptions)',
+	tags: ['requires-auth'],
+	requires: { auth: true },
+	examples: [
+		{
+			command: getCommand('cloud queue consumers list my-queue'),
+			description: 'List consumers',
+		},
+	],
+	subcommands: [listConsumersSubcommand],
+});
+
+export default consumersSubcommand;

package/src/cmd/cloud/queue/destinations.ts

@@ -18,6 +18,8 @@ const DestinationsListResponseSchema = z.object({
 	destinations: z.array(
 		z.object({
 			id: z.string(),
+			name: z.string(),
+			description: z.string().nullable().optional(),
 			destination_type: z.string(),
 			url: z.string(),
 			enabled: z.boolean(),
@@ -57,18 +59,21 @@ const listDestinationsSubcommand = createSubcommand({
 			} else {
 				const tableData = destinations.map((d: Destination) => ({
 					ID: d.id,
+					Name: d.name,
 					Type: d.destination_type,
 					URL: d.config.url,
 					Enabled: d.enabled ? 'Yes' : 'No',
 					Created: new Date(d.created_at).toLocaleString(),
 				}));
-				tui.table(tableData, ['ID', 'Type', 'URL', 'Enabled', 'Created']);
+				tui.table(tableData, ['ID', 'Name', 'Type', 'URL', 'Enabled', 'Created']);
 			}
 		}
 
 		return {
 			destinations: destinations.map((d: Destination) => ({
 				id: d.id,
+				name: d.name,
+				description: d.description ?? null,
 				destination_type: d.destination_type,
 				url: d.config.url,
 				enabled: d.enabled,
@@ -86,7 +91,7 @@ const createDestinationSubcommand = createSubcommand({
 	examples: [
 		{
 			command: getCommand(
-				'cloud queue destinations create my-queue --url https://example.com/webhook'
+				'cloud queue destinations create my-queue --name order-webhooks --url https://example.com/webhook'
 			),
 			description: 'Create a webhook destination',
 		},
@@ -96,6 +101,8 @@ const createDestinationSubcommand = createSubcommand({
 			queue_name: z.string().min(1).describe('Queue name'),
 		}),
 		options: z.object({
+			name: z.string().min(1).describe('Destination name'),
+			description: z.string().optional().describe('Destination description'),
 			url: z.string().url().describe('Webhook URL'),
 			method: z.string().default('POST').optional().describe('HTTP method (default: POST)'),
 			timeout: z.coerce.number().optional().describe('Request timeout in milliseconds'),
@@ -112,6 +119,8 @@ const createDestinationSubcommand = createSubcommand({
 				client,
 				args.queue_name,
 				{
+					name: opts.name,
+					description: opts.description,
 					destination_type: 'http',
 					config: {
 						url: opts.url,
@@ -125,6 +134,7 @@ const createDestinationSubcommand = createSubcommand({
 
 			if (!options.json) {
 				tui.success(`Created destination: ${destination.id}`);
+				console.log(`  Name:   ${destination.name}`);
 				console.log(`  URL:    ${destination.config.url}`);
 				console.log(`  Method: ${destination.config.method}`);
 			}
@@ -149,7 +159,7 @@ const updateDestinationSubcommand = createSubcommand({
 	requires: { auth: true },
 	examples: [
 		{
-			command: getCommand('cloud queue destinations update my-queue dest_abc123 --disabled'),
+			command: getCommand('cloud queue destinations update my-queue qdest_abc123 --disabled'),
 			description: 'Disable a destination',
 		},
 	],
@@ -159,6 +169,8 @@ const updateDestinationSubcommand = createSubcommand({
 			destination_id: z.string().min(1).describe('Destination ID'),
 		}),
 		options: z.object({
+			name: z.string().min(1).optional().describe('Destination name'),
+			description: z.string().optional().describe('Destination description'),
 			url: z.string().url().optional().describe('Webhook URL'),
 			method: z.string().optional().describe('HTTP method'),
 			timeout: z.coerce.number().optional().describe('Request timeout in milliseconds'),
@@ -173,10 +185,15 @@ const updateDestinationSubcommand = createSubcommand({
 		const client = await createQueueAPIClient(ctx);
 
 		const updateParams: {
+			name?: string;
+			description?: string | null;
 			config?: { url?: string; method?: string; timeout_ms?: number };
 			enabled?: boolean;
 		} = {};
 
+		if (opts.name !== undefined) updateParams.name = opts.name;
+		if (opts.description !== undefined) updateParams.description = opts.description || null;
+
 		if (opts.url || opts.method || opts.timeout !== undefined) {
 			updateParams.config = {};
 			if (opts.url) updateParams.config.url = opts.url;
@@ -202,6 +219,7 @@ const updateDestinationSubcommand = createSubcommand({
 
 		if (!options.json) {
 			tui.success(`Updated destination: ${destination.id}`);
+			console.log(`  Name:    ${destination.name}`);
 			console.log(`  URL:     ${destination.config.url}`);
 			console.log(`  Enabled: ${destination.enabled ? 'Yes' : 'No'}`);
 		}

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

@@ -11,6 +11,7 @@ import { nackSubcommand } from './nack';
 import { dlqSubcommand } from './dlq';
 import { destinationsSubcommand } from './destinations';
 import { sourcesSubcommand } from './sources';
+import { consumersSubcommand } from './consumers';
 import { pauseSubcommand } from './pause';
 import { resumeSubcommand } from './resume';
 import { statsSubcommand } from './stats';
@@ -56,6 +57,7 @@ export const command = createCommand({
 		dlqSubcommand,
 		destinationsSubcommand,
 		sourcesSubcommand,
+		consumersSubcommand,
 		pauseSubcommand,
 		resumeSubcommand,
 		statsSubcommand,

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';