@agentuity/cli 2.0.0-beta.0 → 2.0.0

package/src/cmd/cloud/sandbox/{mkdir.ts → fs/mkdir.ts}

@@ -1,8 +1,8 @@
 import { z } from 'zod';
-import { createCommand } from '../../../types';
-import * as tui from '../../../tui';
-import { createSandboxClient } from './util';
-import { getCommand } from '../../../command-prefix';
+import { createCommand } from '../../../../types';
+import * as tui from '../../../../tui';
+import { createSandboxClient } from '../util';
+import { getCommand } from '../../../../command-prefix';
 import { sandboxMkDir, sandboxResolve } from '@agentuity/server';
 
 const MkDirResponseSchema = z.object({
@@ -17,11 +17,11 @@ export const mkdirSubcommand = createCommand({
 	requires: { auth: true, apiClient: true },
 	examples: [
 		{
-			command: getCommand('cloud sandbox mkdir sbx_abc123 /path/to/dir'),
+			command: getCommand('cloud sandbox fs mkdir sbx_abc123 /path/to/dir'),
 			description: 'Create a directory in the sandbox',
 		},
 		{
-			command: getCommand('cloud sandbox mkdir sbx_abc123 /path/to/nested/dir -p'),
+			command: getCommand('cloud sandbox fs mkdir sbx_abc123 /path/to/nested/dir -p'),
 			description: 'Create nested directories recursively',
 		},
 	],

package/src/cmd/cloud/sandbox/{rm.ts → fs/rm.ts}

@@ -1,8 +1,8 @@
 import { z } from 'zod';
-import { createCommand } from '../../../types';
-import * as tui from '../../../tui';
-import { createSandboxClient } from './util';
-import { getCommand } from '../../../command-prefix';
+import { createCommand } from '../../../../types';
+import * as tui from '../../../../tui';
+import { createSandboxClient } from '../util';
+import { getCommand } from '../../../../command-prefix';
 import { sandboxRmFile, sandboxResolve } from '@agentuity/server';
 
 const RmFileResponseSchema = z.object({
@@ -12,12 +12,13 @@ const RmFileResponseSchema = z.object({
 
 export const rmSubcommand = createCommand({
 	name: 'rm',
+	aliases: ['del', 'remove'],
 	description: 'Remove a file from a sandbox',
 	tags: ['slow', 'requires-auth'],
 	requires: { auth: true, apiClient: true },
 	examples: [
 		{
-			command: getCommand('cloud sandbox rm sbx_abc123 /path/to/file.txt'),
+			command: getCommand('cloud sandbox fs rm sbx_abc123 /path/to/file.txt'),
 			description: 'Remove a file from the sandbox',
 		},
 	],

package/src/cmd/cloud/sandbox/{rmdir.ts → fs/rmdir.ts}

@@ -1,8 +1,8 @@
 import { z } from 'zod';
-import { createCommand } from '../../../types';
-import * as tui from '../../../tui';
-import { createSandboxClient } from './util';
-import { getCommand } from '../../../command-prefix';
+import { createCommand } from '../../../../types';
+import * as tui from '../../../../tui';
+import { createSandboxClient } from '../util';
+import { getCommand } from '../../../../command-prefix';
 import { sandboxRmDir, sandboxResolve } from '@agentuity/server';
 
 const RmDirResponseSchema = z.object({
@@ -17,11 +17,11 @@ export const rmdirSubcommand = createCommand({
 	requires: { auth: true, apiClient: true },
 	examples: [
 		{
-			command: getCommand('cloud sandbox rmdir sbx_abc123 /path/to/dir'),
+			command: getCommand('cloud sandbox fs rmdir sbx_abc123 /path/to/dir'),
 			description: 'Remove an empty directory from the sandbox',
 		},
 		{
-			command: getCommand('cloud sandbox rmdir sbx_abc123 /path/to/dir -r'),
+			command: getCommand('cloud sandbox fs rmdir sbx_abc123 /path/to/dir -r'),
 			description: 'Remove a directory and all its contents recursively',
 		},
 	],

package/src/cmd/cloud/sandbox/{upload.ts → fs/upload.ts}

@@ -1,9 +1,9 @@
 import { z } from 'zod';
 import { readFileSync, statSync } from 'node:fs';
-import { createCommand } from '../../../types';
-import * as tui from '../../../tui';
-import { createSandboxClient } from './util';
-import { getCommand } from '../../../command-prefix';
+import { createCommand } from '../../../../types';
+import * as tui from '../../../../tui';
+import { createSandboxClient } from '../util';
+import { getCommand } from '../../../../command-prefix';
 import { sandboxUploadArchive, sandboxResolve } from '@agentuity/server';
 
 export const uploadSubcommand = createCommand({
@@ -14,15 +14,15 @@ export const uploadSubcommand = createCommand({
 	requires: { auth: true, apiClient: true },
 	examples: [
 		{
-			command: getCommand('cloud sandbox upload sbx_abc123 ./archive.tar.gz'),
+			command: getCommand('cloud sandbox fs upload sbx_abc123 ./archive.tar.gz'),
 			description: 'Upload and extract a tar.gz archive to sandbox root',
 		},
 		{
-			command: getCommand('cloud sandbox upload sbx_abc123 ./archive.zip --path /subdir'),
+			command: getCommand('cloud sandbox fs upload sbx_abc123 ./archive.zip --path /subdir'),
 			description: 'Upload and extract a zip archive to a specific directory',
 		},
 		{
-			command: getCommand('cloud sandbox upload sbx_abc123 ./archive.bin --format tar.gz'),
+			command: getCommand('cloud sandbox fs upload sbx_abc123 ./archive.bin --format tar.gz'),
 			description: 'Upload with explicit format specification',
 		},
 	],

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

@@ -7,14 +7,9 @@ import { getSubcommand } from './get';
 import { deleteSubcommand } from './delete';
 import { snapshotCommand } from './snapshot';
 import { runtimeCommand } from './runtime';
-import { cpSubcommand } from './cp';
+import { command as fsCommand } from './fs';
 import { command as executionCommand } from './execution';
-import { mkdirSubcommand } from './mkdir';
-import { rmdirSubcommand } from './rmdir';
-import { rmSubcommand } from './rm';
-import { lsSubcommand } from './ls';
-import { downloadSubcommand } from './download';
-import { uploadSubcommand } from './upload';
+import { command as jobCommand } from './job';
 import { envSubcommand } from './env';
 import { pauseSubcommand } from './pause';
 import { resumeSubcommand } from './resume';
@@ -51,14 +46,9 @@ export const command = createCommand({
 		deleteSubcommand,
 		snapshotCommand,
 		runtimeCommand,
-		cpSubcommand,
+		fsCommand,
 		executionCommand,
-		mkdirSubcommand,
-		rmdirSubcommand,
-		rmSubcommand,
-		lsSubcommand,
-		downloadSubcommand,
-		uploadSubcommand,
+		jobCommand,
 		envSubcommand,
 		pauseSubcommand,
 		resumeSubcommand,

package/src/cmd/cloud/sandbox/job/create.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import { createCommand } from '../../../../types';
+import * as tui from '../../../../tui';
+import { createSandboxClient } from '../util';
+import { getCommand } from '../../../../command-prefix';
+import { jobCreate, sandboxResolve } from '@agentuity/server';
+
+export const createSubcommand = createCommand({
+	name: 'create',
+	aliases: ['new'],
+	description: 'Create a background job in a sandbox',
+	tags: ['requires-auth'],
+	requires: { auth: true, apiClient: true },
+	examples: [
+		{
+			command: getCommand('cloud sandbox job create sbx_abc123 -- bun run build'),
+			description: 'Create a background job',
+		},
+		{
+			command: getCommand('cloud sandbox job create sbx_abc123 -- npm install'),
+			description: 'Run npm install as a background job',
+		},
+	],
+
+	schema: {
+		args: z.object({
+			sandboxId: z.string().describe('Sandbox ID'),
+			command: z.array(z.string()).describe('Command and arguments to run as a background job'),
+		}),
+		options: z.object({}),
+	},
+
+	async handler(ctx) {
+		const { args, options, auth, logger, apiClient } = ctx;
+
+		const sandboxInfo = await sandboxResolve(apiClient, args.sandboxId);
+		const { region, orgId } = sandboxInfo;
+
+		const client = createSandboxClient(logger, auth, region);
+
+		const job = await jobCreate(client, {
+			sandboxId: args.sandboxId,
+			options: {
+				command: args.command,
+			},
+			orgId,
+		});
+
+		if (options.json) {
+			return job;
+		}
+
+		tui.success(`Created job ${tui.bold(job.jobId)}`);
+		tui.info(`Status: ${job.status}`);
+		tui.muted(
+			`Use 'agentuity cloud sandbox job get ${args.sandboxId} ${job.jobId}' to check status`
+		);
+
+		return job;
+	},
+});
+
+export default createSubcommand;

package/src/cmd/cloud/sandbox/job/destroy.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+import { createCommand } from '../../../../types';
+import * as tui from '../../../../tui';
+import { createSandboxClient } from '../util';
+import { getCommand } from '../../../../command-prefix';
+import { jobStop, sandboxResolve } from '@agentuity/server';
+
+export const destroySubcommand = createCommand({
+	name: 'destroy',
+	aliases: ['stop', 'terminate'],
+	description: 'Terminate a running job',
+	tags: ['requires-auth'],
+	requires: { auth: true, apiClient: true },
+	examples: [
+		{
+			command: getCommand('cloud sandbox job destroy sbx_abc123 job_xyz789'),
+			description: 'Terminate a job gracefully',
+		},
+		{
+			command: getCommand('cloud sandbox job destroy sbx_abc123 job_xyz789 --force'),
+			description: 'Force kill a job',
+		},
+	],
+
+	schema: {
+		args: z.object({
+			sandboxId: z.string().describe('Sandbox ID'),
+			jobId: z.string().describe('Job ID'),
+		}),
+		options: z.object({
+			force: z
+				.boolean()
+				.default(false)
+				.describe('Force kill the job (SIGKILL instead of SIGTERM)'),
+		}),
+	},
+
+	async handler(ctx) {
+		const { args, opts, options, auth, logger, apiClient } = ctx;
+
+		const sandboxInfo = await sandboxResolve(apiClient, args.sandboxId);
+		const { region, orgId } = sandboxInfo;
+
+		const client = createSandboxClient(logger, auth, region);
+
+		const job = await jobStop(client, {
+			sandboxId: args.sandboxId,
+			jobId: args.jobId,
+			force: opts.force,
+			orgId,
+		});
+
+		if (options.json) {
+			return job;
+		}
+
+		if (job.status === 'cancelled') {
+			tui.success(`Job ${tui.bold(job.jobId)} terminated`);
+		} else {
+			tui.info(`Job ${tui.bold(job.jobId)} status: ${job.status}`);
+		}
+
+		return job;
+	},
+});
+
+export default destroySubcommand;

package/src/cmd/cloud/sandbox/job/get.ts

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+import { createCommand } from '../../../../types';
+import * as tui from '../../../../tui';
+import { createSandboxClient } from '../util';
+import { jobGet, sandboxResolve } from '@agentuity/server';
+
+export const getSubcommand = createCommand({
+	name: 'get',
+	aliases: ['show', 'info'],
+	description: 'Get details of a specific job',
+	tags: ['read-only', 'requires-auth'],
+	requires: { auth: true, apiClient: true },
+
+	schema: {
+		args: z.object({
+			sandboxId: z.string().describe('Sandbox ID'),
+			jobId: z.string().describe('Job ID'),
+		}),
+		options: z.object({}),
+	},
+
+	async handler(ctx) {
+		const { args, options, auth, logger, apiClient } = ctx;
+
+		const sandboxInfo = await sandboxResolve(apiClient, args.sandboxId);
+		const { region, orgId } = sandboxInfo;
+
+		const client = createSandboxClient(logger, auth, region);
+
+		const job = await jobGet(client, {
+			sandboxId: args.sandboxId,
+			jobId: args.jobId,
+			orgId,
+		});
+
+		if (options.json) {
+			return job;
+		}
+
+		const statusText =
+			job.status === 'completed'
+				? tui.colorSuccess(job.status)
+				: job.status === 'failed'
+					? tui.colorError(job.status)
+					: job.status === 'running'
+						? tui.colorWarning(job.status)
+						: tui.colorMuted(job.status);
+
+		tui.info(`Job ${tui.bold(job.jobId)}`);
+		console.log('');
+		console.log(`  Status:     ${statusText}`);
+		console.log(`  Sandbox:    ${job.sandboxId}`);
+		console.log(`  Command:    ${job.command.join(' ')}`);
+
+		if (job.exitCode !== undefined && job.exitCode !== null) {
+			console.log(`  Exit code:  ${job.exitCode}`);
+		}
+		if (job.startedAt) {
+			console.log(`  Started:    ${job.startedAt}`);
+		}
+		if (job.completedAt) {
+			console.log(`  Completed:  ${job.completedAt}`);
+		}
+		if (job.error) {
+			console.log(`  Error:      ${tui.colorError(job.error)}`);
+		}
+		if (job.stdoutStreamUrl) {
+			console.log(`  Stdout:     ${job.stdoutStreamUrl}`);
+		}
+		if (job.stderrStreamUrl) {
+			console.log(`  Stderr:     ${job.stderrStreamUrl}`);
+		}
+
+		return job;
+	},
+});
+
+export default getSubcommand;

package/src/cmd/cloud/sandbox/job/index.ts

@@ -0,0 +1,42 @@
+import { createCommand } from '../../../../types';
+import { getSubcommand } from './get';
+import { listSubcommand } from './list';
+import { createSubcommand } from './create';
+import { destroySubcommand } from './destroy';
+import { logsSubcommand } from './logs';
+import { getCommand } from '../../../../command-prefix';
+
+export const command = createCommand({
+	name: 'job',
+	aliases: ['jobs'],
+	description: 'Manage background jobs in a sandbox',
+	tags: ['requires-auth'],
+	examples: [
+		{
+			command: getCommand('cloud sandbox job create sbx_abc123 -- bun run build'),
+			description: 'Create a background job',
+		},
+		{
+			command: getCommand('cloud sandbox job list sbx_abc123'),
+			description: 'List jobs for a sandbox',
+		},
+		{
+			command: getCommand('cloud sandbox job destroy sbx_abc123 job_xyz789'),
+			description: 'Terminate a running job',
+		},
+		{
+			command: getCommand('cloud sandbox job logs sbx_abc123 job_xyz789'),
+			description: 'View logs from a job',
+		},
+	],
+	subcommands: [
+		createSubcommand,
+		getSubcommand,
+		listSubcommand,
+		destroySubcommand,
+		logsSubcommand,
+	],
+	requires: { auth: true, org: true },
+});
+
+export default command;

package/src/cmd/cloud/sandbox/job/list.ts

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+import { createCommand } from '../../../../types';
+import * as tui from '../../../../tui';
+import { createSandboxClient } from '../util';
+import { jobList, sandboxResolve } from '@agentuity/server';
+
+export const listSubcommand = createCommand({
+	name: 'list',
+	description: 'List jobs for a sandbox',
+	tags: ['read-only', 'requires-auth'],
+	requires: { auth: true, apiClient: true },
+
+	schema: {
+		args: z.object({
+			sandboxId: z.string().describe('Sandbox ID'),
+		}),
+		options: z.object({
+			limit: z.coerce
+				.number()
+				.int()
+				.min(1)
+				.max(100)
+				.default(20)
+				.describe('Maximum number of jobs to list'),
+		}),
+	},
+
+	async handler(ctx) {
+		const { args, opts, options, auth, logger, apiClient } = ctx;
+
+		const sandboxInfo = await sandboxResolve(apiClient, args.sandboxId);
+		const { region, orgId } = sandboxInfo;
+
+		const client = createSandboxClient(logger, auth, region);
+
+		const result = await jobList(client, {
+			sandboxId: args.sandboxId,
+			orgId,
+			limit: opts.limit,
+		});
+
+		if (options.json) {
+			return result;
+		}
+
+		if (result.jobs.length === 0) {
+			tui.info('No jobs found');
+			return result;
+		}
+
+		tui.info(`Jobs for sandbox ${tui.bold(args.sandboxId)}:`);
+		console.log('');
+
+		for (const job of result.jobs) {
+			const statusText =
+				job.status === 'completed'
+					? tui.colorSuccess(job.status)
+					: job.status === 'failed'
+						? tui.colorError(job.status)
+						: job.status === 'running'
+							? tui.colorWarning(job.status)
+							: tui.colorMuted(job.status);
+			console.log(
+				`  ${tui.bold(job.jobId)} ${statusText} ${tui.colorMuted(job.command.join(' '))}`
+			);
+			if (job.exitCode !== undefined && job.exitCode !== null) {
+				console.log(`    Exit code: ${job.exitCode}`);
+			}
+			if (job.startedAt) {
+				console.log(`    Started: ${job.startedAt}`);
+			}
+			if (job.completedAt) {
+				console.log(`    Completed: ${job.completedAt}`);
+			}
+		}
+
+		return result;
+	},
+});
+
+export default listSubcommand;

package/src/cmd/cloud/sandbox/job/logs.ts

@@ -0,0 +1,139 @@
+import { z } from 'zod';
+import { createSubcommand } from '../../../../types';
+import * as tui from '../../../../tui';
+import { createSandboxClient } from '../util';
+import { jobGet, sandboxResolve } from '@agentuity/server';
+import { getCommand } from '../../../../command-prefix';
+import { streamUrlToWritable } from '../../../../utils/stream-url';
+
+const JobLogsResponseSchema = z.object({
+	jobId: z.string(),
+	sandboxId: z.string(),
+	status: z.string(),
+	bytesRead: z.number().optional(),
+});
+
+export const logsSubcommand = createSubcommand({
+	name: 'logs',
+	aliases: ['log'],
+	description: 'Stream logs from a sandbox job',
+	tags: ['read-only', 'slow', 'requires-auth'],
+	requires: { auth: true, apiClient: true },
+	examples: [
+		{
+			command: getCommand('cloud sandbox job logs sbx_abc123 job_xyz789'),
+			description: 'View stdout logs from a job',
+		},
+		{
+			command: getCommand('cloud sandbox job logs sbx_abc123 job_xyz789 --stderr'),
+			description: 'View stderr logs from a job',
+		},
+		{
+			command: getCommand('cloud sandbox job logs sbx_abc123 job_xyz789 --follow'),
+			description: 'Follow logs in real-time',
+		},
+		{
+			command: getCommand('cloud sandbox job logs sbx_abc123 job_xyz789 --grep error'),
+			description: 'Filter logs containing "error"',
+		},
+		{
+			command: getCommand('cloud sandbox job logs sbx_abc123 job_xyz789 --tail 100'),
+			description: 'Show last 100 lines',
+		},
+	],
+	schema: {
+		args: z.object({
+			sandboxId: z.string().describe('Sandbox ID'),
+			jobId: z.string().describe('Job ID'),
+		}),
+		options: z.object({
+			stderr: z.boolean().default(false).describe('Show stderr instead of stdout'),
+			follow: z.boolean().default(false).describe('Follow logs in real-time (for running jobs)'),
+			timestamps: z.boolean().default(true).describe('Show timestamps in output'),
+			grep: z.string().optional().describe('Filter logs by pattern (case-insensitive)'),
+			tail: z.coerce
+				.number()
+				.int()
+				.min(1)
+				.optional()
+				.describe('Number of lines to show from the end'),
+		}),
+		response: JobLogsResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { args, opts, options, auth, logger, apiClient } = ctx;
+
+		const sandboxInfo = await sandboxResolve(apiClient, args.sandboxId);
+		const { region, orgId } = sandboxInfo;
+
+		const client = createSandboxClient(logger, auth, region);
+
+		const job = await jobGet(client, {
+			sandboxId: args.sandboxId,
+			jobId: args.jobId,
+			orgId,
+		});
+
+		const streamUrl = opts.stderr ? job.stderrStreamUrl : job.stdoutStreamUrl;
+		const isJson = options.json ?? false;
+
+		if (!streamUrl) {
+			if (isJson) {
+				return {
+					jobId: job.jobId,
+					sandboxId: job.sandboxId,
+					status: job.status,
+				};
+			}
+			tui.warning(
+				`No ${opts.stderr ? 'stderr' : 'stdout'} stream available for job ${job.jobId}`
+			);
+			if (job.status === 'pending') {
+				tui.info('Job is still pending - logs will be available once it starts running');
+			}
+			return {
+				jobId: job.jobId,
+				sandboxId: job.sandboxId,
+				status: job.status,
+			};
+		}
+
+		if (!isJson) {
+			tui.info(
+				`Streaming ${opts.stderr ? 'stderr' : 'stdout'} for job ${tui.bold(job.jobId)} (status: ${job.status})`
+			);
+		}
+
+		const abortController = new AbortController();
+		const handleSignal = () => {
+			abortController.abort();
+		};
+		process.on('SIGINT', handleSignal);
+		process.on('SIGTERM', handleSignal);
+
+		try {
+			const result = await streamUrlToWritable(streamUrl, process.stdout, logger, {
+				signal: abortController.signal,
+				follow: opts.follow,
+				timestamps: opts.timestamps ?? true,
+				grep: opts.grep,
+				tail: opts.tail,
+				json: isJson,
+				label: opts.stderr ? 'stderr' : 'stdout',
+			});
+
+			return {
+				jobId: job.jobId,
+				sandboxId: job.sandboxId,
+				status: job.status,
+				bytesRead: result.bytesRead,
+			};
+		} finally {
+			process.off('SIGINT', handleSignal);
+			process.off('SIGTERM', handleSignal);
+		}
+	},
+});
+
+export default logsSubcommand;

package/src/cmd/cloud/sandbox/run.ts

@@ -65,6 +65,12 @@ export const runSubcommand = createCommand({
 				.optional()
 				.describe('Apt packages to install (can be specified multiple times)'),
 			projectId: z.string().optional().describe('Project ID to associate this sandbox with'),
+			scope: z
+				.array(z.string())
+				.optional()
+				.describe(
+					'Permission scopes for service access (e.g., kv:read, aigateway, services:write)'
+				),
 		}),
 		response: SandboxRunResponseSchema,
 	},
@@ -177,6 +183,7 @@ export const runSubcommand = createCommand({
 					stream: opts.timestamps !== undefined ? { timestamps: opts.timestamps } : undefined,
 					snapshot: opts.snapshot,
 					dependencies: opts.dependency,
+					scopes: opts.scope,
 				},
 				orgId,
 				region,
@@ -194,10 +201,17 @@ export const runSubcommand = createCommand({
 			const duration = Date.now() - started;
 			const output = outputChunks.join('');
 
-			if (!options.json) {
-				if (result.exitCode !== 0) {
+			if (result.exitCode !== 0) {
+				if (!options.json) {
 					tui.error(`failed with exit code ${result.exitCode} in ${duration}ms`);
 				}
+				// Use process.exit() directly rather than process.exitCode to ensure
+				// the exit code propagates reliably across all runtimes (Bun/Node).
+				// process.exitCode can be overwritten by later async cleanup.
+				if (!options.json) {
+					process.exit(result.exitCode);
+				}
+				process.exitCode = result.exitCode;
 			}
 
 			return {

package/src/cmd/cloud/sandbox/runtime/index.ts

@@ -4,7 +4,7 @@ import { getCommand } from '../../../../command-prefix';
 
 export const runtimeCommand = createCommand({
 	name: 'runtime',
-	aliases: ['rt'],
+	aliases: ['rt', 'runtimes'],
 	description: 'Manage sandbox runtimes',
 	tags: ['slow', 'requires-auth'],
 	examples: [