@agentuity/cli 0.1.31 → 0.1.33

package/src/cmd/cloud/env/pull.ts

@@ -1,5 +1,4 @@
 import { z } from 'zod';
-import { join } from 'node:path';
 import { createSubcommand } from '../../../types';
 import * as tui from '../../../tui';
 import { projectGet, orgEnvGet } from '@agentuity/server';
@@ -8,7 +7,6 @@ import {
 	readEnvFile,
 	writeEnvFile,
 	mergeEnvVars,
-	isReservedAgentuityKey,
 } from '../../../env-util';
 import { getCommand } from '../../../command-prefix';
 import { resolveOrgId, isOrgScope } from './org-util';
@@ -93,7 +91,7 @@ export const pullSubcommand = createSubcommand({
 		const targetEnvPath = await findExistingEnvFile(projectDir);
 		const localEnv = await readEnvFile(targetEnvPath);
 
-		// Preserve local AGENTUITY_SDK_KEY before writing (since it will be skipped in the first write)
+		// Preserve local AGENTUITY_SDK_KEY
 		const localSdkKey = localEnv.AGENTUITY_SDK_KEY;
 
 		// Merge: cloud values override local if force=true, otherwise keep local
@@ -106,32 +104,25 @@ export const pullSubcommand = createSubcommand({
 			mergedEnv = mergeEnvVars(cloudEnv, localEnv);
 		}
 
-		// Write to .env (skip reserved AGENTUITY_ keys, except AGENTUITY_PUBLIC_)
+		// Determine the SDK key to use: cloud api_key is source of truth, fallback to local
+		const sdkKeyToWrite = cloudApiKey || localSdkKey;
+		if (sdkKeyToWrite) {
+			mergedEnv.AGENTUITY_SDK_KEY = sdkKeyToWrite;
+		}
+
+		// Write to .env in a single operation, preserveExisting: false since we have the full merged state
 		await writeEnvFile(targetEnvPath, mergedEnv, {
-			skipKeys: Object.keys(mergedEnv).filter(isReservedAgentuityKey),
+			preserveExisting: false,
+			addComment: (key) => {
+				if (key === 'AGENTUITY_SDK_KEY') {
+					return 'AGENTUITY_SDK_KEY is a sensitive value and should not be committed to version control.';
+				}
+				return null;
+			},
 		});
 
-		// Restore AGENTUITY_SDK_KEY to .env (cloud is source of truth, fallback to local)
-		// The key was removed by the write above since it's in skipKeys, so we need to restore it
-		const dotEnvPath = join(projectDir, '.env');
-		const dotEnv = await readEnvFile(dotEnvPath);
-
-		// Cloud is source of truth: use cloud api_key if available, otherwise fallback to local
-		// For org scope, only restore if local key exists (orgs don't have api_key)
-		const sdkKeyToWrite = cloudApiKey || localSdkKey;
-		if (sdkKeyToWrite) {
-			dotEnv.AGENTUITY_SDK_KEY = sdkKeyToWrite;
-			await writeEnvFile(dotEnvPath, dotEnv, {
-				addComment: (key) => {
-					if (key === 'AGENTUITY_SDK_KEY') {
-						return 'AGENTUITY_SDK_KEY is a sensitive value and should not be committed to version control.';
-					}
-					return null;
-				},
-			});
-			if (cloudApiKey && cloudApiKey !== localSdkKey) {
-				tui.info(`Wrote AGENTUITY_SDK_KEY to ${dotEnvPath}`);
-			}
+		if (cloudApiKey && cloudApiKey !== localSdkKey) {
+			tui.info(`Wrote AGENTUITY_SDK_KEY to ${targetEnvPath}`);
 		}
 
 		const count = Object.keys(cloudEnv).length;

package/src/cmd/cloud/env/set.ts

@@ -4,9 +4,7 @@ import * as tui from '../../../tui';
 import { projectEnvUpdate, orgEnvUpdate } from '@agentuity/server';
 import {
 	findExistingEnvFile,
-	readEnvFile,
 	writeEnvFile,
-	filterAgentuitySdkKeys,
 	looksLikeSecret,
 	isReservedAgentuityKey,
 	isPublicVarKey,
@@ -145,12 +143,8 @@ export const setSubcommand = createSubcommand({
 			let envFilePath: string | undefined;
 			if (projectDir) {
 				envFilePath = await findExistingEnvFile(projectDir);
-				const currentEnv = await readEnvFile(envFilePath);
-				currentEnv[args.key] = args.value;
-
-				// Filter out AGENTUITY_ keys before writing
-				const filteredEnv = filterAgentuitySdkKeys(currentEnv);
-				await writeEnvFile(envFilePath, filteredEnv);
+				// Write only the new key - writeEnvFile preserves existing keys by default
+				await writeEnvFile(envFilePath, { [args.key]: args.value });
 			}
 
 			const successMsg = envFilePath

package/src/cmd/cloud/region-lookup.ts

@@ -2,7 +2,7 @@ import type { Logger } from '@agentuity/core';
 import { projectGet, sandboxGet, deploymentGet, type APIClient } from '@agentuity/server';
 import { getResourceRegion, setResourceRegion } from '../../cache';
 import { getGlobalCatalystAPIClient } from '../../config';
-import type { AuthData } from '../../types';
+import type { AuthData, Config } from '../../types';
 import * as tui from '../../tui';
 import { ErrorCode } from '../../errors';
 
@@ -35,7 +35,8 @@ export async function getIdentifierRegion(
 	apiClient: APIClient,
 	profileName = 'production',
 	identifier: string,
-	orgId?: string
+	orgId?: string,
+	config?: Config | null
 ): Promise<string> {
 	const identifierType = getIdentifierType(identifier);
 
@@ -57,8 +58,14 @@ export async function getIdentifierRegion(
 		const deployment = await deploymentGet(apiClient, identifier);
 		region = deployment.cloudRegion ?? null;
 	} else {
-		// sandbox
-		const globalClient = await getGlobalCatalystAPIClient(logger, auth, profileName);
+		// sandbox - pass config to getGlobalCatalystAPIClient for proper region resolution
+		const globalClient = await getGlobalCatalystAPIClient(
+			logger,
+			auth,
+			profileName,
+			orgId,
+			config
+		);
 		const sandbox = await sandboxGet(globalClient, { sandboxId: identifier, orgId });
 		region = sandbox.region ?? null;
 	}
@@ -70,6 +77,14 @@ export async function getIdentifierRegion(
 		);
 	}
 
+	// Validate region is a non-empty string
+	if (typeof region !== 'string' || region.trim() === '') {
+		tui.fatal(
+			`Invalid region returned for ${identifierType} '${identifier}': '${region}'. Use --region flag to specify a valid region.`,
+			ErrorCode.RESOURCE_NOT_FOUND
+		);
+	}
+
 	// Cache the result
 	await setResourceRegion(identifierType, profileName, identifier, region);
 	logger.trace(`[region-lookup] Cached region for ${identifier}: ${region}`);

package/src/cmd/cloud/scp/download.ts

@@ -72,7 +72,8 @@ export const downloadCommand = createSubcommand({
 			apiClient,
 			profileName,
 			identifier,
-			orgId
+			orgId,
+			config
 		);
 
 		const hostname = getIONHost(config, region);

package/src/cmd/cloud/scp/upload.ts

@@ -75,7 +75,8 @@ export const uploadCommand = createSubcommand({
 			apiClient,
 			profileName,
 			identifier,
-			orgId
+			orgId,
+			config
 		);
 
 		const hostname = getIONHost(config, region);

package/src/cmd/cloud/ssh.ts

@@ -80,7 +80,8 @@ export const sshSubcommand = createSubcommand({
 			apiClient,
 			profileName,
 			targetIdentifier,
-			orgId
+			orgId,
+			config
 		);
 
 		const hostname = getIONHost(config, region);

package/src/cmd/cloud/storage/create.ts

@@ -29,6 +29,9 @@ export const createSubcommand = defineSubcommand({
 		},
 	],
 	schema: {
+		options: z.object({
+			description: z.string().optional().describe('Optional description for the bucket'),
+		}),
 		response: z.object({
 			success: z.boolean().describe('Whether creation succeeded'),
 			name: z.string().describe('Created storage bucket name'),
@@ -36,7 +39,7 @@ export const createSubcommand = defineSubcommand({
 	},
 
 	async handler(ctx) {
-		const { logger, orgId, region, auth, options } = ctx;
+		const { logger, orgId, region, auth, options, opts } = ctx;
 
 		// Handle dry-run mode
 		if (isDryRunMode(options)) {
@@ -58,7 +61,9 @@ export const createSubcommand = defineSubcommand({
 			message: `Creating storage in ${region}`,
 			clearOnSuccess: true,
 			callback: async () => {
-				return createResources(catalystClient, orgId, region!, [{ type: 's3' }]);
+				return createResources(catalystClient, orgId, region!, [
+					{ type: 's3', description: opts.description },
+				]);
 			},
 		});
 

package/src/cmd/cloud/storage/get.ts

@@ -15,6 +15,9 @@ const StorageGetResponseSchema = z.object({
 	endpoint: z.string().optional().describe('S3 endpoint URL'),
 	org_id: z.string().optional().describe('Organization ID that owns this bucket'),
 	org_name: z.string().optional().describe('Organization name that owns this bucket'),
+	bucket_type: z.string().optional().describe('Bucket type (user or snapshots)'),
+	internal: z.boolean().optional().describe('Whether this is a system-managed bucket'),
+	description: z.string().optional().describe('Optional description of the bucket'),
 });
 
 export const getSubcommand = createSubcommand({
@@ -134,6 +137,9 @@ export const getSubcommand = createSubcommand({
 			endpoint: bucket.endpoint ?? undefined,
 			org_id: bucket.org_id,
 			org_name: bucket.org_name,
+			bucket_type: bucket.bucket_type,
+			internal: bucket.internal,
+			description: bucket.description ?? undefined,
 		};
 	},
 });

package/src/cmd/cloud/storage/list.ts

@@ -20,6 +20,9 @@ const StorageListResponseSchema = z.object({
 				cloud_region: z.string().optional().describe('Cloud region where bucket is hosted'),
 				org_id: z.string().optional().describe('Organization ID that owns this bucket'),
 				org_name: z.string().optional().describe('Organization name that owns this bucket'),
+				bucket_type: z.string().optional().describe('Bucket type (user or snapshots)'),
+				internal: z.boolean().optional().describe('Whether this is a system-managed bucket'),
+				description: z.string().optional().describe('Optional description of the bucket'),
 			})
 		)
 		.optional()
@@ -241,6 +244,9 @@ export const listSubcommand = createSubcommand({
 				cloud_region: s3.cloud_region,
 				org_id: s3.org_id,
 				org_name: s3.org_name,
+				bucket_type: s3.bucket_type,
+				internal: s3.internal,
+				description: s3.description ?? undefined,
 			})),
 		};
 	},

package/src/cmd/project/auth/init.ts

@@ -12,6 +12,7 @@ import {
 	generateAuthSchemaSql,
 	getGeneratedSqlDir,
 } from './shared';
+import { readEnvFile, writeEnvFile } from '../../../env-util';
 import enquirer from 'enquirer';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -96,32 +97,23 @@ export const initSubcommand = createSubcommand({
 
 		const databaseName = dbInfo.name;
 
-		// Update .env with database URL
+		// Update .env with database URL using proper parsing
 		const envPath = path.join(projectDir, '.env');
-		let envContent = '';
-
-		if (fs.existsSync(envPath)) {
-			envContent = fs.readFileSync(envPath, 'utf-8');
-			if (!envContent.endsWith('\n') && envContent.length > 0) {
-				envContent += '\n';
-			}
-		}
+		const existingEnv = await readEnvFile(envPath);
 
 		// Check if DATABASE_URL already exists
-		const hasDatabaseUrl = envContent.match(/^DATABASE_URL=/m);
+		const hasDatabaseUrl = 'DATABASE_URL' in existingEnv;
 
 		if (dbInfo.url !== databaseUrl || !hasDatabaseUrl) {
 			if (hasDatabaseUrl) {
 				// DATABASE_URL exists, use AUTH_DATABASE_URL instead
-				envContent += `AUTH_DATABASE_URL="${dbInfo.url}"\n`;
-				fs.writeFileSync(envPath, envContent);
+				await writeEnvFile(envPath, { AUTH_DATABASE_URL: dbInfo.url });
 				tui.success('AUTH_DATABASE_URL added to .env');
 				tui.warning(
 					`DATABASE_URL already exists. Update your ${tui.bold('src/auth.ts')} to use AUTH_DATABASE_URL.`
 				);
 			} else {
-				envContent += `DATABASE_URL="${dbInfo.url}"\n`;
-				fs.writeFileSync(envPath, envContent);
+				await writeEnvFile(envPath, { DATABASE_URL: dbInfo.url });
 				tui.success('DATABASE_URL added to .env');
 			}
 		} else {
@@ -129,18 +121,14 @@ export const initSubcommand = createSubcommand({
 		}
 
 		// Add AGENTUITY_AUTH_SECRET if not present
-		// Re-read envContent to get latest state
-		envContent = fs.existsSync(envPath) ? fs.readFileSync(envPath, 'utf-8') : '';
-		if (!envContent.endsWith('\n') && envContent.length > 0) {
-			envContent += '\n';
-		}
+		// Re-read env to get latest state
+		const currentEnv = await readEnvFile(envPath);
 
 		const hasAuthSecret =
-			envContent.match(/^AGENTUITY_AUTH_SECRET=/m) || envContent.match(/^BETTER_AUTH_SECRET=/m);
+			'AGENTUITY_AUTH_SECRET' in currentEnv || 'BETTER_AUTH_SECRET' in currentEnv;
 		if (!hasAuthSecret) {
 			const devSecret = `dev-${crypto.randomUUID()}-CHANGE-ME`;
-			envContent += `AGENTUITY_AUTH_SECRET="${devSecret}"\n`;
-			fs.writeFileSync(envPath, envContent);
+			await writeEnvFile(envPath, { AGENTUITY_AUTH_SECRET: devSecret });
 			tui.success('AGENTUITY_AUTH_SECRET added to .env (development default)');
 			tui.warning(
 				`Replace ${tui.bold('AGENTUITY_AUTH_SECRET')} with a secure value before deploying.`

package/src/cmd/upgrade/index.ts

@@ -138,7 +138,7 @@ export const command = createCommand({
 		// Check if we can upgrade based on installation type
 		if (installationType === 'source') {
 			tui.error('Upgrade is not available when running from source.');
-			tui.info('You are running the CLI from source code (development mode).');
+			tui.warning('You are running the CLI from source code (development mode).');
 			tui.info('Use git to update the source code instead.');
 			return {
 				upgraded: false,
@@ -150,10 +150,10 @@ export const command = createCommand({
 
 		if (installationType === 'local') {
 			tui.error('Upgrade is not available for local project installations.');
-			tui.info('The CLI is installed as a project dependency.');
+			tui.warning('The CLI is installed as a project dependency.');
 			tui.newline();
-			tui.info('To upgrade, update your package.json or run:');
-			tui.info(`  ${tui.muted('bun add @agentuity/cli@latest')}`);
+			console.log('To upgrade, update your package.json or run:');
+			console.log(`  ${tui.muted('bun add @agentuity/cli@latest')}`);
 			return {
 				upgraded: false,
 				from: currentVersion,

package/src/config.ts

@@ -809,14 +809,16 @@ export async function getDefaultRegion(
  * @param auth - Authentication data
  * @param profileName - Profile name (default: 'production')
  * @param orgId - Optional organization ID for CLI key authentication
+ * @param config - Optional config for region preference lookup
  */
 export async function getGlobalCatalystAPIClient(
 	logger: Logger,
 	auth: AuthData,
 	profileName = 'production',
-	orgId?: string
+	orgId?: string,
+	config?: Config | null
 ) {
-	const region = await getDefaultRegion(profileName);
+	const region = await getDefaultRegion(profileName, config);
 	return getCatalystAPIClient(logger, auth, region, orgId);
 }
 
@@ -828,6 +830,12 @@ export function getIONHost(config: Config | null, region: string) {
 	if (config?.name === 'local' || region === 'local') {
 		return 'ion.agentuity.io';
 	}
+	// Validate region is a non-empty string to prevent malformed hostnames
+	if (!region || typeof region !== 'string' || region.trim() === '') {
+		throw new Error(
+			`Invalid region: '${region}'. Region must be a non-empty string. Use --region flag to specify a valid region.`
+		);
+	}
 	return `ion-${region}.agentuity.cloud`;
 }
 

package/src/env-util.ts

@@ -149,7 +149,8 @@ export async function readEnvFile(path: string): Promise<EnvVars> {
 
 /**
  * Write environment variables to an .env file
- * Optionally skip certain keys (like AGENTUITY_SDK_KEY)
+ * By default, preserves existing keys that are not in the new vars.
+ * Use preserveExisting: false to completely overwrite the file.
  */
 export async function writeEnvFile(
 	path: string,
@@ -157,20 +158,36 @@ export async function writeEnvFile(
 	options?: {
 		skipKeys?: string[];
 		addComment?: (key: string) => string | null;
+		/**
+		 * When true (default), reads existing file first and merges with new vars.
+		 * New vars take priority for matching keys, but all existing keys are preserved.
+		 * When false, completely overwrites the file with only the provided vars.
+		 */
+		preserveExisting?: boolean;
 	}
 ): Promise<void> {
 	const skipKeys = options?.skipKeys || [];
+	const preserveExisting = options?.preserveExisting ?? true;
+
+	// If preserveExisting is true, read existing file and merge
+	let finalVars = vars;
+	if (preserveExisting) {
+		const existing = await readEnvFile(path);
+		// Merge: existing as base, new vars override
+		finalVars = { ...existing, ...vars };
+	}
+
 	const lines: string[] = [];
 
 	// Sort keys for consistent output
-	const sortedKeys = Object.keys(vars).sort();
+	const sortedKeys = Object.keys(finalVars).sort();
 
 	for (const key of sortedKeys) {
 		if (skipKeys.includes(key)) {
 			continue;
 		}
 
-		const value = vars[key];
+		const value = finalVars[key];
 
 		// Add comment if provided
 		if (options?.addComment) {

package/src/types.ts

@@ -24,7 +24,10 @@ export const ConfigSchema = zod.object({
 	devmode: zod
 		.object({
 			hostname: zod.string().optional().describe('Development mode hostname'),
-			privateKey: zod.string().optional().describe('Development mode private key (base64-encoded PEM)'),
+			privateKey: zod
+				.string()
+				.optional()
+				.describe('Development mode private key (base64-encoded PEM)'),
 		})
 		.optional()
 		.describe('Development mode configuration'),

package/src/utils/installation-type.ts

@@ -2,6 +2,8 @@
  * Detects how the CLI was installed and is being run
  */
 
+import os from 'node:os';
+
 export type InstallationType = 'global' | 'local' | 'source';
 
 /**
@@ -12,10 +14,24 @@ export type InstallationType = 'global' | 'local' | 'source';
  * @returns 'source' - Running from source code (development)
  */
 export function getInstallationType(): InstallationType {
-	// Normalize path to POSIX separators for cross-platform compatibility
+	// Normalize paths to POSIX separators for cross-platform compatibility
 	const mainPath = Bun.main.replace(/\\/g, '/');
+	// Bun.argv[1] contains the original invocation path (before symlink resolution)
+	const invokedPath = (Bun.argv[1] ?? '').replace(/\\/g, '/');
+
+	// Get bun's global bin directory from BUN_INSTALL or default to ~/.bun/bin
+	// Use os.homedir() as primary fallback to avoid "undefined/.bun" paths
+	const home = os.homedir() ?? process.env.HOME ?? process.env.USERPROFILE ?? '';
+	const bunInstall = (process.env.BUN_INSTALL ?? (home ? `${home}/.bun` : '')).replace(/\\/g, '/');
+	const globalBinDir = bunInstall ? `${bunInstall}/bin/` : '';
+
+	// Global install: invoked from bun's global bin directory (e.g., ~/.bun/bin/agentuity)
+	// This handles symlinks created by `bun add -g @agentuity/cli`
+	if (globalBinDir && invokedPath.startsWith(globalBinDir)) {
+		return 'global';
+	}
 
-	// Global install: ~/.bun/install/global/node_modules/@agentuity/cli/...
+	// Also check the resolved path for explicit global install locations
 	if (mainPath.includes('/.bun/install/global/')) {
 		return 'global';
 	}