@agentuity/cli 0.0.11 → 0.0.13

package/src/cmd/project/download.ts

@@ -1,8 +1,9 @@
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { existsSync, mkdirSync, renameSync, readdirSync, cpSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { pipeline } from 'node:stream/promises';
 import { createGunzip } from 'node:zlib';
-import { extract } from 'tar-fs';
+import { extract, type Headers } from 'tar-fs';
 import type { Logger } from '@/logger';
 import * as tui from '@/tui';
 import { downloadWithSpinner } from '@/download';
@@ -27,22 +28,12 @@ interface SetupOptions {
 	logger: Logger;
 }
 
-export async function downloadTemplate(options: DownloadOptions): Promise<void> {
-	const { dest, template, templateDir, templateBranch } = options;
-
-	mkdirSync(dest, { recursive: true });
-
-	// Copy from local directory if provided
-	if (templateDir) {
-		const { resolve } = await import('node:path');
-		const sourceDir = resolve(join(templateDir, template.directory));
-
-		if (!existsSync(sourceDir)) {
-			throw new Error(`Template directory not found: ${sourceDir}`);
-		}
-
-		tui.info(`📦 Copying template from ${sourceDir}...`);
+async function cleanup(sourceDir: string, dest: string) {
+	if (!existsSync(sourceDir)) {
+		throw new Error(`Template directory not found: ${sourceDir}`);
+	}
 
+	tui.spinner(`📦 Copying template from ${sourceDir}...`, async () => {
 		// Copy all files from source to dest
 		const files = readdirSync(sourceDir);
 		for (const file of files) {
@@ -54,8 +45,23 @@ export async function downloadTemplate(options: DownloadOptions): Promise<void>
 		if (existsSync(gi)) {
 			renameSync(gi, join(dest, '.gitignore'));
 		}
+	});
+}
+
+export async function downloadTemplate(options: DownloadOptions): Promise<void> {
+	const { dest, template, templateDir, templateBranch } = options;
 
-		return;
+	mkdirSync(dest, { recursive: true });
+
+	// Copy from local directory if provided
+	if (templateDir) {
+		const sourceDir = resolve(join(templateDir, template.directory));
+
+		if (!existsSync(sourceDir)) {
+			throw new Error(`Template directory not found: ${sourceDir}`);
+		}
+
+		return cleanup(sourceDir, dest);
 	}
 
 	// Download from GitHub
@@ -74,65 +80,43 @@ export async function downloadTemplate(options: DownloadOptions): Promise<void>
 		},
 		async (stream) => {
 			// Extract only the template directory from tarball
+			const prefix = `sdk-${branch}/${templatePath}/`;
 			await pipeline(
 				stream,
 				createGunzip(),
 				extract(tempDir, {
-					map: (header) => {
-						const prefix = `sdk-${branch}/${templatePath}/`;
-						if (header.name.startsWith(prefix)) {
-							header.name = header.name.substring(prefix.length);
-							return header;
-						}
-						// eslint-disable-next-line @typescript-eslint/no-explicit-any
-						return null as any;
+					filter: (name: string) => name.startsWith(prefix),
+					map: (header: Headers) => {
+						header.name = header.name.substring(prefix.length);
+						return header;
 					},
 				})
 			);
 		}
 	);
 
-	// Move files from temp to dest
-	const files = readdirSync(tempDir);
-	for (const file of files) {
-		cpSync(join(tempDir, file), join(dest, file), { recursive: true });
-	}
-	rmSync(tempDir, { recursive: true, force: true });
+	await cleanup(tempDir, dest);
 
-	// Rename gitignore -> .gitignore
-	const gi = join(dest, 'gitignore');
-	if (existsSync(gi)) {
-		renameSync(gi, join(dest, '.gitignore'));
+	// Extra safety: refuse to delete root or home directories
+	const home = homedir();
+	if (tempDir === '/' || tempDir === home) {
+		throw new Error(`Refusing to delete protected path: ${tempDir}`);
 	}
+	rmSync(tempDir, { recursive: true, force: true });
 }
 
 export async function setupProject(options: SetupOptions): Promise<void> {
 	const { dest, projectName, dirName, noInstall, noBuild, logger } = options;
 
-	process.chdir(dest);
-
 	// Replace {{PROJECT_NAME}} in files
 	tui.info(`🔧 Setting up ${projectName}...`);
 	await replaceInFiles(dest, projectName, dirName);
 
-	// Run setup.ts if it exists (legacy)
-	if (await Bun.file('./setup.ts').exists()) {
-		await tui.spinner({
-			message: 'Running setup script...',
-			callback: async () => {
-				const proc = Bun.spawn(['bun', './setup.ts'], { stdio: ['pipe', 'pipe', 'pipe'] });
-				const exitCode = await proc.exited;
-				if (exitCode !== 0) {
-					logger.error('Setup script failed');
-				}
-			},
-		});
-	}
-
 	// Install dependencies
 	if (!noInstall) {
 		const exitCode = await tui.runCommand({
 			command: 'bun install',
+			cwd: dest,
 			cmd: ['bun', 'install'],
 			clearOnSuccess: true,
 		});
@@ -145,6 +129,7 @@ export async function setupProject(options: SetupOptions): Promise<void> {
 	if (!noBuild) {
 		const exitCode = await tui.runCommand({
 			command: 'bun run build',
+			cwd: dest,
 			cmd: ['bun', 'run', 'build'],
 			clearOnSuccess: true,
 		});

package/src/cmd/project/template-flow.ts

@@ -1,13 +1,17 @@
 import { basename, resolve } from 'node:path';
 import { existsSync, readdirSync, rmSync } from 'node:fs';
+import { cwd } from 'node:process';
+import { homedir } from 'node:os';
 import enquirer from 'enquirer';
 import type { Logger } from '@/logger';
 import * as tui from '@/tui';
+import { playSound } from '@/sound';
 import { fetchTemplates, type TemplateInfo } from './templates';
 import { downloadTemplate, setupProject } from './download';
 
 interface CreateFlowOptions {
 	projectName?: string;
+	dir?: string;
 	template?: string;
 	templateDir?: string;
 	templateBranch?: string;
@@ -20,6 +24,7 @@ interface CreateFlowOptions {
 export async function runCreateFlow(options: CreateFlowOptions): Promise<void> {
 	const {
 		projectName: initialProjectName,
+		dir: targetDir,
 		template: initialTemplate,
 		templateDir,
 		templateBranch,
@@ -64,14 +69,20 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<void> {
 	const dirName = projectName === '.' ? '.' : sanitizeDirectoryName(projectName);
 
 	// Step 4: Determine destination directory
-	const dest = dirName === '.' ? process.cwd() : resolve(process.cwd(), dirName);
+	// Expand ~ to home directory
+	let expandedTargetDir = targetDir;
+	if (expandedTargetDir && expandedTargetDir.startsWith('~')) {
+		expandedTargetDir = expandedTargetDir.replace(/^~/, homedir());
+	}
+	const baseDir = expandedTargetDir ? resolve(expandedTargetDir) : process.cwd();
+	const dest = dirName === '.' ? baseDir : resolve(baseDir, dirName);
 	const destExists = existsSync(dest);
 	const destEmpty = destExists ? readdirSync(dest).length === 0 : true;
 
 	if (destExists && !destEmpty && dirName !== '.') {
 		// In TTY mode, ask if they want to overwrite
 		if (process.stdin.isTTY && !skipPrompts) {
-			tui.warning(`Directory ${dirName} already exists and is not empty.\n`);
+			tui.warning(`Directory ${dest} already exists and is not empty.`, true);
 			const response = await enquirer.prompt<{ overwrite: boolean }>({
 				type: 'confirm',
 				name: 'overwrite',
@@ -84,19 +95,23 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<void> {
 				process.exit(0);
 			}
 
-			// Delete the existing directory
+			// Extra safety: refuse to delete root or home directories
+			const home = homedir();
+			if (dest === '/' || dest === home) {
+				logger.fatal(`Refusing to delete protected path: ${dest}`);
+				return;
+			}
 			rmSync(dest, { recursive: true, force: true });
-			tui.success(`Deleted ${dirName}\n`);
+			tui.success(`Deleted ${dest}\n`);
 		} else {
-			logger.fatal(`Directory ${dirName} already exists and is not empty.`);
+			logger.fatal(`Directory ${dest} already exists and is not empty.`, true);
 		}
 	}
 
 	// Show directory and name confirmation
 	if (!skipPrompts) {
-		const displayPath = dirName === '.' ? basename(dest) : dirName;
 		tui.info(`📁 Project: ${tui.bold(projectName)}`);
-		tui.info(`📂 Directory: ${tui.bold(displayPath)}\n`);
+		tui.info(`📂 Directory: ${tui.bold(dest)}\n`);
 	}
 
 	// Step 5: Select template
@@ -152,14 +167,14 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<void> {
 	tui.success('✨ Project created successfully!\n');
 	tui.info('Next steps:');
 	if (dirName !== '.') {
+		const dirDisplay = cwd() == targetDir ? basename(dirName) : dest;
 		tui.newline();
-		console.log(`  1. ${tui.bold(`cd ${dirName}`)}`);
+		console.log(`  1. ${tui.bold(`cd ${dirDisplay}`)}`);
 		console.log(`  2. ${tui.bold('bun run dev')}`);
 	} else {
-		console.log(`  1. ${tui.bold('bun run dev')}`);
+		console.log(`  ${tui.bold('bun run dev')}`);
 	}
-	tui.newline();
-	console.log(`Your agents will be running at ${tui.link('http://localhost:3000')}`);
+	playSound();
 }
 
 /**

package/src/config.ts

@@ -1,5 +1,5 @@
 import { YAML } from 'bun';
-import { join, extname } from 'node:path';
+import { join, extname, basename } from 'node:path';
 import { homedir } from 'node:os';
 import { mkdir, readdir, readFile, writeFile, chmod } from 'node:fs/promises';
 import type { Config, Profile, AuthData } from './types';
@@ -104,6 +104,13 @@ export async function loadConfig(customPath?: string): Promise<Config | null> {
 		const content = await file.text();
 		const config = YAML.parse(content);
 
+		// check to see if this is a legacy config file that might not have the required name
+		// and in this case we can just use the filename
+		const _config = config as { name?: string };
+		if (!_config.name) {
+			_config.name = basename(configPath).replace(extname(configPath), '');
+		}
+
 		const result = ConfigSchema.safeParse(config);
 		if (!result.success) {
 			tui.error(`Invalid config in ${configPath}:`);

package/src/download.ts

@@ -1,4 +1,4 @@
-import { Transform } from 'node:stream';
+import { Transform, Readable } from 'node:stream';
 import * as tui from './tui';
 
 export interface DownloadOptions {
@@ -48,7 +48,7 @@ export async function downloadWithProgress(
 	});
 
 	// Pipe the response through the progress tracker
-	const responseStream = response.body as unknown as NodeJS.ReadableStream;
+	const responseStream = Readable.fromWeb(response.body as unknown as ReadableStream);
 	responseStream.pipe(progressStream);
 
 	return progressStream;

package/src/index.ts

@@ -1,6 +1,7 @@
 export { createCLI, registerCommands } from './cli';
 export { validateRuntime, isBun } from './runtime';
 export { getVersion, getRevision, getPackageName, getPackage } from './version';
+export { requireAuth, optionalAuth, withAuth, withOptionalAuth } from './auth';
 export {
 	loadConfig,
 	saveConfig,

package/src/sound.ts

@@ -1,25 +1,39 @@
-import { $ } from 'bun';
+import { join } from 'node:path';
 
-export async function playSound(): Promise<void> {
+export function playSound(): void {
 	const platform = process.platform;
 
-	let result;
+	let command: string[];
 	switch (platform) {
-		case 'darwin':
-			result = await $`afplay /System/Library/Sounds/Glass.aiff`.quiet().nothrow();
+		case 'darwin': {
+			const items = [
+				'Blow.aiff',
+				'Bottle.aiff',
+				'Frog.aiff',
+				'Funk.aiff',
+				'Glass.aiff',
+				'Hero.aiff',
+				'Morse.aiff',
+				'Ping.aiff',
+				'Pop.aiff',
+				'Purr.aiff',
+				'Sosumi.aiff',
+			] as const;
+			const file = items[Math.floor(Math.random() * items.length)];
+			command = ['afplay', join('/System/Library/Sounds', file)];
 			break;
+		}
 		case 'linux':
-			result = await $`paplay /usr/share/sounds/freedesktop/stereo/complete.oga`
-				.quiet()
-				.nothrow();
+			command = ['paplay', '/usr/share/sounds/freedesktop/stereo/complete.oga'];
 			break;
 		case 'win32':
-			result = await $`rundll32 user32.dll,MessageBeep 0x00000040`.quiet().nothrow();
+			command = ['rundll32', 'user32.dll,MessageBeep', '0x00000040'];
 			break;
+		default:
+			return;
 	}
 
-	// Fallback to terminal bell if command failed or platform unsupported
-	if (!result || result.exitCode !== 0) {
-		process.stdout.write('\u0007');
-	}
+	Bun.spawn(command, {
+		stdio: ['ignore', 'ignore', 'ignore'],
+	}).unref();
 }

package/src/tui.ts

@@ -82,11 +82,21 @@ export function error(message: string): void {
 	console.error(`${color}${ICONS.error} ${message}${reset}`);
 }
 
+/**
+ * Print an error message with a red X and then exit
+ */
+export function fatal(message: string): never {
+	const color = getColor('error');
+	const reset = COLORS.reset;
+	console.error(`${color}${ICONS.error} ${message}${reset}`);
+	process.exit(1);
+}
+
 /**
  * Print a warning message with a yellow warning icon
  */
-export function warning(message: string): void {
-	const color = getColor('warning');
+export function warning(message: string, asError = false): void {
+	const color = asError ? getColor('error') : getColor('warning');
 	const reset = COLORS.reset;
 	console.log(`${color}${ICONS.warning} ${message}${reset}`);
 }
@@ -200,9 +210,13 @@ export function padLeft(str: string, length: number, pad = ' '): string {
  * Creates a bordered box around the content
  *
  * Uses Bun.stringWidth() for accurate width calculation with ANSI codes and unicode
+ * Responsive to terminal width - adapts to narrow terminals
  */
 export function banner(title: string, body: string): void {
-	const maxWidth = 80;
+	// Get terminal width, default to 80 if not available, minimum 40
+	const termWidth = process.stdout.columns || 80;
+	const maxWidth = Math.max(40, Math.min(termWidth - 2, 80)); // Between 40 and 80, with 2 char margin
+
 	const border = {
 		topLeft: '╭',
 		topRight: '╮',
@@ -377,6 +391,33 @@ export async function confirm(message: string, defaultValue = true): Promise<boo
 	});
 }
 
+/**
+ * Display a signup benefits box with cyan border
+ * Shows the value proposition for creating an Agentuity account
+ */
+export function showSignupBenefits(): void {
+	const CYAN = Bun.color('cyan', 'ansi-16m');
+	const TEXT =
+		currentColorScheme === 'dark' ? Bun.color('white', 'ansi') : Bun.color('black', 'ansi');
+	const RESET = '\x1b[0m';
+
+	const lines = [
+		'╔════════════════════════════════════════════╗',
+		`║ ⨺ Signup for Agentuity             ${muted('free')}${CYAN}    ║`,
+		'║                                            ║',
+		`║ ✓ ${TEXT}Cloud deployment, previews and CI/CD${CYAN}     ║`,
+		`║ ✓ ${TEXT}AI Gateway, KV, Vector and more${CYAN}          ║`,
+		`║ ✓ ${TEXT}Observability, Tracing and Logging${CYAN}       ║`,
+		`║ ✓ ${TEXT}Organization and Team support${CYAN}            ║`,
+		`║ ✓ ${TEXT}And much more!${CYAN}                           ║`,
+		'╚════════════════════════════════════════════╝',
+	];
+
+	console.log('');
+	lines.forEach((line) => console.log(CYAN + line + RESET));
+	console.log('');
+}
+
 /**
  * Copy text to clipboard
  * Returns true if successful, false otherwise
@@ -443,9 +484,36 @@ function getDisplayWidth(str: string): number {
 	return Bun.stringWidth(withoutOSC8);
 }
 
+/**
+ * Extract ANSI codes from the beginning of a string
+ */
+function extractLeadingAnsiCodes(str: string): string {
+	// Match ANSI escape sequences at the start of the string
+	// eslint-disable-next-line no-control-regex
+	const match = str.match(/^(\x1b\[[0-9;]*m)+/);
+	return match ? match[0] : '';
+}
+
+/**
+ * Strip ANSI codes from a string
+ */
+function stripAnsiCodes(str: string): string {
+	// Remove all ANSI escape sequences
+	// eslint-disable-next-line no-control-regex
+	return str.replace(/\x1b\[[0-9;]*m/g, '');
+}
+
+/**
+ * Check if a string ends with ANSI reset code
+ */
+function endsWithReset(str: string): boolean {
+	return str.endsWith('\x1b[0m') || str.endsWith(COLORS.reset);
+}
+
 /**
  * Wrap text to a maximum width
  * Handles explicit newlines and word wrapping
+ * Preserves ANSI color codes across wrapped lines
  */
 function wrapText(text: string, maxWidth: number): string[] {
 	const allLines: string[] = [];
@@ -460,6 +528,13 @@ function wrapText(text: string, maxWidth: number): string[] {
 			continue;
 		}
 
+		// Record starting index for this paragraph's lines
+		const paragraphStart = allLines.length;
+
+		// Extract any leading ANSI codes from the paragraph
+		const leadingCodes = extractLeadingAnsiCodes(paragraph);
+		const hasReset = endsWithReset(paragraph);
+
 		// Wrap each paragraph
 		const words = paragraph.split(' ');
 		let currentLine = '';
@@ -477,13 +552,30 @@ function wrapText(text: string, maxWidth: number): string[] {
 				}
 				// If the word itself is longer than maxWidth, just use it as is
 				// (better to have a long line than break in the middle)
-				currentLine = word;
+				// But if we have leading codes and this isn't the first line, apply them
+				if (leadingCodes && currentLine) {
+					// Strip any existing codes from the word to avoid duplication
+					const strippedWord = stripAnsiCodes(word);
+					currentLine = leadingCodes + strippedWord;
+				} else {
+					currentLine = word;
+				}
 			}
 		}
 
 		if (currentLine) {
 			allLines.push(currentLine);
 		}
+
+		// If the original paragraph had ANSI codes and ended with reset,
+		// ensure each wrapped line ends with reset (only for this paragraph's lines)
+		if (leadingCodes && hasReset) {
+			for (let i = paragraphStart; i < allLines.length; i++) {
+				if (!endsWithReset(allLines[i])) {
+					allLines[i] += COLORS.reset;
+				}
+			}
+		}
 	}
 
 	return allLines.length > 0 ? allLines : [''];
@@ -658,6 +750,20 @@ export interface CommandRunnerOptions {
 	 * Defaults to false
 	 */
 	clearOnSuccess?: boolean;
+	/**
+	 * If true or undefined, will truncate each line of output
+	 */
+	truncate?: boolean;
+
+	/**
+	 * If undefined, will show up to 3 last lines of output while running. Customize the number with this property.
+	 */
+	maxLinesOutput?: number;
+
+	/**
+	 * If undefined, will show up to 10 last lines on failure. Customize the number with this property.
+	 */
+	maxLinesOnFailure?: number;
 }
 
 /**
@@ -671,7 +777,16 @@ export interface CommandRunnerOptions {
  * Shows the last 3 lines of output as it streams.
  */
 export async function runCommand(options: CommandRunnerOptions): Promise<number> {
-	const { command, cmd, cwd, env, clearOnSuccess = false } = options;
+	const {
+		command,
+		cmd,
+		cwd,
+		env,
+		clearOnSuccess = false,
+		truncate = true,
+		maxLinesOutput = 3,
+		maxLinesOnFailure = 10,
+	} = options;
 	const isTTY = process.stdout.isTTY;
 
 	// If not a TTY, just run the command normally and log output
@@ -746,7 +861,7 @@ export async function runCommand(options: CommandRunnerOptions): Promise<number>
 	};
 
 	// Initial display
-	renderOutput(3);
+	renderOutput(maxLinesOutput);
 
 	try {
 		// Spawn the command
@@ -805,10 +920,12 @@ export async function runCommand(options: CommandRunnerOptions): Promise<number>
 			process.stdout.write(`\x1b[${linesRendered}A`);
 
 			// Show compact success: ✓ command
-			process.stdout.write(`\r\x1b[K${green}${ICONS.success}${reset} ${cmdColor}${displayCmd}${reset}\n`);
+			process.stdout.write(
+				`\r\x1b[K${green}${ICONS.success}${reset} ${cmdColor}${displayCmd}${reset}\n`
+			);
 		} else {
 			// Determine how many lines to show in final output
-			const finalLinesToShow = exitCode === 0 ? 3 : 10;
+			const finalLinesToShow = exitCode === 0 ? maxLinesOutput : maxLinesOnFailure;
 
 			// Show final status with appropriate color
 			const statusColor = exitCode === 0 ? green : red;
@@ -818,7 +935,7 @@ export async function runCommand(options: CommandRunnerOptions): Promise<number>
 			const finalOutputLines = allOutputLines.slice(-finalLinesToShow);
 			for (const line of finalOutputLines) {
 				let displayLine = line;
-				if (getDisplayWidth(displayLine) > maxLineWidth) {
+				if (truncate && getDisplayWidth(displayLine) > maxLineWidth) {
 					displayLine = displayLine.slice(0, maxLineWidth - 3) + '...';
 				}
 				process.stdout.write(`\r\x1b[K${mutedColor}${displayLine}${reset}\n`);

package/src/types.ts

@@ -150,6 +150,7 @@ export type CommandContext<
 // Helper to create subcommands with proper type inference
 export function createSubcommand<
 	TRequiresAuth extends boolean,
+	TOptionalAuth extends boolean | string,
 	TArgsSchema extends z.ZodType | undefined,
 	TOptionsSchema extends z.ZodType | undefined,
 >(definition: {
@@ -158,6 +159,7 @@ export function createSubcommand<
 	aliases?: string[];
 	toplevel?: boolean;
 	requiresAuth?: TRequiresAuth;
+	optionalAuth?: TOptionalAuth;
 	schema?: TArgsSchema extends z.ZodType
 		? TOptionsSchema extends z.ZodType
 			? { args: TArgsSchema; options: TOptionsSchema }
@@ -166,7 +168,15 @@ export function createSubcommand<
 			? { options: TOptionsSchema }
 			: never;
 	handler(
-		ctx: CommandContext<TRequiresAuth extends true ? true : false, TArgsSchema, TOptionsSchema>
+		ctx: CommandContext<
+			TRequiresAuth extends true
+				? true
+				: TOptionalAuth extends true | string
+					? true | false
+					: false,
+			TArgsSchema,
+			TOptionsSchema
+		>
 	): void | Promise<void>;
 }): SubcommandDefinition {
 	return definition as unknown as SubcommandDefinition;
@@ -175,6 +185,7 @@ export function createSubcommand<
 // Helper to create commands with proper type inference
 export function createCommand<
 	TRequiresAuth extends boolean,
+	TOptionalAuth extends boolean | string,
 	TArgsSchema extends z.ZodType | undefined,
 	TOptionsSchema extends z.ZodType | undefined,
 >(definition: {
@@ -183,6 +194,7 @@ export function createCommand<
 	aliases?: string[];
 	hidden?: boolean;
 	requiresAuth?: TRequiresAuth;
+	optionalAuth?: TOptionalAuth;
 	schema?: TArgsSchema extends z.ZodType
 		? TOptionsSchema extends z.ZodType
 			? { args: TArgsSchema; options: TOptionsSchema }
@@ -191,7 +203,15 @@ export function createCommand<
 			? { options: TOptionsSchema }
 			: never;
 	handler?(
-		ctx: CommandContext<TRequiresAuth extends true ? true : false, TArgsSchema, TOptionsSchema>
+		ctx: CommandContext<
+			TRequiresAuth extends true
+				? true
+				: TOptionalAuth extends true | string
+					? true | false
+					: false,
+			TArgsSchema,
+			TOptionsSchema
+		>
 	): void | Promise<void>;
 	subcommands?: SubcommandDefinition[];
 }): CommandDefinition {
@@ -206,6 +226,7 @@ export type SubcommandDefinition =
 			aliases?: string[];
 			toplevel?: boolean;
 			requiresAuth: true;
+			optionalAuth?: false | string;
 			schema?: CommandSchemas;
 			handler(ctx: CommandContext): void | Promise<void>;
 	  }
@@ -215,6 +236,17 @@ export type SubcommandDefinition =
 			aliases?: string[];
 			toplevel?: boolean;
 			requiresAuth?: false;
+			optionalAuth: true | string;
+			schema?: CommandSchemas;
+			handler(ctx: CommandContext): void | Promise<void>;
+	  }
+	| {
+			name: string;
+			description: string;
+			aliases?: string[];
+			toplevel?: boolean;
+			requiresAuth?: false;
+			optionalAuth?: false;
 			schema?: CommandSchemas;
 			handler(ctx: CommandContext): void | Promise<void>;
 	  };
@@ -227,6 +259,18 @@ export type CommandDefinition =
 			aliases?: string[];
 			hidden?: boolean;
 			requiresAuth: true;
+			optionalAuth?: false | string;
+			schema?: CommandSchemas;
+			handler?(ctx: CommandContext): void | Promise<void>;
+			subcommands?: SubcommandDefinition[];
+	  }
+	| {
+			name: string;
+			description: string;
+			aliases?: string[];
+			hidden?: boolean;
+			requiresAuth?: false;
+			optionalAuth: true | string;
 			schema?: CommandSchemas;
 			handler?(ctx: CommandContext): void | Promise<void>;
 			subcommands?: SubcommandDefinition[];
@@ -237,6 +281,7 @@ export type CommandDefinition =
 			aliases?: string[];
 			hidden?: boolean;
 			requiresAuth?: false;
+			optionalAuth?: false;
 			schema?: CommandSchemas;
 			handler?(ctx: CommandContext): void | Promise<void>;
 			subcommands?: SubcommandDefinition[];