@agentuity/cli 0.0.6

package/dist/types.d.ts

@@ -0,0 +1,164 @@
+import type { Logger } from './logger';
+import type * as z from 'zod';
+import { z as zod } from 'zod';
+export declare const ConfigSchema: z.ZodObject<{
+    name: z.ZodString;
+    auth: z.ZodOptional<z.ZodObject<{
+        api_key: z.ZodOptional<z.ZodString>;
+        user_id: z.ZodOptional<z.ZodString>;
+        expires: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    devmode: z.ZodOptional<z.ZodObject<{
+        hostname: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    overrides: z.ZodOptional<z.ZodObject<{
+        api_url: z.ZodOptional<z.ZodString>;
+        app_url: z.ZodOptional<z.ZodString>;
+        transport_url: z.ZodOptional<z.ZodString>;
+        websocket_url: z.ZodOptional<z.ZodString>;
+        skip_version_check: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    preferences: z.ZodOptional<z.ZodObject<{
+        last_update_check: z.ZodOptional<z.ZodNumber>;
+        last_legacy_warning: z.ZodOptional<z.ZodNumber>;
+        orgId: z.ZodOptional<z.ZodString>;
+        project_dir: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Config = zod.infer<typeof ConfigSchema>;
+export type LogLevel = 'debug' | 'trace' | 'info' | 'warn' | 'error';
+export interface Profile {
+    name: string;
+    filename: string;
+    selected: boolean;
+}
+export interface AuthData {
+    apiKey: string;
+    userId: string;
+    expires: Date;
+}
+export interface GlobalOptions {
+    config?: string;
+    logLevel: LogLevel;
+    logTimestamp?: boolean;
+    logPrefix?: boolean;
+}
+export interface CommandSchemas {
+    args?: z.ZodType;
+    options?: z.ZodType;
+}
+export type CommandContext<RequiresAuth extends boolean = false, ArgsSchema extends z.ZodType | undefined = undefined, OptionsSchema extends z.ZodType | undefined = undefined> = RequiresAuth extends true ? ArgsSchema extends z.ZodType ? OptionsSchema extends z.ZodType ? {
+    config: Config | null;
+    logger: Logger;
+    options: GlobalOptions;
+    auth: AuthData;
+    args: z.infer<ArgsSchema>;
+    opts: z.infer<OptionsSchema>;
+} : {
+    config: Config | null;
+    logger: Logger;
+    options: GlobalOptions;
+    auth: AuthData;
+    args: z.infer<ArgsSchema>;
+} : OptionsSchema extends z.ZodType ? {
+    config: Config | null;
+    logger: Logger;
+    options: GlobalOptions;
+    auth: AuthData;
+    opts: z.infer<OptionsSchema>;
+} : {
+    config: Config | null;
+    logger: Logger;
+    options: GlobalOptions;
+    auth: AuthData;
+} : ArgsSchema extends z.ZodType ? OptionsSchema extends z.ZodType ? {
+    config: Config | null;
+    logger: Logger;
+    options: GlobalOptions;
+    args: z.infer<ArgsSchema>;
+    opts: z.infer<OptionsSchema>;
+} : {
+    config: Config | null;
+    logger: Logger;
+    options: GlobalOptions;
+    args: z.infer<ArgsSchema>;
+} : OptionsSchema extends z.ZodType ? {
+    config: Config | null;
+    logger: Logger;
+    options: GlobalOptions;
+    opts: z.infer<OptionsSchema>;
+} : {
+    config: Config | null;
+    logger: Logger;
+    options: GlobalOptions;
+};
+export declare function createSubcommand<TRequiresAuth extends boolean, TArgsSchema extends z.ZodType | undefined, TOptionsSchema extends z.ZodType | undefined>(definition: {
+    name: string;
+    description: string;
+    aliases?: string[];
+    toplevel?: boolean;
+    requiresAuth?: TRequiresAuth;
+    schema?: TArgsSchema extends z.ZodType ? TOptionsSchema extends z.ZodType ? {
+        args: TArgsSchema;
+        options: TOptionsSchema;
+    } : {
+        args: TArgsSchema;
+    } : TOptionsSchema extends z.ZodType ? {
+        options: TOptionsSchema;
+    } : never;
+    handler(ctx: CommandContext<TRequiresAuth extends true ? true : false, TArgsSchema, TOptionsSchema>): void | Promise<void>;
+}): SubcommandDefinition;
+export declare function createCommand<TRequiresAuth extends boolean, TArgsSchema extends z.ZodType | undefined, TOptionsSchema extends z.ZodType | undefined>(definition: {
+    name: string;
+    description: string;
+    aliases?: string[];
+    hidden?: boolean;
+    requiresAuth?: TRequiresAuth;
+    schema?: TArgsSchema extends z.ZodType ? TOptionsSchema extends z.ZodType ? {
+        args: TArgsSchema;
+        options: TOptionsSchema;
+    } : {
+        args: TArgsSchema;
+    } : TOptionsSchema extends z.ZodType ? {
+        options: TOptionsSchema;
+    } : never;
+    handler?(ctx: CommandContext<TRequiresAuth extends true ? true : false, TArgsSchema, TOptionsSchema>): void | Promise<void>;
+    subcommands?: SubcommandDefinition[];
+}): CommandDefinition;
+export type SubcommandDefinition = {
+    name: string;
+    description: string;
+    aliases?: string[];
+    toplevel?: boolean;
+    requiresAuth: true;
+    schema?: CommandSchemas;
+    handler(ctx: CommandContext): void | Promise<void>;
+} | {
+    name: string;
+    description: string;
+    aliases?: string[];
+    toplevel?: boolean;
+    requiresAuth?: false;
+    schema?: CommandSchemas;
+    handler(ctx: CommandContext): void | Promise<void>;
+};
+export type CommandDefinition = {
+    name: string;
+    description: string;
+    aliases?: string[];
+    hidden?: boolean;
+    requiresAuth: true;
+    schema?: CommandSchemas;
+    handler?(ctx: CommandContext): void | Promise<void>;
+    subcommands?: SubcommandDefinition[];
+} | {
+    name: string;
+    description: string;
+    aliases?: string[];
+    hidden?: boolean;
+    requiresAuth?: false;
+    schema?: CommandSchemas;
+    handler?(ctx: CommandContext): void | Promise<void>;
+    subcommands?: SubcommandDefinition[];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Centralized version and package information
+ * Loads package.json once and caches it
+ */
+import pkg from '../package.json';
+export declare function getPackage(): typeof pkg;
+export declare function getVersion(): string;
+export declare function getPackageName(): string;
+export declare function getRevision(): string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,GAAG,MAAM,iBAAiB,CAAuB;AAKxD,wBAAgB,UAAU,IAAI,OAAO,GAAG,CAKvC;AAED,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,wBAAgB,WAAW,IAAI,MAAM,CAGpC"}

package/package.json

@@ -0,0 +1,46 @@
+{
+	"name": "@agentuity/cli",
+	"version": "0.0.6",
+	"type": "module",
+	"main": "./src/index.ts",
+	"types": "./dist/index.d.ts",
+	"bin": {
+		"agentuity": "./bin/cli.ts"
+	},
+	"exports": {
+		".": {
+			"import": "./src/index.ts",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"files": [
+		"AGENTS.md",
+		"README.md",
+		"src",
+		"dist",
+		"bin"
+	],
+	"scripts": {
+		"clean": "rm -rf dist",
+		"build": "bunx tsc --build --emitDeclarationOnly --force",
+		"typecheck": "bunx tsc --noEmit",
+		"test": "bun scripts/test-create-integration.ts",
+		"prepublishOnly": "bun run clean && bun run build",
+		"setup-dev-template": "bun scripts/setup-dev-template.ts",
+		"simulate-create": "bun scripts/simulate-bun-create.ts"
+	},
+	"dependencies": {
+		"@agentuity/core": "0.0.6",
+		"acorn-loose": "^8.5.2",
+		"astring": "^1.9.0",
+		"commander": "^14.0.2",
+		"enquirer": "^2.4.1",
+		"zod": "^4.1.12"
+	},
+	"devDependencies": {
+		"typescript": "^5.9.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}

package/src/api-errors.md

@@ -0,0 +1,115 @@
+# API Error Handling
+
+The `APIClient` class automatically handles various error conditions returned by the Agentuity API.
+
+## Error Response Format
+
+API errors follow this standard format:
+
+```json
+{
+	"success": false,
+	"code": "ERROR_CODE",
+	"message": "Human-readable error message",
+	"details": {}
+}
+```
+
+## Development Mode / Version Check Bypass
+
+For local development and testing, version checks can be bypassed using multiple methods (in priority order):
+
+### 1. CLI Flag (Highest Priority, Hidden)
+
+```bash
+agentuity --skip-version-check auth login
+```
+
+### 2. Environment Variable
+
+```bash
+export AGENTUITY_SKIP_VERSION_CHECK=1
+agentuity auth login
+```
+
+### 3. Profile/Config Override
+
+Add to your profile YAML file (e.g., `~/.config/agentuity/dev.yaml`):
+
+```yaml
+name: 'dev'
+overrides:
+   api_url: https://api.agentuity.io
+   app_url: https://app.agentuity.io
+   skip_version_check: true
+```
+
+### 4. Automatic Detection (Lowest Priority)
+
+Version checks are automatically skipped when:
+
+- Version is `"dev"` in package.json
+- Version starts with `"0.0."` (pre-release versions)
+
+**Important:** Skipping the version check only prevents the CLI from showing the upgrade error. If the API server enforces version requirements server-side (returns 409 status), the request will still fail. This is intended behavior to ensure API compatibility.
+
+## Handled Error Codes
+
+### UPGRADE_REQUIRED
+
+When the CLI version is outdated or incompatible with the API, the server returns:
+
+```json
+{
+	"success": false,
+	"code": "UPGRADE_REQUIRED",
+	"message": "Please upgrade to the latest version of the CLI. Instructions at https://agentuity.dev/CLI/installation"
+}
+```
+
+**Behavior:**
+
+- Throws `UpgradeRequiredError` (extends `Error`)
+- Commands should catch this and display a helpful upgrade message
+- Exits with code 1
+
+**Example handling:**
+
+```typescript
+import { UpgradeRequiredError } from '@agentuity/cli';
+
+try {
+	await apiCall();
+} catch (error) {
+	if (error instanceof UpgradeRequiredError) {
+		logger.error('⚠ CLI Upgrade Required');
+		logger.error(error.message);
+		logger.error('Visit: https://agentuity.dev/CLI/installation');
+		process.exit(1);
+	}
+	throw error;
+}
+```
+
+## Generic Error Handling
+
+For other API errors:
+
+1. If the response includes a `message` field, it's thrown as `Error(message)`
+2. Otherwise, throws `Error("API error: {status} {statusText}")`
+
+## Debug Mode
+
+Set `DEBUG=1` environment variable to see detailed error information:
+
+```bash
+DEBUG=1 agentuity auth login
+```
+
+This will print:
+
+- Request URL
+- HTTP method
+- Status code and text
+- Request headers
+- Response body

package/src/api.ts

@@ -0,0 +1,186 @@
+/**
+ * API Client for Agentuity Platform
+ *
+ * Handles HTTP requests to the API with automatic error parsing and User-Agent headers.
+ *
+ * Error handling:
+ * - UPGRADE_REQUIRED (409): Throws UpgradeRequiredError
+ * - Other errors: Throws Error with API message or status text
+ *
+ * See api-errors.md for full documentation.
+ */
+
+import type { Config } from './types';
+import { getVersion, getRevision } from './version';
+
+interface APIErrorResponse {
+	success: boolean;
+	code?: string;
+	message: string;
+	details?: Record<string, unknown>;
+}
+
+function getUserAgent(config?: Config | null): string {
+	// If we're skipping version check, send "dev" to signal the server to skip too
+	let version = getVersion();
+	if (shouldSkipVersionCheck(config)) {
+		version = 'dev';
+	}
+
+	const revision = getRevision();
+	return `Agentuity CLI/${version} (${revision})`;
+}
+
+function shouldSkipVersionCheck(config?: Config | null): boolean {
+	// Priority order:
+	// 1. CLI flag (set via env var in cli.ts)
+	// 2. Environment variable
+	// 3. Config override
+	// 4. Auto-detection (dev/0.0.x versions)
+
+	// Skip if environment variable is set (includes CLI flag)
+	if (
+		process.env.AGENTUITY_SKIP_VERSION_CHECK === '1' ||
+		process.env.AGENTUITY_SKIP_VERSION_CHECK === 'true'
+	) {
+		return true;
+	}
+
+	// Check config overrides
+	const overrides = config?.overrides as { skip_version_check?: boolean } | undefined;
+	if (overrides?.skip_version_check === true) {
+		return true;
+	}
+
+	// Skip if version is 'dev' or starts with '0.0.' (pre-release/local development)
+	const version = getVersion();
+	if (version === 'dev' || version.startsWith('0.0.')) {
+		return true;
+	}
+
+	return false;
+}
+
+export class UpgradeRequiredError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = 'UpgradeRequiredError';
+	}
+}
+
+export class APIClient {
+	constructor(
+		private baseUrl: string,
+		private apiKey?: string,
+		private config?: Config | null
+	) {}
+
+	async request<T>(method: string, endpoint: string, body?: unknown): Promise<T> {
+		const url = `${this.baseUrl}${endpoint}`;
+		const headers: Record<string, string> = {
+			'Content-Type': 'application/json',
+			'User-Agent': getUserAgent(this.config),
+		};
+
+		if (this.apiKey) {
+			headers['Authorization'] = `Bearer ${this.apiKey}`;
+		}
+
+		const response = await fetch(url, {
+			method,
+			headers,
+			body: body ? JSON.stringify(body) : undefined,
+		});
+
+		if (!response.ok) {
+			const responseBody = await response.text();
+
+			// Try to parse error response
+			let errorData: APIErrorResponse | null = null;
+			try {
+				errorData = JSON.parse(responseBody) as APIErrorResponse;
+			} catch {
+				// Not JSON, ignore
+			}
+
+			if (process.env.DEBUG) {
+				// Sanitize headers to avoid leaking API keys
+				const sanitizedHeaders = { ...headers };
+				for (const key in sanitizedHeaders) {
+					if (key.toLowerCase() === 'authorization') {
+						sanitizedHeaders[key] = 'REDACTED';
+					}
+				}
+
+				console.error('API Error Details:');
+				console.error('  URL:', url);
+				console.error('  Method:', method);
+				console.error('  Status:', response.status, response.statusText);
+				console.error('  Headers:', JSON.stringify(sanitizedHeaders, null, 2));
+				console.error('  Response:', responseBody);
+			}
+
+			// Check for UPGRADE_REQUIRED error
+			if (errorData?.code === 'UPGRADE_REQUIRED') {
+				// Skip version check in development
+				if (shouldSkipVersionCheck(this.config)) {
+					if (process.env.DEBUG) {
+						console.error(
+							'[DEBUG] Skipping version check (flag/env/config override or dev mode)'
+						);
+					}
+					// Continue as if there was no error - the server should still process the request
+					// but we'll throw a different error since we can't continue with a 409
+					throw new Error('Version check skipped, but request failed. Try upgrading the CLI.');
+				}
+
+				throw new UpgradeRequiredError(
+					errorData.message || 'Please upgrade to the latest version of the CLI'
+				);
+			}
+
+			// Throw with message from API if available
+			if (errorData?.message) {
+				throw new Error(errorData.message);
+			}
+
+			throw new Error(`API error: ${response.status} ${response.statusText}`);
+		}
+
+		// Successful response; handle empty bodies (e.g., 204 No Content)
+		if (response.status === 204) {
+			return undefined as T;
+		}
+		const contentLength = response.headers.get('content-length');
+		if (contentLength === '0') {
+			return undefined as T;
+		}
+		return response.json() as Promise<T>;
+	}
+}
+
+export function getAPIBaseURL(config?: Config | null): string {
+	if (process.env.AGENTUITY_API_URL) {
+		return process.env.AGENTUITY_API_URL;
+	}
+
+	const overrides = config?.overrides as { api_url?: string } | undefined;
+	if (overrides?.api_url) {
+		return overrides.api_url;
+	}
+
+	return 'https://api.agentuity.com';
+}
+
+export function getAppBaseURL(config?: Config | null): string {
+	if (process.env.AGENTUITY_APP_URL) {
+		return process.env.AGENTUITY_APP_URL;
+	}
+
+	const overrides = config?.overrides as { app_url?: string } | undefined;
+	if (overrides?.app_url) {
+		return overrides.app_url;
+	}
+
+	return 'https://app.agentuity.com';
+}

package/src/auth.ts

@@ -0,0 +1,91 @@
+import { existsSync } from 'node:fs';
+import { getDefaultConfigDir, getAuth } from './config';
+import { getCommand } from './command-prefix';
+import type { CommandContext, AuthData } from './types';
+import * as tui from './tui';
+
+export function isTTY(): boolean {
+	return process.stdin.isTTY === true && process.stdout.isTTY === true;
+}
+
+export function hasLoggedInBefore(): boolean {
+	const configDir = getDefaultConfigDir();
+	return existsSync(configDir);
+}
+
+export async function isAuthenticated(): Promise<boolean> {
+	const auth = await getAuth();
+	if (!auth) {
+		return false;
+	}
+	return auth.expires > new Date();
+}
+
+export async function requireAuth(ctx: CommandContext<false>): Promise<AuthData> {
+	const { logger } = ctx;
+	const auth = await getAuth();
+
+	if (auth && auth.expires > new Date()) {
+		return auth;
+	}
+
+	const loginCmd = getCommand('auth login');
+	const hasConfig = hasLoggedInBefore();
+
+	if (!isTTY()) {
+		if (hasConfig) {
+			logger.fatal(
+				`You are not currently logged in or your session has expired.\n` +
+					`Use "${loginCmd}" to login to Agentuity`
+			);
+		} else {
+			logger.fatal(
+				`Authentication required.\n` + `Use "${loginCmd}" to create an account or login`
+			);
+		}
+	}
+
+	// Interactive mode - prompt user to login
+	tui.newline();
+	tui.warning(
+		hasConfig
+			? 'You are not currently logged in or your session has expired.'
+			: 'Authentication required to continue.'
+	);
+	tui.newline();
+
+	const shouldLogin = await tui.confirm(
+		hasConfig ? 'Would you like to login now?' : 'Would you like to create an account or login?',
+		true
+	);
+
+	if (!shouldLogin) {
+		logger.fatal(`Authentication required. Run "${loginCmd}" when you're ready to continue.`);
+	}
+
+	// Import and run login flow
+	const { loginCommand } = await import('./cmd/auth/login');
+	await loginCommand.handler(ctx);
+
+	// After login completes, verify we have auth
+	const newAuth = await getAuth();
+	if (!newAuth || newAuth.expires <= new Date()) {
+		return logger.fatal('Login was not completed successfully.');
+	}
+
+	return newAuth;
+}
+
+export function withAuth<TArgs extends unknown[]>(
+	ctx: CommandContext<false>,
+	handler: (ctx: CommandContext<true>, ...args: TArgs) => Promise<void> | void
+): (...args: TArgs) => Promise<void> {
+	return async (...args: TArgs) => {
+		const auth = await requireAuth(ctx);
+		const authenticatedCtx: CommandContext<true> = {
+			...ctx,
+			auth,
+		};
+		return handler(authenticatedCtx, ...args);
+	};
+}

package/src/banner.ts

@@ -0,0 +1,23 @@
+export function showBanner(version: string): void {
+	const CYAN = Bun.color('cyan', 'ansi-16m');
+	const RESET = '\x1b[0m';
+
+	const width = 52; // Content width between pipes
+	const versionLabel = ' Version:        '; // Include leading space
+	const versionPadding = width - versionLabel.length - 1; // Subtract 1 for the space before closing pipe
+
+	const lines = [
+		'╭────────────────────────────────────────────────────╮',
+		'│ ⨺ Agentuity     Build, manage and deploy AI agents │',
+		'│                                                    │',
+		`│${versionLabel}${version.padEnd(versionPadding)} │`,
+		'│ Docs:           https://agentuity.dev              │',
+		'│ Community:      https://discord.gg/agentuity       │',
+		'│ Dashboard:      https://app.agentuity.com          │',
+		'╰────────────────────────────────────────────────────╯',
+	];
+
+	console.log('');
+	lines.forEach((line) => console.log(CYAN + line + RESET));
+	console.log('');
+}