@agentuity/cli 2.0.0-beta.0 → 2.0.0

package/src/cmd/project/delete.ts

@@ -18,7 +18,7 @@ export const deleteSubcommand = createSubcommand({
 	name: 'delete',
 	description: 'Delete a project',
 	tags: ['destructive', 'deletes-resource', 'slow', 'requires-auth'],
-	aliases: ['rm', 'del'],
+	aliases: ['rm', 'del', 'remove', 'terminate'],
 	requires: { auth: true, apiClient: true },
 	idempotent: false,
 	examples: [

package/src/cmd/project/hostname/get.ts

@@ -12,6 +12,7 @@ const HostnameGetResponseSchema = z.object({
 
 export const getSubcommand = createSubcommand({
 	name: 'get',
+	aliases: ['show', 'info'],
 	description: 'Show the current vanity hostname for the project',
 	tags: ['read-only', 'fast', 'requires-auth', 'requires-project'],
 	requires: { auth: true, apiClient: true, project: true },

package/src/cmd/project/show.ts

@@ -12,6 +12,14 @@ const ProjectShowResponseSchema = z.object({
 	orgId: z.string().describe('Organization ID'),
 	secrets: z.record(z.string(), z.string()).optional().describe('Project secrets (masked)'),
 	env: z.record(z.string(), z.string()).optional().describe('Environment variables'),
+	urls: z
+		.object({
+			dashboard: z.string().describe('Dashboard URL for the project'),
+			app: z.string().describe('Public URL for the latest deployment'),
+			custom: z.array(z.string()).describe('Custom domain URLs'),
+		})
+		.optional()
+		.describe('Project URLs'),
 });
 
 export const showSubcommand = createSubcommand({
@@ -60,6 +68,7 @@ export const showSubcommand = createSubcommand({
 			orgId: project.orgId,
 			secrets: project.secrets,
 			env: project.env,
+			urls: project.urls,
 		};
 	},
 });

package/src/cmd/support/report.ts

@@ -1,12 +1,12 @@
 import { createSubcommand } from '../../types';
 import { z } from 'zod';
-import { readFileSync } from 'node:fs';
+import { createWriteStream, readFileSync } from 'node:fs';
 import { join, basename } from 'node:path';
 import { tmpdir } from 'node:os';
 import { getLogSessionsInCurrentWindow } from '../../internal-logger';
 import * as tui from '../../tui';
 import { randomBytes } from 'node:crypto';
-import AdmZip from 'adm-zip';
+import archiver from 'archiver';
 import { APIResponseSchema } from '@agentuity/server';
 import { StructuredError } from '@agentuity/core';
 
@@ -61,10 +61,19 @@ async function createReportZip(sessionDirs: string[]): Promise<string> {
 		throw NoSessionDirectoriesError();
 	}
 
-	// Create zip in temp directory
+	// Create zip in temp directory, streaming to disk instead of buffering in memory
 	const tempZip = join(tmpdir(), `agentuity-report-${randomBytes(8).toString('hex')}.zip`);
 
-	const zip = new AdmZip();
+	const output = createWriteStream(tempZip);
+	const zip = archiver('zip', { zlib: { level: 9 } });
+
+	const writeDone = new Promise<void>((resolve, reject) => {
+		output.on('close', resolve);
+		output.on('error', reject);
+		zip.on('error', reject);
+	});
+
+	zip.pipe(output);
 
 	for (const sessionDir of sessionDirs) {
 		const sessionFile = join(sessionDir, 'session.json');
@@ -75,14 +84,15 @@ async function createReportZip(sessionDirs: string[]): Promise<string> {
 
 		// Add files with session ID prefix to avoid conflicts
 		if (await Bun.file(sessionFile).exists()) {
-			zip.addLocalFile(sessionFile, sessionId);
+			zip.file(sessionFile, { name: `${sessionId}/session.json` });
 		}
 		if (await Bun.file(logsFile).exists()) {
-			zip.addLocalFile(logsFile, sessionId);
+			zip.file(logsFile, { name: `${sessionId}/logs.jsonl` });
 		}
 	}
 
-	zip.writeZip(tempZip);
+	await zip.finalize();
+	await writeDone;
 
 	return tempZip;
 }
@@ -95,14 +105,15 @@ async function uploadReport(
 	zipPath: string,
 	logger: import('../../types').Logger
 ): Promise<void> {
-	const fileBuffer = readFileSync(zipPath);
+	// Use Bun.file() to stream the zip to S3 without loading it into memory.
+	// Bun automatically sets Content-Length from the file size.
+	const file = Bun.file(zipPath);
 
 	const response = await fetch(presignedUrl, {
 		method: 'PUT',
-		body: fileBuffer,
+		body: file,
 		headers: {
 			'Content-Type': 'application/zip',
-			'Content-Length': fileBuffer.length.toString(),
 		},
 	});
 

package/src/cmd/upgrade/index.ts

@@ -3,6 +3,7 @@ import { getVersion, getCompareUrl, getReleaseUrl, toTag } from '../../version';
 import { getCommand } from '../../command-prefix';
 import { z } from 'zod';
 import { ErrorCode, createError, exitWithError } from '../../errors';
+import { isJSONMode } from '../../output';
 import * as tui from '../../tui';
 import { tmpdir } from 'node:os';
 import { getInstallationType, type InstallationType } from '../../utils/installation-type';
@@ -235,8 +236,8 @@ export const command = createCommand({
 				};
 			}
 
-			// Show version info
-			if (!force) {
+			// Show version info (suppress in JSON mode)
+			if (!isJSONMode(options)) {
 				tui.info(`Current version: ${tui.muted(normalizedCurrent)}`);
 				tui.info(`Latest version:  ${tui.bold(normalizedLatest)}`);
 				tui.newline();
@@ -249,22 +250,6 @@ export const command = createCommand({
 				tui.newline();
 			}
 
-			// Confirm upgrade
-			if (!force) {
-				const shouldUpgrade = await tui.confirm('Do you want to upgrade?', true);
-
-				if (!shouldUpgrade) {
-					const message = 'Upgrade cancelled';
-					tui.info(message);
-					return {
-						upgraded: false,
-						from: currentVersion,
-						to: latestVersion,
-						message,
-					};
-				}
-			}
-
 			// Perform the upgrade using bun
 			await tui.spinner({
 				type: 'logger',

package/src/errors.ts

@@ -1,22 +1,51 @@
 import type { Logger } from './types';
 
 /**
- * Standard exit codes for the CLI
+ * Standard exit codes for the CLI.
+ *
+ * Values start at 10 to avoid collisions with Unix signal numbers (1-9)
+ * and shell conventions (e.g. 2 = misuse of builtins, 9 = SIGKILL/OOM).
+ * Range 10-125 is safe — below shell-reserved 126-128 and signal-death
+ * codes 128+N.
+ *
+ * 0 and 1 are kept as universal success/failure codes.
  */
 export enum ExitCode {
 	SUCCESS = 0,
 	GENERAL_ERROR = 1,
-	VALIDATION_ERROR = 2,
-	AUTH_ERROR = 3,
-	NOT_FOUND = 4,
-	PERMISSION_ERROR = 5,
-	NETWORK_ERROR = 6,
-	FILE_ERROR = 7,
-	USER_CANCELLED = 8,
-	BUILD_FAILED = 9,
-	SECURITY_ERROR = 10,
+	VALIDATION_ERROR = 10,
+	AUTH_ERROR = 11,
+	NOT_FOUND = 12,
+	PERMISSION_ERROR = 13,
+	NETWORK_ERROR = 14,
+	FILE_ERROR = 15,
+	USER_CANCELLED = 16,
+	BUILD_FAILED = 17,
+	SECURITY_ERROR = 18,
+	PAYMENT_REQUIRED = 19,
+	UPGRADE_REQUIRED = 20,
 }
 
+/**
+ * Human-readable descriptions for each exit code.
+ * This is the single source of truth consumed by the schema generator and AI help.
+ */
+export const exitCodeDescriptions: Record<number, string> = {
+	[ExitCode.SUCCESS]: 'Success',
+	[ExitCode.GENERAL_ERROR]: 'General error',
+	[ExitCode.VALIDATION_ERROR]: 'Validation error (invalid arguments or options)',
+	[ExitCode.AUTH_ERROR]: 'Authentication error (login required or credentials invalid)',
+	[ExitCode.NOT_FOUND]: 'Resource not found (project, file, deployment, etc.)',
+	[ExitCode.PERMISSION_ERROR]: 'Permission denied (insufficient access rights)',
+	[ExitCode.NETWORK_ERROR]: 'Network error (API unreachable or timeout)',
+	[ExitCode.FILE_ERROR]: 'File system error (file read/write failed)',
+	[ExitCode.USER_CANCELLED]: 'User cancelled (operation aborted by user)',
+	[ExitCode.BUILD_FAILED]: 'Build failed',
+	[ExitCode.SECURITY_ERROR]: 'Security error (malware detected)',
+	[ExitCode.PAYMENT_REQUIRED]: 'Payment required (plan upgrade needed)',
+	[ExitCode.UPGRADE_REQUIRED]: 'Upgrade required (CLI version too old)',
+};
+
 /**
  * Standard error codes for the CLI
  */
@@ -152,7 +181,11 @@ export function getExitCode(errorCode: ErrorCode): ExitCode {
 
 		// Payment required - user needs to upgrade their plan
 		case ErrorCode.PAYMENT_REQUIRED:
-			return ExitCode.GENERAL_ERROR;
+			return ExitCode.PAYMENT_REQUIRED;
+
+		// Upgrade required - CLI version too old
+		case ErrorCode.UPGRADE_REQUIRED:
+			return ExitCode.UPGRADE_REQUIRED;
 
 		// Resource conflicts and other errors
 		case ErrorCode.RESOURCE_ALREADY_EXISTS:
@@ -162,7 +195,6 @@ export function getExitCode(errorCode: ErrorCode): ExitCode {
 		case ErrorCode.RUNTIME_ERROR:
 		case ErrorCode.INTERNAL_ERROR:
 		case ErrorCode.NOT_IMPLEMENTED:
-		case ErrorCode.UPGRADE_REQUIRED:
 		default:
 			return ExitCode.GENERAL_ERROR;
 	}

package/src/schema-generator.ts

@@ -1,5 +1,6 @@
 import type { Command } from 'commander';
 import type { CommandDefinition, SubcommandDefinition, CommandSchemas } from './types';
+import { exitCodeDescriptions } from './errors';
 import { parseArgsSchema, parseOptionsSchema } from './schema-parser';
 import * as z from 'zod';
 
@@ -313,18 +314,7 @@ export function generateCLISchema(
 		name: 'agentuity',
 		version,
 		description: 'Agentuity CLI',
-		exitCodes: {
-			0: 'Success',
-			1: 'General error',
-			2: 'Validation error (invalid arguments or options)',
-			3: 'Authentication error (login required or credentials invalid)',
-			4: 'Resource not found (project, file, deployment, etc.)',
-			5: 'Permission denied (insufficient access rights)',
-			6: 'Network error (API unreachable or timeout)',
-			7: 'File system error (file read/write failed)',
-			8: 'User cancelled (operation aborted by user)',
-			9: 'Build failed',
-		},
+		exitCodes: { ...exitCodeDescriptions },
 		globalOptions: [
 			{
 				name: 'config',
@@ -358,7 +348,7 @@ export function generateCLISchema(
 				name: 'org-id',
 				type: 'string',
 				required: false,
-				description: 'Use a specific organization when performing operations',
+				description: 'Use a specific organization when performing operations (alias: --org)',
 			},
 			{
 				name: 'color-scheme',

package/src/schema-parser.ts

@@ -454,6 +454,17 @@ export function buildValidationInput(
 				value = true;
 			}
 
+			// Handle --org alias for --org-id: if orgId is not set but org is, use that value
+			// Only treat --org as an --org-id alias if the schema does NOT declare a separate 'org' option
+			if (
+				(opt.name === 'orgId' || opt.name === 'org-id') &&
+				value === undefined &&
+				rawOptions.org !== undefined &&
+				!parsed.some((o) => o.name === 'org')
+			) {
+				value = rawOptions.org;
+			}
+
 			if (value !== undefined) {
 				result.options[opt.name] = value;
 			}

package/src/steps.ts

@@ -10,6 +10,7 @@ import type { LogLevel } from './types';
 import { ValidationInputError, ValidationOutputError, type IssuesType } from '@agentuity/server';
 import { clearLastLines, isTTYLike } from './tui';
 import { appendLog, isLogCollectionEnabled } from './log-collector';
+import { getOutputOptions, isJSONMode } from './output';
 
 /**
  * Error thrown when step execution is interrupted by a signal (e.g., Ctrl+C).
@@ -700,6 +701,43 @@ async function runStepsPlain(steps: Step[]): Promise<void> {
  * Run a series of steps with animated progress
  */
 export async function runSteps(steps: Step[], logLevel?: LogLevel): Promise<void> {
+	const outputOptions = getOutputOptions();
+
+	// In JSON mode, skip all UI rendering
+	if (outputOptions && isJSONMode(outputOptions)) {
+		const abortController = new AbortController();
+		for (const step of steps) {
+			if (abortController.signal.aborted) break;
+			if (step) {
+				const ctx: StepContext = {
+					signal: abortController.signal,
+					progress: () => {},
+				};
+				let outcome: StepOutcome;
+				try {
+					outcome = await step.run(ctx);
+				} catch (err) {
+					if (err instanceof Error && err.name === 'AbortError') {
+						throw new StepInterruptError();
+					}
+					outcome = {
+						status: 'error',
+						message: err instanceof Error ? err.message : String(err),
+						cause: err instanceof Error ? err : undefined,
+					};
+				}
+				if (outcome.status === 'error') {
+					if (outcome.cause instanceof Error && outcome.cause.name === 'AbortError') {
+						throw new StepInterruptError();
+					}
+					const errorMsg = outcome.message || 'An unknown error occurred';
+					throw new Error(errorMsg);
+				}
+			}
+		}
+		return;
+	}
+
 	const useTUI = isTTYLike() && (!logLevel || ['info', 'warn', 'error'].includes(logLevel));
 
 	if (useTUI) {

package/src/tui.ts

@@ -25,6 +25,12 @@ function ensureCursorRestoration(): void {
 	exitHandlerInstalled = true;
 
 	const restoreCursor = () => {
+		// Only write ANSI escape sequences when stderr is a real terminal.
+		// Writing to non-TTY streams (pipes, command substitution, etc.)
+		// pollutes captured output with invisible control characters.
+		if (!process.stderr.isTTY) {
+			return;
+		}
 		// Skip cursor restoration in CI - terminals don't support these sequences
 		if (process.env.CI) {
 			return;
@@ -293,8 +299,13 @@ export function getSeverityColor(severity: string): (text: string) => string {
 export function success(message: string): void {
 	const color = getColor('success');
 	const reset = getColor('reset');
-	// Clear line first to ensure no leftover content from previous output
-	process.stderr.write(`\r\x1b[2K${color}${ICONS.success} ${message}${reset}\n`);
+	if (process.stderr.isTTY) {
+		// Clear line first to ensure no leftover content from previous output
+		process.stderr.write(`\r\x1b[2K${color}${ICONS.success} ${message}${reset}\n`);
+	} else {
+		// No ANSI control sequences for non-TTY streams (pipes, command substitution)
+		process.stderr.write(`${ICONS.success} ${message}\n`);
+	}
 }
 
 /**
@@ -1242,18 +1253,23 @@ export async function spinner<T>(
 	const { getOutputOptions, shouldDisableProgress } = await import('./output');
 	const outputOptions = getOutputOptions();
 	const noProgress = outputOptions ? shouldDisableProgress(outputOptions) : false;
+	const isJsonMode = outputOptions?.json === true;
 
-	// If no interactive TTY-like environment or progress disabled, just execute
-	// the callback without animation
-	if (!isTTYLike() || noProgress) {
+	// If stderr is not a real terminal or progress disabled, just execute
+	// the callback without animation. We check stderr specifically because
+	// the spinner writes ANSI sequences to stderr — isTTYLike() may return
+	// true when stdout is a TTY but stderr is piped (e.g. 2>&1 in $()).
+	if (!process.stderr.isTTY || noProgress) {
 		try {
 			const result =
 				options.type === 'progress'
 					? await options.callback(() => {})
 					: options.type === 'logger'
 						? await options.callback((logMessage: string) => {
-								// In non-TTY mode, just write logs directly to stdout
-								process.stdout.write(logMessage + '\n');
+								// In JSON mode, don't write logs to stdout
+								if (!isJsonMode) {
+									process.stdout.write(logMessage + '\n');
+								}
 							})
 						: options.type === 'countdown'
 							? await options.callback()
@@ -1263,7 +1279,6 @@ export async function spinner<T>(
 
 			// If clearOnSuccess is true, don't show success message
 			// Also skip success message in JSON mode
-			const isJsonMode = outputOptions?.json === true;
 			if (!options.clearOnSuccess && !isJsonMode) {
 				const successColor = getColor('success');
 				console.error(`${successColor}${ICONS.success} ${message}${reset}`);
@@ -1273,7 +1288,7 @@ export async function spinner<T>(
 		} catch (err) {
 			const clearOnError =
 				(options.type === 'progress' || options.type === 'simple') && options.clearOnError;
-			if (!clearOnError) {
+			if (!clearOnError && !isJsonMode) {
 				const errorColor = getColor('error');
 				console.error(`${errorColor}${ICONS.error} ${message}${reset}`);
 			}

package/src/utils/stream-capture.ts

@@ -0,0 +1,39 @@
+import { createWriteStream } from 'node:fs';
+
+/**
+ * Stream a ReadableStream of raw bytes to a file on disk.
+ *
+ * This mirrors the pattern used by the deploy fork wrapper to capture child
+ * process stdout/stderr without accumulating the output in memory.  Returns
+ * the total number of bytes written.
+ */
+export async function captureStreamToFile(
+	stream: ReadableStream<Uint8Array>,
+	filePath: string
+): Promise<number> {
+	const writer = createWriteStream(filePath);
+	const reader = stream.getReader();
+	let totalBytes = 0;
+
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+
+			const ok = writer.write(value);
+			totalBytes += value.byteLength;
+
+			// Respect backpressure: wait for drain when the internal buffer is full
+			if (!ok) {
+				await new Promise<void>((resolve) => writer.once('drain', resolve));
+			}
+		}
+	} finally {
+		await new Promise<void>((resolve, reject) => {
+			writer.once('error', reject);
+			writer.end(resolve);
+		});
+	}
+
+	return totalBytes;
+}

package/src/utils/stream-url.ts

@@ -0,0 +1,226 @@
+import { writeAndDrain } from '@agentuity/server';
+import type { Logger } from '@agentuity/core';
+import * as tui from '../tui';
+
+export interface StreamUrlOptions {
+	signal?: AbortSignal;
+	follow?: boolean;
+	timestamps?: boolean;
+	grep?: string;
+	tail?: number;
+	json?: boolean;
+	label?: string;
+	raw?: boolean;
+	v2?: boolean;
+}
+
+export interface StreamUrlResult {
+	bytesRead: number;
+	chunks: number;
+}
+
+export class StreamFetchError extends Error {
+	constructor(
+		public status: number,
+		public statusText: string,
+		message: string
+	) {
+		super(message);
+		this.name = 'StreamFetchError';
+	}
+}
+
+function escapeRegExp(str: string): string {
+	return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export async function streamUrlToWritable(
+	url: string,
+	writable: NodeJS.WritableStream,
+	logger: Logger,
+	options: StreamUrlOptions = {}
+): Promise<StreamUrlResult> {
+	const {
+		signal,
+		follow,
+		timestamps,
+		grep,
+		tail,
+		json,
+		label = 'stream',
+		raw = false,
+		v2 = false,
+	} = options;
+	const streamStart = Date.now();
+	let bytesRead = 0;
+	let chunks = 0;
+
+	try {
+		const fetchUrl = new URL(url);
+
+		if (follow || v2) {
+			fetchUrl.searchParams.set('v', '2');
+		}
+		if (follow) {
+			fetchUrl.searchParams.set('follow', 'true');
+		}
+
+		const redactedUrl =
+			fetchUrl.origin + fetchUrl.pathname + (fetchUrl.search ? '?REDACTED' : '');
+		logger.debug('[%s] fetching: %s', label, redactedUrl);
+		const response = await fetch(fetchUrl.href, { signal });
+		logger.debug(
+			'[%s] response status=%d in %dms',
+			label,
+			response.status,
+			Date.now() - streamStart
+		);
+
+		if (!response.ok || !response.body) {
+			logger.debug('[%s] not ok or no body', label);
+			if (!json) {
+				tui.error(`Failed to fetch stream: ${response.status} ${response.statusText}`);
+			}
+			throw new StreamFetchError(
+				response.status,
+				response.statusText,
+				`Failed to fetch stream: ${response.status} ${response.statusText}`
+			);
+		}
+
+		const reader = response.body.getReader();
+
+		if (raw) {
+			while (true) {
+				const { done, value } = await reader.read();
+				if (done) {
+					logger.debug(
+						'[%s] EOF after %dms (%d chunks, %d bytes)',
+						label,
+						Date.now() - streamStart,
+						chunks,
+						bytesRead
+					);
+					break;
+				}
+
+				if (value) {
+					chunks++;
+					bytesRead += value.length;
+					if (chunks <= 3 || chunks % 100 === 0) {
+						logger.debug(
+							'[%s] chunk #%d: %d bytes (total: %d bytes, +%dms)',
+							label,
+							chunks,
+							value.length,
+							bytesRead,
+							Date.now() - streamStart
+						);
+					}
+					await writeAndDrain(writable, value);
+				}
+			}
+		} else {
+			const decoder = new TextDecoder();
+			let leftover = '';
+			const grepPattern = grep ? new RegExp(escapeRegExp(grep), 'i') : null;
+			const needsFiltering = tail !== undefined || grepPattern !== null;
+			const tailBuffer: string[] = [];
+			const maxTail = tail ?? Infinity;
+			const liveOutput = follow && needsFiltering;
+
+			const outputLine = async (line: string) => {
+				if (json) {
+					const obj = {
+						timestamp: new Date().toISOString(),
+						stream: label,
+						message: line,
+					};
+					await writeAndDrain(writable, Buffer.from(JSON.stringify(obj) + '\n'));
+				} else {
+					const formatted = timestamps ? formatLineWithTimestamp(line) : line;
+					await writeAndDrain(writable, Buffer.from(formatted + '\n'));
+				}
+			};
+
+			const processFilteredLine = async (line: string) => {
+				if (grepPattern && !grepPattern.test(line)) {
+					return;
+				}
+				if (tail !== undefined) {
+					tailBuffer.push(line);
+					if (tailBuffer.length > maxTail) {
+						tailBuffer.shift();
+					}
+					if (liveOutput) {
+						await outputLine(line);
+					}
+				} else {
+					await outputLine(line);
+				}
+			};
+
+			while (true) {
+				const { done, value } = await reader.read();
+				if (done) {
+					if (leftover) {
+						if (needsFiltering) {
+							await processFilteredLine(leftover);
+						} else {
+							await outputLine(leftover);
+						}
+					}
+					logger.debug(
+						'[%s] EOF after %dms (%d chunks, %d bytes)',
+						label,
+						Date.now() - streamStart,
+						chunks,
+						bytesRead
+					);
+					break;
+				}
+
+				if (value) {
+					chunks++;
+					bytesRead += value.length;
+					const text = leftover + decoder.decode(value, { stream: true });
+					const lines = text.split('\n');
+					leftover = lines.pop() ?? '';
+
+					for (const line of lines) {
+						if (needsFiltering) {
+							await processFilteredLine(line);
+						} else {
+							await outputLine(line);
+						}
+					}
+				}
+			}
+
+			if (!liveOutput && needsFiltering && tailBuffer.length > 0) {
+				for (const line of tailBuffer) {
+					await outputLine(line);
+				}
+			}
+		}
+
+		return { bytesRead, chunks };
+	} catch (err) {
+		if (err instanceof Error && err.name === 'AbortError') {
+			logger.debug('[%s] aborted after %dms', label, Date.now() - streamStart);
+			return { bytesRead, chunks };
+		}
+		logger.debug('[%s] error after %dms: %s', label, Date.now() - streamStart, err);
+		throw err;
+	}
+}
+
+function formatLineWithTimestamp(line: string): string {
+	const timestamp = new Date().toLocaleTimeString('en-US', {
+		hour12: false,
+		hour: '2-digit',
+		minute: '2-digit',
+		second: '2-digit',
+	});
+	return `${tui.muted(timestamp)} ${line}`;
+}