@agentuity/cli 0.1.15 → 0.1.17

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

@@ -1,55 +1,97 @@
 import { z } from 'zod';
 import { createSubcommand } from '../../../types';
 import * as tui from '../../../tui';
-import { projectGet } from '@agentuity/server';
+import { projectGet, orgEnvGet } from '@agentuity/server';
 import { getCommand } from '../../../command-prefix';
 import { ErrorCode } from '../../../errors';
+import { resolveOrgId, isOrgScope } from './org-util';
 
 const EnvGetResponseSchema = z.object({
 	key: z.string().describe('Environment variable key name'),
 	value: z.string().describe('Environment variable value'),
 	secret: z.boolean().describe('Whether the value is stored as a secret'),
+	scope: z.enum(['project', 'org']).describe('The scope where the variable was found'),
 });
 
 export const getSubcommand = createSubcommand({
 	name: 'get',
 	description: 'Get an environment variable or secret value',
-	tags: ['read-only', 'fast', 'requires-auth', 'requires-project'],
+	tags: ['read-only', 'fast', 'requires-auth'],
 	examples: [
 		{ command: getCommand('env get NODE_ENV'), description: 'Get environment variable' },
 		{ command: getCommand('env get API_KEY'), description: 'Get a secret value' },
 		{ command: getCommand('env get API_KEY --no-mask'), description: 'Show unmasked value' },
+		{
+			command: getCommand('env get OPENAI_API_KEY --org'),
+			description: 'Get org-level variable',
+		},
 	],
-	requires: { auth: true, project: true, apiClient: true },
+	requires: { auth: true, apiClient: true },
+	optional: { project: true },
 	schema: {
 		args: z.object({
 			key: z.string().describe('the environment variable or secret key'),
 		}),
 		options: z.object({
 			maskSecret: z.boolean().optional().describe('mask the secret value in output'),
+			org: z
+				.union([z.boolean(), z.string()])
+				.optional()
+				.describe(
+					'get from organization level (use --org for default org, or --org <orgId> for specific org)'
+				),
 		}),
 		response: EnvGetResponseSchema,
 	},
 	idempotent: true,
 
 	async handler(ctx) {
-		const { args, opts, apiClient, project, options } = ctx;
+		const { args, opts, apiClient, project, options, config } = ctx;
+		const useOrgScope = isOrgScope(opts?.org);
 
-		// Fetch project with unmasked values
-		const projectData = await tui.spinner('Fetching variable', () => {
-			return projectGet(apiClient, { id: project.projectId, mask: false });
-		});
+		// Require project context if not using org scope
+		if (!useOrgScope && !project) {
+			tui.fatal(
+				'Project context required. Run from a project directory or use --org for organization scope.'
+			);
+		}
 
-		// Look for the key in both env and secrets
 		let value: string | undefined;
 		let isSecret = false;
+		let scope: 'project' | 'org';
+
+		if (useOrgScope) {
+			// Organization scope
+			const orgId = await resolveOrgId(apiClient, config, opts!.org!);
+
+			const orgData = await tui.spinner('Fetching organization variable', () => {
+				return orgEnvGet(apiClient, { id: orgId, mask: false });
+			});
+
+			if (orgData.secrets?.[args.key] !== undefined) {
+				value = orgData.secrets[args.key];
+				isSecret = true;
+			} else if (orgData.env?.[args.key] !== undefined) {
+				value = orgData.env[args.key];
+				isSecret = false;
+			}
+
+			scope = 'org';
+		} else {
+			// Project scope
+			const projectData = await tui.spinner('Fetching variable', () => {
+				return projectGet(apiClient, { id: project!.projectId, mask: false });
+			});
+
+			if (projectData.secrets?.[args.key] !== undefined) {
+				value = projectData.secrets[args.key];
+				isSecret = true;
+			} else if (projectData.env?.[args.key] !== undefined) {
+				value = projectData.env[args.key];
+				isSecret = false;
+			}
 
-		if (projectData.secrets?.[args.key] !== undefined) {
-			value = projectData.secrets[args.key];
-			isSecret = true;
-		} else if (projectData.env?.[args.key] !== undefined) {
-			value = projectData.env[args.key];
-			isSecret = false;
+			scope = 'project';
 		}
 
 		if (value === undefined) {
@@ -62,13 +104,15 @@ export const getSubcommand = createSubcommand({
 		if (!options.json) {
 			const displayValue = shouldMask ? tui.maskSecret(value) : value;
 			const typeLabel = isSecret ? ' (secret)' : '';
-			tui.success(`${args.key}=${displayValue}${typeLabel}`);
+			const scopeLabel = useOrgScope ? ' [org]' : '';
+			tui.success(`${args.key}=${displayValue}${typeLabel}${scopeLabel}`);
 		}
 
 		return {
 			key: args.key,
 			value,
 			secret: isSecret,
+			scope,
 		};
 	},
 });

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

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { createSubcommand } from '../../../types';
 import * as tui from '../../../tui';
-import { projectEnvUpdate } from '@agentuity/server';
+import { projectEnvUpdate, orgEnvUpdate } from '@agentuity/server';
 import {
 	findExistingEnvFile,
 	readEnvFile,
@@ -13,6 +13,7 @@ import {
 	isReservedAgentuityKey,
 } from '../../../env-util';
 import { getCommand } from '../../../command-prefix';
+import { resolveOrgId, isOrgScope } from './org-util';
 
 const EnvImportResponseSchema = z.object({
 	success: z.boolean().describe('Whether import succeeded'),
@@ -20,21 +21,18 @@ const EnvImportResponseSchema = z.object({
 	envCount: z.number().describe('Number of env vars imported'),
 	secretCount: z.number().describe('Number of secrets imported'),
 	skipped: z.number().describe('Number of items skipped'),
-	path: z.string().describe('Local file path where variables were saved'),
+	path: z
+		.string()
+		.optional()
+		.describe('Local file path where variables were saved (project scope only)'),
 	file: z.string().describe('Source file path'),
+	scope: z.enum(['project', 'org']).describe('The scope where variables were imported'),
 });
 
 export const importSubcommand = createSubcommand({
 	name: 'import',
 	description: 'Import environment variables and secrets from a file to cloud and local .env',
-	tags: [
-		'mutating',
-		'creates-resource',
-		'slow',
-		'api-intensive',
-		'requires-auth',
-		'requires-project',
-	],
+	tags: ['mutating', 'creates-resource', 'slow', 'api-intensive', 'requires-auth'],
 	examples: [
 		{
 			command: getCommand('cloud env import .env.backup'),
@@ -44,18 +42,37 @@ export const importSubcommand = createSubcommand({
 			command: getCommand('cloud env import .env.local'),
 			description: 'Import from .env.local file',
 		},
+		{
+			command: getCommand('cloud env import .env.shared --org'),
+			description: 'Import to organization level',
+		},
 	],
 	idempotent: false,
-	requires: { auth: true, project: true, apiClient: true },
+	requires: { auth: true, apiClient: true },
+	optional: { project: true },
 	schema: {
 		args: z.object({
 			file: z.string().describe('path to the .env file to import'),
 		}),
+		options: z.object({
+			org: z
+				.union([z.boolean(), z.string()])
+				.optional()
+				.describe('import to organization level (use --org for default org)'),
+		}),
 		response: EnvImportResponseSchema,
 	},
 
 	async handler(ctx) {
-		const { args, apiClient, project, projectDir } = ctx;
+		const { args, apiClient, project, projectDir, config, opts } = ctx;
+		const useOrgScope = isOrgScope(opts?.org);
+
+		// Require project context if not using org scope
+		if (!useOrgScope && !project) {
+			tui.fatal(
+				'Project context required. Run from a project directory or use --org for organization scope.'
+			);
+		}
 
 		// Read the import file
 		const importedVars = await readEnvFile(args.file);
@@ -68,8 +85,8 @@ export const importSubcommand = createSubcommand({
 				envCount: 0,
 				secretCount: 0,
 				skipped: 0,
-				path: '',
 				file: args.file,
+				scope: useOrgScope ? ('org' as const) : ('project' as const),
 			};
 		}
 
@@ -84,8 +101,8 @@ export const importSubcommand = createSubcommand({
 				envCount: 0,
 				secretCount: 0,
 				skipped: Object.keys(importedVars).length,
-				path: '',
 				file: args.file,
+				scope: useOrgScope ? ('org' as const) : ('project' as const),
 			};
 		}
 
@@ -104,40 +121,71 @@ export const importSubcommand = createSubcommand({
 			}
 		}
 
-		// Push to cloud
-		await tui.spinner('Importing variables to cloud', () => {
-			return projectEnvUpdate(apiClient, {
-				id: project.projectId,
-				env,
-				secrets,
+		const envCount = Object.keys(env).length;
+		const secretCount = Object.keys(secrets).length;
+		const totalCount = envCount + secretCount;
+
+		if (useOrgScope) {
+			// Organization scope
+			const orgId = await resolveOrgId(apiClient, config, opts!.org!);
+
+			await tui.spinner('Importing variables to organization', () => {
+				return orgEnvUpdate(apiClient, {
+					id: orgId,
+					env,
+					secrets,
+				});
+			});
+
+			tui.success(
+				`Imported ${totalCount} variable${totalCount !== 1 ? 's' : ''} to organization from ${args.file} (${envCount} env, ${secretCount} secret${secretCount !== 1 ? 's' : ''})`
+			);
+
+			return {
+				success: true,
+				imported: totalCount,
+				envCount,
+				secretCount,
+				skipped: Object.keys(importedVars).length - totalCount,
+				file: args.file,
+				scope: 'org' as const,
+			};
+		} else {
+			// Project scope (existing behavior)
+			await tui.spinner('Importing variables to cloud', () => {
+				return projectEnvUpdate(apiClient, {
+					id: project!.projectId,
+					env,
+					secrets,
+				});
 			});
-		});
 
-		// Merge with local .env file
-		const localEnvPath = await findExistingEnvFile(projectDir);
-		const localEnv = await readEnvFile(localEnvPath);
-		const mergedEnv = mergeEnvVars(localEnv, filteredVars);
+			// Merge with local .env file only if we have a project directory
+			let localEnvPath: string | undefined;
+			if (projectDir) {
+				localEnvPath = await findExistingEnvFile(projectDir);
+				const localEnv = await readEnvFile(localEnvPath);
+				const mergedEnv = mergeEnvVars(localEnv, filteredVars);
 
-		await writeEnvFile(localEnvPath, mergedEnv, {
-			skipKeys: Object.keys(mergedEnv).filter(isReservedAgentuityKey),
-		});
+				await writeEnvFile(localEnvPath, mergedEnv, {
+					skipKeys: Object.keys(mergedEnv).filter(isReservedAgentuityKey),
+				});
+			}
 
-		const envCount = Object.keys(env).length;
-		const secretCount = Object.keys(secrets).length;
-		const totalCount = envCount + secretCount;
+			tui.success(
+				`Imported ${totalCount} variable${totalCount !== 1 ? 's' : ''} from ${args.file} (${envCount} env, ${secretCount} secret${secretCount !== 1 ? 's' : ''})`
+			);
 
-		tui.success(
-			`Imported ${totalCount} variable${totalCount !== 1 ? 's' : ''} from ${args.file} (${envCount} env, ${secretCount} secret${secretCount !== 1 ? 's' : ''})`
-		);
-
-		return {
-			success: true,
-			imported: totalCount,
-			envCount,
-			secretCount,
-			skipped: Object.keys(importedVars).length - totalCount,
-			path: localEnvPath,
-			file: args.file,
-		};
+			return {
+				success: true,
+				imported: totalCount,
+				envCount,
+				secretCount,
+				skipped: Object.keys(importedVars).length - totalCount,
+				path: localEnvPath,
+				file: args.file,
+				scope: 'project' as const,
+			};
+		}
 	},
 });

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

@@ -10,8 +10,8 @@ import { getCommand } from '../../../command-prefix';
 
 export const command = createCommand({
 	name: 'env',
-	description: 'Manage environment variables and secrets for your project',
-	tags: ['fast', 'requires-auth', 'requires-project'],
+	description: 'Manage environment variables and secrets for your project or organization',
+	tags: ['fast', 'requires-auth'],
 	examples: [
 		{ command: getCommand('cloud env list'), description: 'List all variables and secrets' },
 		{
@@ -22,6 +22,10 @@ export const command = createCommand({
 			command: getCommand('cloud env set API_KEY "sk_..." --secret'),
 			description: 'Set a secret',
 		},
+		{
+			command: getCommand('cloud env set OPENAI_API_KEY "sk_..." --secret --org'),
+			description: 'Set an organization-wide secret',
+		},
 	],
 	subcommands: [
 		listSubcommand,

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

@@ -1,12 +1,14 @@
 import { z } from 'zod';
 import { createSubcommand } from '../../../types';
 import * as tui from '../../../tui';
-import { projectGet } from '@agentuity/server';
+import { projectGet, orgEnvGet } from '@agentuity/server';
 import { getCommand } from '../../../command-prefix';
+import { resolveOrgId, isOrgScope } from './org-util';
 
 const EnvItemSchema = z.object({
 	value: z.string().describe('Variable value'),
 	secret: z.boolean().describe('Whether this is a secret'),
+	scope: z.enum(['project', 'org']).describe('The scope of the variable'),
 });
 
 const EnvListResponseSchema = z.record(z.string(), EnvItemSchema);
@@ -15,14 +17,19 @@ export const listSubcommand = createSubcommand({
 	name: 'list',
 	aliases: ['ls'],
 	description: 'List all environment variables and secrets',
-	tags: ['read-only', 'fast', 'requires-auth', 'requires-project'],
+	tags: ['read-only', 'fast', 'requires-auth'],
 	examples: [
-		{ command: getCommand('env list'), description: 'List all variables' },
+		{ command: getCommand('env list'), description: 'List all variables (project + org merged)' },
 		{ command: getCommand('env list --no-mask'), description: 'Show unmasked values' },
 		{ command: getCommand('env list --secrets'), description: 'List only secrets' },
 		{ command: getCommand('env list --env-only'), description: 'List only env vars' },
+		{
+			command: getCommand('env list --org'),
+			description: 'List only organization-level variables',
+		},
 	],
-	requires: { auth: true, project: true, apiClient: true },
+	requires: { auth: true, apiClient: true },
+	optional: { project: true },
 	idempotent: true,
 	schema: {
 		options: z.object({
@@ -32,39 +39,108 @@ export const listSubcommand = createSubcommand({
 				.describe('mask secret values in output (use --no-mask to show values)'),
 			secrets: z.boolean().default(false).describe('list only secrets'),
 			'env-only': z.boolean().default(false).describe('list only environment variables'),
+			org: z
+				.union([z.boolean(), z.string()])
+				.optional()
+				.describe('list organization-level variables only (use --org for default org)'),
 		}),
 		response: EnvListResponseSchema,
 	},
-	webUrl: (ctx) => `/projects/${encodeURIComponent(ctx.project.projectId)}/settings`,
+	webUrl: (ctx) => {
+		// If --org flag is used, link to org settings; otherwise link to project settings
+		if (ctx.opts?.org) {
+			return `/settings/organization/env`;
+		}
+		return ctx.project
+			? `/projects/${encodeURIComponent(ctx.project.projectId)}/settings`
+			: undefined;
+	},
 
 	async handler(ctx) {
-		const { opts, apiClient, project, options } = ctx;
-
-		// Fetch project with unmasked values
-		const projectData = await tui.spinner('Fetching variables', () => {
-			return projectGet(apiClient, { id: project.projectId, mask: false });
-		});
+		const { opts, apiClient, project, options, config } = ctx;
+		const useOrgScope = isOrgScope(opts?.org);
 
-		const env = projectData.env || {};
-		const secrets = projectData.secrets || {};
-
-		// Build combined result with type info
-		const result: Record<string, { value: string; secret: boolean }> = {};
+		// Build combined result with type info and scope
+		const result: Record<string, { value: string; secret: boolean; scope: 'project' | 'org' }> =
+			{};
 
 		// Filter based on options
 		const showEnv = !opts?.secrets;
 		const showSecrets = !opts?.['env-only'];
 
-		if (showEnv) {
-			for (const [key, value] of Object.entries(env)) {
-				result[key] = { value, secret: false };
+		if (useOrgScope) {
+			// Organization scope only
+			const orgId = await resolveOrgId(apiClient, config, opts!.org!);
+
+			const orgData = await tui.spinner('Fetching organization variables', () => {
+				return orgEnvGet(apiClient, { id: orgId, mask: false });
+			});
+
+			const orgEnv = orgData.env || {};
+			const orgSecrets = orgData.secrets || {};
+
+			if (showEnv) {
+				for (const [key, value] of Object.entries(orgEnv)) {
+					result[key] = { value, secret: false, scope: 'org' };
+				}
+			}
+
+			if (showSecrets) {
+				for (const [key, value] of Object.entries(orgSecrets)) {
+					result[key] = { value, secret: true, scope: 'org' };
+				}
+			}
+		} else if (project) {
+			// Project context: show merged view (org + project, project takes precedence)
+			// First, get project's org ID and fetch org env
+			const projectData = await tui.spinner('Fetching variables', () => {
+				return projectGet(apiClient, { id: project.projectId, mask: false });
+			});
+
+			const projectEnv = projectData.env || {};
+			const projectSecrets = projectData.secrets || {};
+
+			// Try to get org-level env (may fail if no access, that's ok)
+			let orgEnv: Record<string, string> = {};
+			let orgSecrets: Record<string, string> = {};
+
+			if (projectData.orgId) {
+				try {
+					const orgData = await orgEnvGet(apiClient, { id: projectData.orgId, mask: false });
+					orgEnv = orgData.env || {};
+					orgSecrets = orgData.secrets || {};
+				} catch {
+					// Ignore errors - user may not have org env access
+				}
+			}
+
+			// Add org-level first (will be overridden by project-level)
+			if (showEnv) {
+				for (const [key, value] of Object.entries(orgEnv)) {
+					result[key] = { value, secret: false, scope: 'org' };
+				}
+			}
+			if (showSecrets) {
+				for (const [key, value] of Object.entries(orgSecrets)) {
+					result[key] = { value, secret: true, scope: 'org' };
+				}
 			}
-		}
 
-		if (showSecrets) {
-			for (const [key, value] of Object.entries(secrets)) {
-				result[key] = { value, secret: true };
+			// Add project-level (overrides org-level)
+			if (showEnv) {
+				for (const [key, value] of Object.entries(projectEnv)) {
+					result[key] = { value, secret: false, scope: 'project' };
+				}
+			}
+			if (showSecrets) {
+				for (const [key, value] of Object.entries(projectSecrets)) {
+					result[key] = { value, secret: true, scope: 'project' };
+				}
 			}
+		} else {
+			tui.fatal(
+				'Project context required. Run from a project directory or use --org for organization scope.'
+			);
 		}
 
 		// Skip TUI output in JSON mode
@@ -74,11 +150,17 @@ export const listSubcommand = createSubcommand({
 			} else {
 				tui.newline();
 
-				const envCount = showEnv ? Object.keys(env).length : 0;
-				const secretCount = showSecrets ? Object.keys(secrets).length : 0;
+				const projectCount = Object.values(result).filter((v) => v.scope === 'project').length;
+				const orgCount = Object.values(result).filter((v) => v.scope === 'org').length;
+				const secretCount = Object.values(result).filter((v) => v.secret).length;
+				const envCount = Object.values(result).filter((v) => !v.secret).length;
+
 				const parts: string[] = [];
 				if (envCount > 0) parts.push(`${envCount} env`);
 				if (secretCount > 0) parts.push(`${secretCount} secret${secretCount !== 1 ? 's' : ''}`);
+				if (!useOrgScope && projectCount > 0 && orgCount > 0) {
+					parts.push(`${projectCount} project, ${orgCount} org`);
+				}
 
 				tui.info(`Variables (${parts.join(', ')}):`);
 				tui.newline();
@@ -87,10 +169,13 @@ export const listSubcommand = createSubcommand({
 				const shouldMask = opts?.mask !== false;
 
 				for (const key of sortedKeys) {
-					const { value, secret } = result[key];
+					const { value, secret, scope } = result[key];
 					const displayValue = shouldMask && secret ? tui.maskSecret(value) : value;
 					const typeIndicator = secret ? ' [secret]' : '';
-					console.log(`${tui.bold(key)}=${displayValue}${tui.muted(typeIndicator)}`);
+					const scopeIndicator = !useOrgScope ? ` [${scope}]` : '';
+					console.log(
+						`${tui.bold(key)}=${displayValue}${tui.muted(typeIndicator + scopeIndicator)}`
+					);
 				}
 			}
 		}

package/src/cmd/cloud/env/org-util.ts

@@ -0,0 +1,37 @@
+import type { APIClient } from '../../../api';
+import type { Config } from '../../../types';
+import * as tui from '../../../tui';
+import { listOrganizations } from '@agentuity/server';
+
+/**
+ * Resolves the organization ID for org-scoped env operations.
+ *
+ * @param apiClient - The API client
+ * @param config - The CLI config (may be null)
+ * @param orgOption - The --org option value (true for default/prompt, or explicit org ID)
+ * @returns The resolved organization ID
+ */
+export async function resolveOrgId(
+	apiClient: APIClient,
+	config: Config | null,
+	orgOption: boolean | string
+): Promise<string> {
+	// If an explicit org ID was provided (string), use it directly
+	if (typeof orgOption === 'string' && orgOption !== 'true') {
+		return orgOption;
+	}
+
+	// Otherwise, we need to select an org
+	const orgs = await tui.spinner('Fetching organizations', () => listOrganizations(apiClient));
+
+	// Use preference if available, otherwise prompt
+	const preferredOrgId = config?.preferences?.orgId;
+	return tui.selectOrganization(orgs, preferredOrgId);
+}
+
+/**
+ * Checks if we're operating in org scope based on the --org option.
+ */
+export function isOrgScope(orgOption: boolean | string | undefined): boolean {
+	return orgOption === true || (typeof orgOption === 'string' && orgOption.length > 0);
+}