@agentuity/cli 1.0.34 → 1.0.35

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

package/src/domain.ts

@@ -14,14 +14,8 @@ interface DNSSuccess extends BaseDNSResult {
 	success: true;
 }
 
-interface DNSPending extends BaseDNSResult {
-	success: true;
-	pending: true;
-}
-
 interface DNSMissing extends BaseDNSResult {
 	success: false;
-	pending: false;
 }
 
 interface DNSError extends BaseDNSResult {
@@ -34,27 +28,23 @@ interface DNSMisconfigured extends BaseDNSResult {
 	misconfigured: string;
 }
 
-export type DNSResult = DNSSuccess | DNSPending | DNSMissing | DNSError | DNSMisconfigured;
-export type DNSFailed = DNSPending | DNSMissing | DNSError | DNSMisconfigured;
+export type DNSResult = DNSSuccess | DNSMissing | DNSError | DNSMisconfigured;
+export type DNSFailed = DNSMissing | DNSError | DNSMisconfigured;
 
 export function isMisconfigured(x: DNSResult): x is DNSMisconfigured {
 	return 'misconfigured' in x && !!x.misconfigured;
 }
 
 export function isMissing(x: DNSResult): x is DNSMissing {
-	return 'pending' in x && x.pending === false && 'success' in x && x.success === false;
+	return x.success === false && !('error' in x) && !('misconfigured' in x);
 }
 
 export function isError(x: DNSResult): x is DNSError {
 	return 'error' in x && !!x.error;
 }
 
-export function isPending(x: DNSResult): x is DNSPending {
-	return 'pending' in x && x.pending === true && x.success === true;
-}
-
 export function isSuccess(x: DNSResult): x is DNSSuccess {
-	return x.success === true && !('pending' in x) && !('error' in x) && !('misconfigured' in x);
+	return x.success === true;
 }
 
 const timeoutMs = 5000;
@@ -95,30 +85,6 @@ async function fetchDNSRecord(name: string, type: string): Promise<string | null
 	return records[0] ?? null;
 }
 
-/**
- * Check if a domain has a valid TLS certificate by making a HEAD request.
- * This also triggers Let's Encrypt certificate provisioning on first access.
- * Returns true if the TLS certificate is valid (any HTTP status code received).
- * Returns false if the certificate is not yet provisioned (timeout or TLS error).
- */
-async function checkTLSCertificate(domain: string): Promise<boolean> {
-	try {
-		await fetch(`https://${domain}`, {
-			method: 'HEAD',
-			signal: AbortSignal.timeout(timeoutMs),
-			redirect: 'manual',
-			// @ts-expect-error - cache is supported by Bun's fetch at runtime but missing from type definitions
-			cache: 'no-store',
-		});
-		// Any HTTP response means TLS handshake succeeded and certificate is valid
-		return true;
-	} catch {
-		// Timeout, TLS certificate error, connection refused, etc.
-		// All indicate the certificate is not yet provisioned
-		return false;
-	}
-}
-
 const LOCAL_DNS = 'agentuity.io';
 const PRODUCTION_DNS = 'agentuity.run';
 
@@ -197,25 +163,14 @@ export async function checkCustomDomainForDNS(
 
 				if (result) {
 					if (result === proxy) {
-						// DNS is correct — verify TLS certificate (also triggers Let's Encrypt provisioning)
-						const tlsValid = await checkTLSCertificate(domain);
-						if (tlsValid) {
-							return {
-								domain,
-								target: proxy,
-								aRecordTarget,
-								recordType: 'CNAME',
-								success: true,
-							} as DNSSuccess;
-						}
+						// DNS is correctly configured
 						return {
 							domain,
 							target: proxy,
 							aRecordTarget,
 							recordType: 'CNAME',
 							success: true,
-							pending: true,
-						} as DNSPending;
+						} as DNSSuccess;
 					}
 					return {
 						domain,
@@ -278,25 +233,14 @@ export async function checkCustomDomainForDNS(
 					if (domainARecords.length > 0) {
 						const matching = domainARecords.some((a) => ionIPs.includes(a));
 						if (matching) {
-							// DNS is correct — verify TLS certificate (also triggers Let's Encrypt provisioning)
-							const tlsValid = await checkTLSCertificate(domain);
-							if (tlsValid) {
-								return {
-									domain,
-									target: proxy,
-									aRecordTarget,
-									recordType: 'A',
-									success: true,
-								} as DNSSuccess;
-							}
+							// DNS is correctly configured
 							return {
 								domain,
 								target: proxy,
 								aRecordTarget,
 								recordType: 'A',
 								success: true,
-								pending: true,
-							} as DNSPending;
+							} as DNSSuccess;
 						}
 						return {
 							domain,
@@ -318,7 +262,6 @@ export async function checkCustomDomainForDNS(
 				target: proxy,
 				aRecordTarget,
 				recordType: 'CNAME',
-				pending: false,
 			} as DNSMissing;
 		})
 	);
@@ -371,13 +314,6 @@ export async function promptForDNS(
 						aRecordTarget: r.aRecordTarget,
 						status: tui.colorWarning(`${tui.ICONS.error} ${r.misconfigured}`),
 					});
-				} else if (isPending(r)) {
-					records.push({
-						domain: r.domain,
-						cnameTarget: r.target,
-						aRecordTarget: r.aRecordTarget,
-						status: tui.colorWarning('⌛️ Pending'),
-					});
 				} else if (isMissing(r)) {
 					records.push({
 						domain: r.domain,
@@ -420,3 +356,23 @@ export async function promptForDNS(
 		break;
 	}
 }
+
+/**
+ * Trigger TLS certificate provisioning for custom domains by making HTTPS requests.
+ * This causes the Ion proxy to initiate Let's Encrypt certificate issuance.
+ * Fire-and-forget — failures are silently ignored since certs will be provisioned
+ * on first real request if this doesn't succeed.
+ */
+export async function triggerTLSProvisioning(domains: string[]): Promise<void> {
+	await Promise.allSettled(
+		domains.map((domain) =>
+			fetch(`https://${domain}`, {
+				method: 'HEAD',
+				signal: AbortSignal.timeout(10000),
+				redirect: 'manual',
+			}).catch(() => {
+				// Silently ignore — cert will be provisioned on first real request
+			})
+		)
+	);
+}

package/src/output.ts

@@ -63,11 +63,56 @@ export function shouldDisableColors(options: GlobalOptions): boolean {
 	return options.json === true || options.quiet === true || !isTTYLike();
 }
 
+/**
+ * Filter data to only include specified fields.
+ * Supports dot notation for nested fields (e.g., "id,name,properties.title").
+ * For arrays, applies the filter to each element.
+ */
+function filterFields(data: unknown, fields: string[]): unknown {
+	if (Array.isArray(data)) {
+		return data.map((item) => filterFields(item, fields));
+	}
+	if (data && typeof data === 'object') {
+		const result: Record<string, unknown> = {};
+		for (const field of fields) {
+			const parts = field.split('.');
+			let current: unknown = data;
+			let target: Record<string, unknown> = result;
+			for (let i = 0; i < parts.length; i++) {
+				const part = parts[i] as string;
+				if (
+					current &&
+					typeof current === 'object' &&
+					part in (current as Record<string, unknown>)
+				) {
+					if (i === parts.length - 1) {
+						target[part] = (current as Record<string, unknown>)[part];
+					} else {
+						target[part] = target[part] || {};
+						target = target[part] as Record<string, unknown>;
+						current = (current as Record<string, unknown>)[part];
+					}
+				} else {
+					break; // path segment not found — stop traversal for this field
+				}
+			}
+		}
+		return result;
+	}
+	return data;
+}
+
 /**
  * Output JSON to stdout (for agent consumption)
  */
 export function outputJSON(data: unknown): void {
-	console.log(JSON.stringify(data, null, 2));
+	let output = data;
+	const options = getOutputOptions();
+	if (options?.fields) {
+		const fields = options.fields.split(',').map((f) => f.trim());
+		output = filterFields(output, fields);
+	}
+	console.log(JSON.stringify(output, null, 2));
 }
 
 /**

package/src/schema-generator.ts

@@ -75,10 +75,41 @@ export interface CLISchema {
 	commands: SchemaCommand[];
 }
 
+/**
+ * Apply args, options, and response from a CommandSchemas to a SchemaCommand.
+ * Shared by both extractCommandSchema and extractSubcommandSchema.
+ */
+function applySchemaFields(schema: SchemaCommand, schemas: CommandSchemas): void {
+	if (schemas.args) {
+		const parsedArgs = parseArgsSchema(schemas.args);
+		schema.arguments = parsedArgs.metadata.map((arg) => ({
+			name: arg.name,
+			type: arg.variadic ? 'array' : 'string',
+			required: !arg.optional,
+			variadic: arg.variadic,
+		}));
+	}
+
+	if (schemas.options) {
+		const parsedOptions = parseOptionsSchema(schemas.options);
+		schema.options = parsedOptions.map((opt) => ({
+			name: opt.name,
+			type: opt.type,
+			required: !opt.hasDefault,
+			default: opt.defaultValue,
+			description: opt.description,
+		}));
+	}
+
+	if (schemas.response) {
+		schema.response = z.toJSONSchema(schemas.response);
+	}
+}
+
 /**
  * Extract schema information from a CommandDefinition
  */
-function extractCommandSchema(def: CommandDefinition): SchemaCommand {
+export function extractCommandSchema(def: CommandDefinition): SchemaCommand {
 	const schema: SchemaCommand = {
 		name: def.name,
 		description: def.description,
@@ -151,6 +182,14 @@ function extractCommandSchema(def: CommandDefinition): SchemaCommand {
 		};
 	}
 
+	// Extract args and options from schema if available
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	if ((def as any).schema) {
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		const schemas = (def as any).schema as CommandSchemas;
+		applySchemaFields(schema, schemas);
+	}
+
 	// Extract subcommands recursively
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	if ((def as any).subcommands) {
@@ -166,7 +205,7 @@ function extractCommandSchema(def: CommandDefinition): SchemaCommand {
 /**
  * Extract schema information from a SubcommandDefinition
  */
-function extractSubcommandSchema(def: SubcommandDefinition): SchemaCommand {
+export function extractSubcommandSchema(def: SubcommandDefinition): SchemaCommand {
 	const schema: SchemaCommand = {
 		name: def.name,
 		description: def.description,
@@ -249,31 +288,7 @@ function extractSubcommandSchema(def: SubcommandDefinition): SchemaCommand {
 	// Extract args and options from schema if available
 	if (d.schema) {
 		const schemas = d.schema as CommandSchemas;
-
-		if (schemas.args) {
-			const parsedArgs = parseArgsSchema(schemas.args);
-			schema.arguments = parsedArgs.metadata.map((arg) => ({
-				name: arg.name,
-				type: arg.variadic ? 'array' : 'string',
-				required: !arg.optional,
-				variadic: arg.variadic,
-			}));
-		}
-
-		if (schemas.options) {
-			const parsedOptions = parseOptionsSchema(schemas.options);
-			schema.options = parsedOptions.map((opt) => ({
-				name: opt.name,
-				type: opt.type,
-				required: !opt.hasDefault,
-				default: opt.defaultValue,
-				description: opt.description,
-			}));
-		}
-
-		if (schemas.response) {
-			schema.response = z.toJSONSchema(schemas.response);
-		}
+		applySchemaFields(schema, schemas);
 	}
 
 	// Extract nested subcommands recursively
@@ -410,6 +425,26 @@ export function generateCLISchema(
 				default: false,
 				description: 'Validate arguments and options without executing',
 			},
+			{
+				name: 'input',
+				type: 'string',
+				required: false,
+				description: 'Pass arguments and options as a JSON object (for agents)',
+			},
+			{
+				name: 'describe',
+				type: 'boolean',
+				required: false,
+				default: false,
+				description: 'Output command schema as JSON for agent introspection',
+			},
+			{
+				name: 'fields',
+				type: 'string',
+				required: false,
+				description:
+					'Filter JSON output to specified fields (comma-separated, dot notation for nested)',
+			},
 		],
 		commands: commands.map(extractCommandSchema),
 	};

package/src/schema-parser.ts

@@ -1,5 +1,16 @@
 import type { ZodType } from 'zod';
 import type { CommandSchemas } from './types';
+import { StructuredError } from '@agentuity/core';
+
+const InputJSONParseError = StructuredError('InputJSONParseError')<{
+	flag: string;
+	errorType: string;
+}>();
+const InputJSONTypeError = StructuredError('InputJSONTypeError')<{
+	flag: string;
+	expected: string;
+	actual: string;
+}>();
 
 export interface ParsedArgs {
 	names: string[];
@@ -394,7 +405,8 @@ export function buildValidationInput(
 	schemas: CommandSchemas,
 	rawArgs: unknown[],
 	rawOptions: Record<string, unknown>,
-	_options?: { usesStdin?: boolean }
+	_options?: { usesStdin?: boolean },
+	inputJson?: string
 ): { args: Record<string, unknown>; options: Record<string, unknown> } {
 	const result = { args: {} as Record<string, unknown>, options: {} as Record<string, unknown> };
 
@@ -442,6 +454,47 @@ export function buildValidationInput(
 		}
 	}
 
+	// Merge --input JSON values: CLI flags take precedence over --input values
+	if (inputJson !== undefined) {
+		let parsed: Record<string, unknown>;
+		try {
+			parsed = JSON.parse(inputJson) as Record<string, unknown>;
+		} catch (e) {
+			throw new InputJSONParseError({
+				message: `Invalid JSON in --input flag: ${e instanceof Error ? e.message : String(e)}`,
+				flag: '--input',
+				errorType: 'json_parse',
+			});
+		}
+
+		if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+			throw new InputJSONTypeError({
+				message: `Invalid JSON in --input flag: expected a JSON object, got ${parsed === null ? 'null' : Array.isArray(parsed) ? 'array' : typeof parsed}`,
+				flag: '--input',
+				expected: 'object',
+				actual: parsed === null ? 'null' : Array.isArray(parsed) ? 'array' : typeof parsed,
+			});
+		}
+
+		if (schemas.args) {
+			const argsMeta = parseArgsSchema(schemas.args);
+			for (const name of argsMeta.names) {
+				if (result.args[name] === undefined && parsed[name] !== undefined) {
+					result.args[name] = parsed[name];
+				}
+			}
+		}
+
+		if (schemas.options) {
+			const optsMeta = parseOptionsSchema(schemas.options);
+			for (const opt of optsMeta) {
+				if (result.options[opt.name] === undefined && parsed[opt.name] !== undefined) {
+					result.options[opt.name] = parsed[opt.name];
+				}
+			}
+		}
+	}
+
 	return result;
 }
 
@@ -453,9 +506,10 @@ export async function buildValidationInputAsync(
 	schemas: CommandSchemas,
 	rawArgs: unknown[],
 	rawOptions: Record<string, unknown>,
-	options?: { usesStdin?: boolean }
+	options?: { usesStdin?: boolean },
+	inputJson?: string
 ): Promise<{ args: Record<string, unknown>; options: Record<string, unknown> }> {
-	const result = buildValidationInput(schemas, rawArgs, rawOptions, options);
+	const result = buildValidationInput(schemas, rawArgs, rawOptions, options, inputJson);
 
 	// Check for stdin confirmation if:
 	// 1. Command has a confirm option in schema

package/src/types.ts

@@ -310,6 +310,9 @@ export interface GlobalOptions {
 	dryRun?: boolean;
 	validate?: boolean;
 	skipVersionCheck?: boolean;
+	input?: string;
+	describe?: boolean;
+	fields?: string;
 }
 
 export interface PaginationInfo {