@agentuity/cli 0.1.15 → 0.1.17

package/src/onboarding/agentPrompt.ts

@@ -0,0 +1,263 @@
+/**
+ * Agent Onboarding Prompt
+ *
+ * This generates the markdown prompt that coding agents use to guide developers
+ * through Agentuity setup after the CLI has been installed.
+ */
+
+export function getAgentPromptMarkdown(): string {
+	return `
+**Your goal:** Guide the user from zero to a deployed Agentuity project, then help them understand what they have and what to do next.
+
+---
+
+## What is Agentuity?
+
+Agentuity is the full-stack platform for AI agents. Briefly explain to the user:
+
+- **Full-stack agents**: Build agents, APIs, and front-end integrations with end-to-end type safety
+- **Bun/TypeScript SDKs**: First-class developer experience with the fastest JavaScript runtime
+- **AI Gateway**: Unified access to LLMs (OpenAI-compatible SDK) with single billing—no separate API keys needed
+- **Observability**: Logs, tracing, and evals built-in so you can debug and improve agents
+- **Production services**: Sandboxes, storage (S3-compatible), Postgres, KV, and enterprise features available as you grow
+
+We're going to be setting up the default template quickly.
+
+The default template includes AI Gateway integration, thread state persistence, structured logging, Tailwind CSS, and a local Workbench at \`/workbench\` for testing agents.
+
+---
+
+## How to Guide the User
+
+**Your job is to make onboarding as smooth as possible with minimal user interaction.**
+
+1. **Start by briefly explaining** what Agentuity is and what you'll help them accomplish
+2. **Run commands automatically** when you have terminal access—don't ask permission for each step
+3. **Only pause for human action** when absolutely required
+4. **At each step**: Briefly explain what it does and why, then execute
+5. **Celebrate success**: When deployment completes, make sure the user knows they earned free credits and show them what to explore next
+
+Assume the user is technical but new to Agentuity. Be warm, efficient, and action-oriented. The goal is a successful deployment with as few interruptions as possible.
+
+---
+
+## Onboarding Steps
+
+### Step 1: You're Already Logged In!
+
+**The install command automatically authenticated you.** No manual login needed.
+
+Verify with:
+\`\`\`bash
+agentuity auth whoami
+\`\`\`
+
+This outputs your user info including your \`org_id\`. You'll need this for the create command.
+
+---
+
+### Step 2: Create a New Project
+
+**Why:** This scaffolds a full-stack agent app with AI Gateway, persistence, logging, and a testing UI.
+
+**First, get the user's organization ID:**
+\`\`\`bash
+agentuity auth whoami
+\`\`\`
+
+This outputs the user's info including their \`org_id\`. You'll need this for the create command.
+
+**Then create the project (non-interactive):**
+\`\`\`bash
+agentuity create --name "my-first-agent" --org-id <ORG_ID> --region usc --confirm
+\`\`\`
+
+**Required flags for non-interactive mode:**
+- \`--name\`: Project name (use \`my-first-agent\` as default)
+- \`--org-id\`: The organization ID from \`agentuity auth whoami\` (required in non-interactive mode)
+- \`--region\`: Cloud region (use \`usc\` for US Central, or \`use\` for US East)
+- \`--confirm\`: Skips interactive prompts
+
+**Example with real org ID:**
+\`\`\`bash
+agentuity create --name "my-first-agent" --org-id ..... --region usc --confirm
+\`\`\`
+
+If the user wants a different location, add \`--dir\`:
+\`\`\`bash
+agentuity create --name "my-first-agent" --org-id <ORG_ID> --region usc --dir ~/projects/my-first-agent --confirm
+\`\`\`
+
+After creation, \`cd\` into the project directory.
+
+**Docs:** https://agentuity.dev/Get-Started/quickstart
+
+---
+
+### Step 3: Run Locally
+
+**Why:** Start the development server to test the project locally before deploying.
+
+**Command:**
+\`\`\`bash
+agentuity dev
+\`\`\`
+
+**⚠️ This is a long-running process!** The dev server runs continuously until killed. Before or after starting it, **immediately tell the user what to do** — don't just wait silently.
+
+**What happens:**
+- **Local server** starts at \`http://localhost:3500\` — this is where your APIs and agents are served
+- **Workbench** available at \`http://localhost:3500/workbench\` — a built-in UI for testing and interacting with your agents directly, without needing a frontend
+- **Public tunnel URL** is automatically created — the CLI will display a public URL that tunnels to your local server, useful for testing webhooks or sharing with others
+- **Hot reload** enabled — code changes reflect immediately
+
+**Immediately after starting the dev server, tell the user:**
+
+> "The dev server is now running! Here's what to try:
+>
+> 1. Open **http://localhost:3500** to see the app
+> 2. Open **http://localhost:3500/workbench** to interact with your agents (this is a key feature!)
+> 3. The public tunnel URL shown in the terminal can be shared with others
+>
+> Take a few minutes to explore. When you're ready to deploy to production, let me know!"
+
+**Wait for the user to confirm** they're ready to deploy before proceeding to Step 4.
+
+**Keyboard shortcuts** while dev server runs: \`h\` for help, \`r\` to restart, \`q\` to quit.
+
+**Docs:** https://agentuity.dev/Reference/CLI/development
+
+---
+
+### Step 4: Deploy to Production
+
+**Why:** Make the project live with observability, logs, and analytics.
+
+**Important:** Deploying their first project earns the user **free credits** to continue experimenting with the platform. Make sure they know this is a reward for completing onboarding!
+
+**First, stop the dev server:**
+Before deploying, you must stop the dev server that's still running from Step 3. Send \`Ctrl+C\` or \`q\` to the terminal running \`agentuity dev\` to gracefully shut it down. Don't leave it running or you'll have an orphaned process on port 3500.
+
+**Then deploy:**
+\`\`\`bash
+agentuity deploy
+\`\`\`
+
+**What happens:**
+- Project builds and deploys to Agentuity's global edge network
+- The CLI will output the production URL when deployment succeeds
+- Observability (logs, tracing, analytics) is now live
+- **Free credits are awarded** for their first deployment
+
+**⚠️ CRITICAL: Do not hallucinate URLs!**
+- **Only show the user URLs that the CLI actually outputs**
+- Do not make up or guess production URLs (e.g., don't invent \`https://project-name.agentuity.app\`)
+- If the deploy command fails or doesn't show a URL, tell the user to check the dashboard instead
+- If there's an error, report the actual error message from the CLI
+
+**After successful deployment:**
+1. Show the user the **exact production URL from the CLI output**
+2. Direct them to the Agentuity dashboard at https://app.agentuity.com to:
+   - View their deployed project
+   - Explore logs and traces
+   - See their credit balance
+   - Monitor analytics
+
+**If deployment fails or shows errors:**
+- Report the actual error message
+- Don't claim success if the CLI didn't confirm it
+- Suggest checking the dashboard for deployment status
+
+---
+
+## What the Template Provides
+
+After deployment, explain what they now have:
+
+| Feature | What It Does |
+|---------|--------------|
+| **AI Gateway** | OpenAI-compatible SDK routed through Agentuity—unified billing, no separate API keys |
+| **Thread State** | Conversations and agent state persist automatically for multi-turn flows |
+| **Structured Logging** | Logs and traces captured for debugging and analytics |
+| **Workbench** | Local UI at \`/workbench\` for testing agents without a frontend |
+| **Tailwind CSS** | Pre-configured styling for the frontend |
+| **Type Safety** | End-to-end types from agent schemas to API routes to frontend |
+
+---
+
+## Next Steps
+
+After successful deployment, guide the user through these recommendations:
+
+### 1. Celebrate the Free Credits!
+- Remind the user: their first deployment earned them **free credits** to keep experimenting
+- They can view their credit balance in the Agentuity dashboard
+- These credits let them continue building and testing without upfront cost
+
+### 2. Join the Community
+- **Discord**: https://discord.gg/agentuity
+- Get help, see examples, share what you're building
+
+### 3. Explore the Dashboard
+- **Observability**: View logs, traces, and evals for your deployment
+- **Deployments**: See version history with rollback options
+- **Analytics**: Monitor usage and performance
+
+### 4. Connect GitHub
+- Enable GitHub integration in project settings for:
+  - Automatic deployments from branches
+  - CI/CD workflows
+  - Team collaboration
+
+### 5. Explore Additional Services
+As your project grows, Agentuity provides:
+- **Postgres**: Relational database
+- **KV**: Fast key-value storage
+- **Storage**: S3-compatible file storage
+- **Sandboxes**: Isolated execution environments
+
+### 6. Customize Your Agents
+The SDK makes it easy to:
+- Add new agents in \`src/agent/\` (just add a folder with \`agent.ts\`)
+- Create API routes in \`src/api/\`
+- Build type-safe frontend integrations
+
+**Docs:** https://agentuity.dev/Get-Started/project-structure
+
+---
+
+## Handling Common Issues
+
+- **Bun not installed**: The CLI will prompt to install it, or run: \`curl -fsSL https://bun.sh/install | bash\`
+- **Login fails/times out**: Rerun \`agentuity login\` and check browser
+- **Port 3500 in use**: Kill the existing process or use \`agentuity dev --port 8080\`
+- **Deploy fails**: Check build errors in CLI output, ensure you're in the project directory
+
+---
+
+## Success Criteria
+
+**Onboarding is successful when the user has:**
+
+1. ✅ **CLI installed** and authenticated
+2. ✅ **Local dev environment running** — they've seen \`localhost:3500\` and tried the Workbench
+3. ✅ **First deployment complete** — they have a live production URL
+4. ✅ **Free credits earned** — they know they've been rewarded and can keep building
+5. ✅ **Clear next steps** — they know about Discord, the dashboard, and how to extend their project
+
+**Make them feel accomplished!** They just went from zero to a deployed AI agent platform in minutes.
+
+---
+
+## Style Guidelines
+
+- Keep explanations short and practical
+- Explain what & why at each step
+- Give exact commands
+- Handle errors calmly with concrete suggestions
+- Be explicit when human action is required
+- Use non-interactive CLI flags (\`--confirm\`, \`--name\`, \`--org-id\`, \`--region usc\`, \`--dir\`) for smooth automation
+- **Never hallucinate or make up information** — only report URLs, IDs, and status from actual CLI output
+- If something fails or you're unsure, say so honestly and direct the user to the dashboard
+`;
+}

package/src/schema-generator.ts

@@ -13,7 +13,7 @@ export interface SchemaArgument {
 
 export interface SchemaOption {
 	name: string;
-	type: 'string' | 'number' | 'boolean' | 'array';
+	type: 'string' | 'number' | 'boolean' | 'array' | 'optionalString';
 	required: boolean;
 	default?: unknown;
 	description?: string;

package/src/schema-parser.ts

@@ -13,7 +13,7 @@ export interface ParsedArgs {
 export interface ParsedOption {
 	name: string;
 	description?: string;
-	type: 'string' | 'number' | 'boolean' | 'array';
+	type: 'string' | 'number' | 'boolean' | 'array' | 'optionalString';
 	hasDefault?: boolean;
 	defaultValue?: unknown;
 	enumValues?: string[];
@@ -57,6 +57,45 @@ function unwrapSchema(schema: unknown): unknown {
 	return current;
 }
 
+/**
+ * Check if a schema is a union of boolean and string (for optional string flags like --org [value])
+ * This pattern is used when a flag can be used as a boolean (--org) or with a value (--org=myOrgId)
+ */
+function isBooleanStringUnion(schema: unknown): boolean {
+	const unwrapped = unwrapSchema(schema) as ZodTypeInternal;
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	const def = unwrapped?._def as any;
+	// Zod 3 uses typeName, Zod 4 uses type
+	const typeId = def?.typeName || def?.type;
+
+	if (typeId !== 'ZodUnion' && typeId !== 'union') {
+		return false;
+	}
+
+	// Zod 3 uses _def.options, Zod 4 uses .options directly on the schema or _def.options
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	const options = def?.options || (unwrapped as any)?.options;
+	if (!Array.isArray(options) || options.length !== 2) {
+		return false;
+	}
+
+	const types = new Set<string>();
+	for (const opt of options) {
+		// Zod 4: type is directly on the object as .type
+		// Zod 3: type is _def.typeName
+		const optUnknown = opt as unknown as Record<string, unknown>;
+		const optDef = optUnknown?._def as Record<string, unknown> | undefined;
+		const optType =
+			(optUnknown?.type as string) || (optDef?.typeName as string) || (optDef?.type as string);
+		types.add(optType);
+	}
+
+	return (
+		(types.has('boolean') || types.has('ZodBoolean')) &&
+		(types.has('string') || types.has('ZodString'))
+	);
+}
+
 function getShape(schema: ZodType): Record<string, unknown> {
 	const unwrapped = unwrapSchema(schema) as ZodTypeInternal;
 	const typeId = unwrapped?._def?.typeName || unwrapped?._def?.type;
@@ -182,9 +221,12 @@ export function parseOptionsSchema(schema: ZodType): ParsedOption[] {
 			}
 		}
 
-		let type: 'string' | 'number' | 'boolean' | 'array' = 'string';
+		let type: 'string' | 'number' | 'boolean' | 'array' | 'optionalString' = 'string';
 		let enumValues: string[] | undefined;
-		if (typeId === 'ZodNumber' || typeId === 'number') {
+		if (isBooleanStringUnion(value)) {
+			// z.union([z.boolean(), z.string()]) - flag can be used as --flag or --flag=value
+			type = 'optionalString';
+		} else if (typeId === 'ZodNumber' || typeId === 'number') {
 			type = 'number';
 		} else if (typeId === 'ZodBoolean' || typeId === 'boolean') {
 			type = 'boolean';

package/src/tui/box.ts

@@ -198,3 +198,55 @@ export function note(message: string, title = ''): void {
 	});
 	console.log(output);
 }
+
+/**
+ * Draw an error box with red border
+ */
+export function errorBox(title: string, message: string): void {
+	const termWidth = getTerminalWidth();
+	const maxWidth = termWidth - 3;
+	const boxWidth = Math.min(60, maxWidth);
+	const innerWidth = Math.max(boxWidth - 2, 1);
+	const contentWidth = Math.max(innerWidth - 1, 0);
+	const padding = 2;
+
+	const lines: string[] = [];
+
+	// Title line with error symbol
+	const errorSymbol = colors.error('✗');
+	const titleText = colors.error(title);
+	const titleTextWidth = 1 + stringWidth(title); // symbol + title
+	const barsNeeded = Math.max(innerWidth - titleTextWidth - 3, 1);
+	const titleLine = `${errorSymbol}  ${titleText} ${colors.error(symbols.barH.repeat(barsNeeded) + symbols.cornerTR)}`;
+
+	lines.push(colors.error(symbols.bar));
+	lines.push(titleLine);
+
+	// Empty line
+	const emptyLine = `${colors.error(symbols.bar)}${' '.repeat(contentWidth)}${colors.error(symbols.bar)}`;
+	lines.push(emptyLine);
+
+	// Wrap and render content lines
+	const wrapWidth = Math.max(contentWidth - padding * 2, 0);
+	const contentLines = message.split('\n');
+	for (const line of contentLines) {
+		const wrapped = stringWidth(line) > wrapWidth ? wrapText(line, wrapWidth) : [line];
+		for (const wl of wrapped) {
+			const lineLen = stringWidth(wl);
+			const leftPad = padding;
+			const rightPad = Math.max(contentWidth - lineLen - leftPad, 0);
+			lines.push(
+				`${colors.error(symbols.bar)}${' '.repeat(leftPad)}${wl}${' '.repeat(rightPad)}${colors.error(symbols.bar)}`
+			);
+		}
+	}
+
+	lines.push(emptyLine);
+
+	// Bottom border
+	lines.push(
+		colors.error(symbols.connect + symbols.barH.repeat(innerWidth - 1) + symbols.cornerBR)
+	);
+
+	console.log(lines.join('\n'));
+}

package/src/tui.ts

@@ -45,7 +45,7 @@ export { maskSecret };
 // Export new TUI components
 export { createPrompt, PromptFlow } from './tui/prompt';
 export { group } from './tui/group';
-export { note, drawBox } from './tui/box';
+export { note, drawBox, errorBox } from './tui/box';
 export { symbols } from './tui/symbols';
 export { colors as tuiColors } from './tui/colors';
 export type {
@@ -834,7 +834,9 @@ export function showLoggedOutMessage(appBaseUrl: string, hasProfile = false): vo
 	// Box format: "║ " + content + "║" = 48 chars total
 	// Content area = 46 chars, with leading space = 45 chars for URL + padding
 	const urlPadding = Math.max(0, 45 - signupURL.length);
-	const showNewLine = showInline ? '' : `║ ${RESET}${link(signupURL)}${YELLOW}${' '.repeat(urlPadding)}║`;
+	const showNewLine = showInline
+		? ''
+		: `║ ${RESET}${link(signupURL)}${YELLOW}${' '.repeat(urlPadding)}║`;
 
 	const lines = [
 		'╔══════════════════════════════════════════════╗',
@@ -1057,6 +1059,11 @@ export interface SimpleSpinnerOptions<T> {
 	 * Defaults to false
 	 */
 	clearOnSuccess?: boolean;
+	/**
+	 * If true, suppress the error message display on failure (for custom error handling)
+	 * Defaults to false
+	 */
+	clearOnError?: boolean;
 }
 
 /**
@@ -1071,6 +1078,11 @@ export interface ProgressSpinnerOptions<T> {
 	 * Defaults to false
 	 */
 	clearOnSuccess?: boolean;
+	/**
+	 * If true, suppress the error message display on failure (for custom error handling)
+	 * Defaults to false
+	 */
+	clearOnError?: boolean;
 }
 
 /**
@@ -1196,8 +1208,12 @@ export async function spinner<T>(
 
 			return result;
 		} catch (err) {
-			const errorColor = getColor('error');
-			console.error(`${errorColor}${ICONS.error} ${message}${reset}`);
+			const clearOnError =
+				(options.type === 'progress' || options.type === 'simple') && options.clearOnError;
+			if (!clearOnError) {
+				const errorColor = getColor('error');
+				console.error(`${errorColor}${ICONS.error} ${message}${reset}`);
+			}
 			throw err;
 		}
 	}
@@ -1426,10 +1442,14 @@ export async function spinner<T>(
 		}
 		process.stderr.write('\x1B[?25h'); // Show cursor
 
-		// Show error
-		const errorColor = getColor('error');
-		const errorMessage = err instanceof Error ? err.message : String(err);
-		console.error(`${errorColor}${ICONS.error} ${message}: ${errorMessage}${reset}`);
+		// Show error (unless clearOnError is set for custom error handling)
+		const clearOnError =
+			(options.type === 'progress' || options.type === 'simple') && options.clearOnError;
+		if (!clearOnError) {
+			const errorColor = getColor('error');
+			const errorMessage = err instanceof Error ? err.message : String(err);
+			console.error(`${errorColor}${ICONS.error} ${message}: ${errorMessage}${reset}`);
+		}
 
 		throw err;
 	}
@@ -1759,23 +1779,33 @@ export async function selectOrganization(
 		return orgs[0].id;
 	}
 
-	if (!process.stdin.isTTY) {
-		if (initial) {
-			return initial;
+	// Use saved preference if available (regardless of TTY mode)
+	// This allows consistent behavior without prompting on every command
+	if (initial) {
+		const initialOrg = orgs.find((o) => o.id === initial);
+		if (initialOrg) {
+			return initialOrg.id;
 		}
-		fatal(
-			'Organization selection required but cannot prompt in non-interactive environment. Set AGENTUITY_CLOUD_ORG_ID or provide a default organization using --org-id'
-		);
 	}
 
-	// Find the index of the initial org to pre-select it in the list
-	const initialIndex = initial ? orgs.findIndex((o) => o.id === initial) : -1;
+	// Check for non-interactive environment (check both stdin and stdout)
+	const isNonInteractive = !process.stdin.isTTY || !process.stdout.isTTY;
+	if (isNonInteractive) {
+		// In non-interactive mode with multiple orgs, auto-select first org
+		// This allows scripts and CI/CD to work without explicit org selection
+		warning(
+			`Multiple organizations found. Auto-selecting first org: ${orgs[0].name}. ` +
+				`Set AGENTUITY_CLOUD_ORG_ID or use --org-id to specify a different org.`
+		);
+		return orgs[0].id;
+	}
 
+	// Interactive mode with no saved preference - prompt user
 	const response = await enquirer.prompt<{ action: string }>({
 		type: 'select',
 		name: 'action',
 		message: 'Select an organization',
-		initial: initialIndex >= 0 ? initialIndex : 0,
+		initial: 0,
 		choices: orgs.map((o) => ({ message: o.name, name: o.id })),
 	});
 

package/src/types.ts

@@ -62,7 +62,6 @@ export const ConfigSchema = zod.object({
 		})
 		.optional()
 		.describe('the gravity client information'),
-
 });
 
 export type Config = zod.infer<typeof ConfigSchema>;