@agentuity/cli 0.1.10 → 0.1.12

package/src/cmd/cloud/sandbox/snapshot/generate.ts

@@ -0,0 +1,136 @@
+import { z } from 'zod';
+import { createCommand } from '../../../../types';
+import { getCommand } from '../../../../command-prefix';
+
+const TEMPLATE_YAML = `# yaml-language-server: $schema=https://agentuity.dev/schema/cli/v1/agentuity-snapshot.json
+#
+# Agentuity Snapshot Build File
+# =============================
+# This file defines a reproducible sandbox environment.
+# Build with: agentuity cloud sandbox snapshot build <directory>
+#
+# For documentation, see: https://agentuity.dev/Services/Sandbox
+
+# Required: Schema version (must be 1)
+version: 1
+
+# Required: Runtime environment
+# Format: name:tag (e.g., bun:1, node:20, python:3.12)
+# Run 'agentuity cloud sandbox runtime list' to see available runtimes
+runtime: bun:1
+
+# Optional: Snapshot name (alphanumeric, underscores, dashes only)
+# If not provided, a unique name will be auto-generated
+# name: my-snapshot
+
+# Optional: Human-readable description
+# Can be overridden with --description flag
+description: My sandbox snapshot
+
+# Optional: Apt packages to install
+# Packages are validated against Debian stable repositories
+# Supports version pinning: package=version or package=version* (prefix match)
+# dependencies:
+#   - curl
+#   - ffmpeg
+#   - imagemagick=8:6.9*
+
+# Optional: Files to include from the build context directory
+# Supports glob patterns and negative patterns (prefix with !)
+# Files are placed in /home/agentuity/ in the sandbox
+# files:
+#   - "*.js"              # All JS files in root
+#   - src/**              # All files in src/ recursively
+#   - config/*.json       # All JSON files in config/
+#   - "!**/*.test.js"     # Exclude test files
+#   - "!node_modules/**"  # Exclude node_modules
+
+# Optional: Environment variables
+# Use \${VAR} syntax for build-time substitution via --env flag
+# env:
+#   NODE_ENV: production
+#   API_URL: https://api.example.com
+#   SECRET_KEY: \${SECRET_KEY}  # Substituted from: --env SECRET_KEY=value
+
+# Optional: Custom metadata
+# Use \${VAR} syntax for build-time substitution via --metadata flag
+# Stored with the snapshot for reference
+# metadata:
+#   version: \${VERSION}   # Substituted from: --metadata VERSION=1.0.0
+#   author: team-name
+#   build_date: \${BUILD_DATE}
+`;
+
+const TEMPLATE_JSON = {
+	$schema: 'https://agentuity.dev/schema/cli/v1/agentuity-snapshot.json',
+	version: 1,
+	runtime: 'bun:1',
+	name: 'my-snapshot',
+	description: 'My sandbox snapshot',
+	dependencies: ['curl'],
+	files: ['src/**', '*.js', '!**/*.test.js'],
+	env: {
+		NODE_ENV: 'production',
+	},
+	metadata: {
+		version: '1.0.0',
+	},
+};
+
+const GenerateResponseSchema = z.object({
+	format: z.enum(['yaml', 'json']).describe('Output format'),
+	content: z.string().describe('Generated template content'),
+});
+
+export const generateSubcommand = createCommand({
+	name: 'generate',
+	aliases: ['gen', 'init'],
+	description: 'Generate a template snapshot build file',
+	tags: [],
+	requires: {},
+	skipUpgradeCheck: true,
+	skipSkill: true,
+	examples: [
+		{
+			command: getCommand('cloud sandbox snapshot generate'),
+			description: 'Generate a YAML template (default)',
+		},
+		{
+			command: getCommand('cloud sandbox snapshot generate --format json'),
+			description: 'Generate a JSON template',
+		},
+		{
+			command: getCommand('cloud sandbox snapshot generate > agentuity-snapshot.yaml'),
+			description: 'Save template to a file',
+		},
+	],
+	schema: {
+		options: z.object({
+			format: z.enum(['yaml', 'json']).default('yaml').describe('Output format (yaml or json)'),
+		}),
+		response: GenerateResponseSchema,
+	},
+
+	async handler(ctx) {
+		const { opts, options } = ctx;
+		const format = opts.format;
+
+		let content: string;
+		if (format === 'json') {
+			content = JSON.stringify(TEMPLATE_JSON, null, 2);
+		} else {
+			content = TEMPLATE_YAML;
+		}
+
+		if (!options.json) {
+			console.log(content);
+		}
+
+		return {
+			format,
+			content,
+		};
+	},
+});
+
+export default generateSubcommand;

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

@@ -21,6 +21,7 @@ const SandboxInfoSchema = z.object({
 
 const SnapshotGetResponseSchema = z.object({
 	snapshotId: z.string().describe('Snapshot ID'),
+	name: z.string().describe('Snapshot name'),
 	tag: z.string().nullable().optional().describe('Snapshot tag'),
 	sizeBytes: z.number().describe('Snapshot size in bytes'),
 	fileCount: z.number().describe('Number of files'),
@@ -28,6 +29,11 @@ const SnapshotGetResponseSchema = z.object({
 	createdAt: z.string().describe('Creation timestamp'),
 	downloadUrl: z.string().optional().describe('Presigned download URL'),
 	files: z.array(SnapshotFileSchema).nullable().optional().describe('Files in snapshot'),
+	userMetadata: z
+		.record(z.string(), z.string())
+		.nullable()
+		.optional()
+		.describe('User-defined metadata'),
 	sandboxes: z
 		.array(SandboxInfoSchema)
 		.optional()
@@ -72,15 +78,32 @@ export const getSubcommand = createCommand({
 		);
 
 		if (!options.json) {
-			tui.info(`Snapshot: ${tui.bold(snapshot.snapshotId)}`);
+			const tableData: Record<string, string | number> = {
+				Snapshot: tui.bold(snapshot.snapshotId),
+				Name: snapshot.name,
+			};
 			if (snapshot.tag) {
-				console.log(`  ${tui.muted('Tag:')}     ${snapshot.tag}`);
+				tableData['Tag'] = snapshot.tag;
 			}
-			console.log(`  ${tui.muted('Size:')}    ${tui.formatBytes(snapshot.sizeBytes)}`);
-			console.log(`  ${tui.muted('Files:')}   ${snapshot.fileCount}`);
-			console.log(`  ${tui.muted('Created:')} ${snapshot.createdAt}`);
+			tableData['Size'] = tui.formatBytes(snapshot.sizeBytes);
+			tableData['Files'] = snapshot.fileCount;
+			tableData['Created'] = snapshot.createdAt;
 			if (snapshot.parentSnapshotId) {
-				console.log(`  ${tui.muted('Parent:')}  ${snapshot.parentSnapshotId}`);
+				tableData['Parent'] = snapshot.parentSnapshotId;
+			}
+
+			tui.table([tableData], Object.keys(tableData), { layout: 'vertical', padStart: '  ' });
+
+			if (
+				snapshot.userMetadata &&
+				typeof snapshot.userMetadata === 'object' &&
+				Object.keys(snapshot.userMetadata).length > 0
+			) {
+				console.log('');
+				tui.info('Metadata:');
+				for (const [key, value] of Object.entries(snapshot.userMetadata)) {
+					console.log(`  ${tui.muted('•')} ${key}=${value}`);
+				}
 			}
 
 			if (snapshot.files && snapshot.files.length > 0) {

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

@@ -4,6 +4,8 @@ import { listSubcommand } from './list';
 import { getSubcommand } from './get';
 import { deleteSubcommand } from './delete';
 import { tagSubcommand } from './tag';
+import { buildSubcommand } from './build';
+import { generateSubcommand } from './generate';
 import { getCommand } from '../../../../command-prefix';
 
 export const snapshotCommand = createCommand({
@@ -20,8 +22,24 @@ export const snapshotCommand = createCommand({
 			command: getCommand('cloud sandbox snapshot list'),
 			description: 'List all snapshots',
 		},
+		{
+			command: getCommand('cloud sandbox snapshot build .'),
+			description: 'Build a snapshot from a declarative file',
+		},
+		{
+			command: getCommand('cloud sandbox snapshot generate > agentuity-snapshot.yaml'),
+			description: 'Generate a template build file',
+		},
+	],
+	subcommands: [
+		createSubcommand,
+		listSubcommand,
+		getSubcommand,
+		deleteSubcommand,
+		tagSubcommand,
+		buildSubcommand,
+		generateSubcommand,
 	],
-	subcommands: [createSubcommand, listSubcommand, getSubcommand, deleteSubcommand, tagSubcommand],
 	requires: { auth: true, org: true },
 });
 

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

@@ -67,7 +67,7 @@ const SessionGetResponseSchema = z.object({
 				pending: z.boolean(),
 				success: z.boolean(),
 				error: z.string().nullable(),
-				result: z.string().nullable(),
+				result: z.record(z.string(), z.unknown()).nullable(),
 			})
 		)
 		.describe('Eval runs'),
@@ -171,48 +171,44 @@ export const getSubcommand = createSubcommand({
 				return result;
 			}
 
-			console.log(tui.bold('ID:          ') + session.id);
-			console.log(tui.bold('Project:     ') + session.project_id);
-			console.log(tui.bold('Deployment:  ') + (session.deployment_id || '-'));
-			console.log(tui.bold('Start:       ') + new Date(session.start_time).toLocaleString());
+			const tableData: Record<string, string> = {
+				ID: session.id,
+				Project: session.project_id,
+				Deployment: session.deployment_id || '-',
+				Start: new Date(session.start_time).toLocaleString(),
+			};
 			if (session.end_time) {
-				console.log(tui.bold('End:         ') + new Date(session.end_time).toLocaleString());
+				tableData['End'] = new Date(session.end_time).toLocaleString();
 			}
-			if (session.duration && session.end_time) {
-				console.log(
-					tui.bold('Duration:    ') + `${(session.duration / 1_000_000).toFixed(0)}ms`
-				);
+			if (session.duration != null && session.end_time != null) {
+				tableData['Duration'] = `${(session.duration / 1_000_000).toFixed(0)}ms`;
 			}
-			console.log(tui.bold('Method:      ') + session.method);
-			console.log(tui.bold('URL:         ') + tui.link(session.url, session.url));
-			console.log(tui.bold('Trigger:     ') + session.trigger);
+			tableData['Method'] = session.method;
+			tableData['URL'] = tui.link(session.url, session.url);
+			tableData['Trigger'] = session.trigger;
 			if (session.env !== 'production') {
-				console.log(tui.bold('Environment: ') + session.env);
+				tableData['Environment'] = session.env;
 			}
-			console.log(tui.bold('Dev Mode:    ') + (session.devmode ? 'Yes' : 'No'));
-			console.log(
-				tui.bold('Success:     ') +
-					(session.success ? tui.colorSuccess('✓') : tui.colorError('✗'))
-			);
-			console.log(tui.bold('Pending:     ') + (session.pending ? 'Yes' : 'No'));
+			tableData['Dev Mode'] = session.devmode ? 'Yes' : 'No';
+			tableData['Success'] = session.success ? tui.colorSuccess('✓') : tui.colorError('✗');
+			tableData['Pending'] = session.pending ? 'Yes' : 'No';
 			if (session.error) {
-				console.log(tui.bold('Error:       ') + tui.error(session.error));
+				tableData['Error'] = tui.colorError(session.error);
 			}
 			if (enriched.agents.length > 0) {
-				const agentDisplay = enriched.agents
+				tableData['Agents'] = enriched.agents
 					.map((agent: AgentInfo) => `${agent.name} ${tui.muted(`(${agent.identifier})`)}`)
 					.join(', ');
-				console.log(tui.bold('Agents:      ') + agentDisplay);
 			}
 			if (enriched.route) {
-				console.log(
-					tui.bold('Route:       ') +
-						`${enriched.route.method.toUpperCase()} ${enriched.route.path} ${tui.muted(`(${enriched.route.id})`)}`
-				);
+				tableData['Route'] =
+					`${enriched.route.method.toUpperCase()} ${enriched.route.path} ${tui.muted(`(${enriched.route.id})`)}`;
 			} else {
-				console.log(tui.bold('Route ID:    ') + session.route_id);
+				tableData['Route ID'] = session.route_id;
 			}
-			console.log(tui.bold('Thread ID:   ') + session.thread_id);
+			tableData['Thread ID'] = session.thread_id;
+
+			tui.table([tableData], Object.keys(tableData), { layout: 'vertical', padStart: '  ' });
 
 			if (enriched.evalRuns.length > 0) {
 				console.log('');

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

@@ -53,6 +53,10 @@ export const listSubcommand = createSubcommand({
 			command: getCommand('cloud session list --env=production'),
 			description: 'Only production environment',
 		},
+		{
+			command: getCommand('cloud session list --all'),
+			description: 'List all sessions regardless of project context',
+		},
 	],
 	aliases: ['ls'],
 	requires: { auth: true },
@@ -76,6 +80,7 @@ export const listSubcommand = createSubcommand({
 				.default(10)
 				.describe('Number of sessions to list (1–100)'),
 			projectId: z.string().optional().describe('Filter by project ID'),
+			all: z.boolean().optional().describe('List all sessions regardless of project context'),
 			deploymentId: z.string().optional().describe('Filter by deployment ID'),
 			trigger: z.string().optional().describe('Filter by trigger type (api, cron, webhook)'),
 			env: z.string().optional().describe('Filter by environment'),
@@ -89,14 +94,14 @@ export const listSubcommand = createSubcommand({
 		response: SessionListResponseSchema,
 	},
 	webUrl: (ctx) => {
-		const projectId = ctx.opts?.projectId || ctx.project?.projectId;
+		const projectId = ctx.opts?.all ? undefined : ctx.opts?.projectId || ctx.project?.projectId;
 		return projectId ? `/projects/${encodeURIComponent(projectId)}/sessions` : undefined;
 	},
 	async handler(ctx) {
 		const { logger, auth, project, opts, options, config } = ctx;
 		const catalystClient = await getGlobalCatalystAPIClient(logger, auth, config?.name);
 
-		const projectId = opts.projectId || project?.projectId;
+		const projectId = opts.all ? undefined : opts.projectId || project?.projectId;
 
 		try {
 			const sessions = await sessionList(catalystClient, {

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

@@ -59,21 +59,25 @@ export const getSubcommand = createSubcommand({
 				return result;
 			}
 
-			console.log(tui.bold('ID:          ') + thread.id);
-			console.log(tui.bold('Project:     ') + thread.project_id);
-			console.log(tui.bold('Created:     ') + new Date(thread.created_at).toLocaleString());
-			console.log(tui.bold('Updated:     ') + new Date(thread.updated_at).toLocaleString());
-			console.log(tui.bold('Deleted:     ') + (thread.deleted ? 'Yes' : 'No'));
+			const tableData: Record<string, string> = {
+				ID: thread.id,
+				Project: thread.project_id,
+				Created: new Date(thread.created_at).toLocaleString(),
+				Updated: new Date(thread.updated_at).toLocaleString(),
+				Deleted: thread.deleted ? 'Yes' : 'No',
+			};
 			if (thread.deleted_at) {
-				console.log(tui.bold('Deleted At:  ') + new Date(thread.deleted_at).toLocaleString());
+				tableData['Deleted At'] = new Date(thread.deleted_at).toLocaleString();
 			}
 			if (thread.deleted_by) {
-				console.log(tui.bold('Deleted By:  ') + thread.deleted_by);
+				tableData['Deleted By'] = thread.deleted_by;
 			}
 			if (thread.user_data) {
-				console.log(tui.bold('User Data:   ') + thread.user_data);
+				tableData['User Data'] = thread.user_data;
 			}
 
+			tui.table([tableData], Object.keys(tableData), { layout: 'vertical', padStart: '  ' });
+
 			return result;
 		} catch (ex) {
 			if (ex instanceof APIError && ex.status === 404) {

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

@@ -34,6 +34,10 @@ export const listSubcommand = createSubcommand({
 			command: getCommand('cloud thread list --org-id=org_*'),
 			description: 'Filter by organization',
 		},
+		{
+			command: getCommand('cloud thread list --all'),
+			description: 'List all threads regardless of project context',
+		},
 	],
 	aliases: ['ls'],
 	requires: { auth: true },
@@ -58,6 +62,7 @@ export const listSubcommand = createSubcommand({
 				.describe('Number of threads to list (1–100)'),
 			orgId: z.string().optional().describe('Filter by organization ID'),
 			projectId: z.string().optional().describe('Filter by project ID'),
+			all: z.boolean().optional().describe('List all threads regardless of project context'),
 		}),
 		response: ThreadListResponseSchema,
 	},
@@ -65,7 +70,7 @@ export const listSubcommand = createSubcommand({
 		const { logger, auth, project, opts, options, config } = ctx;
 		const catalystClient = await getGlobalCatalystAPIClient(logger, auth, config?.name);
 
-		const projectId = opts.projectId || project?.projectId;
+		const projectId = opts.all ? undefined : opts.projectId || project?.projectId;
 		const orgId = opts.orgId;
 
 		try {

package/src/cmd/dev/file-watcher.ts

@@ -55,6 +55,7 @@ export function createFileWatcher(options: FileWatcherOptions): FileWatcherManag
 		'.idea',
 		'.DS_Store',
 		'.playwright',
+		'.bun',
 		'src/generated',
 	]);
 
@@ -76,6 +77,7 @@ export function createFileWatcher(options: FileWatcherOptions): FileWatcherManag
 		'.dist',
 		'.vscode',
 		'.idea',
+		'.bun',
 		'.DS_Store',
 		'.playwright',
 		'src/web', // Vite handles frontend with HMR - no backend restart needed

package/src/cmd/dev/index.ts

@@ -12,9 +12,10 @@ import { APIClient, getAPIBaseURL, getAppBaseURL, getGravityDevModeURL } from '.
 import { download } from './download';
 import { createDevmodeSyncService } from './sync';
 import { getDevmodeDeploymentId } from '../build/ast';
-import { getDefaultConfigDir, saveConfig, loadProjectSDKKey } from '../../config';
+import { getDefaultConfigDir, saveConfig, loadProjectSDKKey, getAuth } from '../../config';
 import type { Config } from '../../types';
 import { typecheck } from '../build/typecheck';
+import { isTTY, hasLoggedInBefore } from '../../auth';
 import { createFileWatcher } from './file-watcher';
 import { regenerateSkillsAsync } from './skills';
 import { prepareDevLock, releaseLockSync } from './dev-lock';
@@ -171,12 +172,15 @@ export const command = createCommand({
 				.describe('The TCP port to start the dev server (also reads from PORT env)'),
 		}),
 	},
-	optional: { auth: 'Continue without an account (local only)', project: true },
+	optional: { project: true },
 
 	async handler(ctx) {
-		const { opts, logger, project, projectDir, auth } = ctx;
+		const { opts, logger, project, projectDir } = ctx;
 		let { config } = ctx;
 
+		// Get auth state - we handle auth ourselves based on project state
+		let auth = await getAuth();
+
 		const rootDir = resolve(projectDir);
 		const appTs = join(rootDir, 'app.ts');
 		const srcDir = join(rootDir, 'src');
@@ -208,6 +212,71 @@ export const command = createCommand({
 			originalExit(1);
 		}
 
+		// Handle authentication state based on project registration
+		if (project) {
+			// Registered project (has agentuity.json) - check if user needs to login
+			const isValidAuth = auth && auth.expires > new Date();
+			if (!isValidAuth) {
+				if (isTTY()) {
+					const hasProfile = await hasLoggedInBefore();
+					const message = hasProfile
+						? 'Your session has expired or you are not logged in.'
+						: 'This project is registered with Agentuity Cloud but you are not logged in.';
+
+					tui.warning(message);
+					tui.newline();
+
+					const shouldLogin = await tui.confirm(
+						hasProfile ? 'Would you like to login now?' : 'Would you like to login or create an account?',
+						true
+					);
+
+					if (shouldLogin) {
+						tui.newline();
+
+						// Run login flow inline
+						const { loginCommand } = await import('../auth/login');
+
+						// Ensure apiClient is available for login handler
+						const loginCtx = ctx as unknown as Record<string, unknown>;
+						if (!loginCtx.apiClient) {
+							loginCtx.apiClient = new APIClient(getAPIBaseURL(config), logger, config);
+						}
+
+						if (loginCommand.handler) {
+							await loginCommand.handler(
+								loginCtx as Parameters<NonNullable<typeof loginCommand.handler>>[0]
+							);
+						}
+
+						// Refresh auth state after login
+						const freshAuth = await getAuth();
+						if (!freshAuth || freshAuth.expires <= new Date()) {
+							tui.fatal('Login was not completed successfully.', ErrorCode.AUTH_FAILED);
+						}
+						auth = freshAuth;
+						tui.newline();
+						tui.success('Login successful! Continuing with dev server...');
+						tui.newline();
+					} else {
+						// User chose not to login - show warning about disabled features
+						tui.newline();
+						tui.showLoggedOutMessage(getAppBaseURL(config), hasProfile);
+					}
+				} else {
+					// Non-TTY: fatal error with instruction
+					logger.fatal(
+						`Authentication required for this project.\n` +
+							`Run "${getCommand('auth login')}" to login to Agentuity`,
+						ErrorCode.AUTH_REQUIRED
+					);
+				}
+			}
+		} else {
+			// No agentuity.json - local-only mode, ignore auth state
+			tui.showLocalOnlyWarning();
+		}
+
 		// Prepare dev lock: cleans up stale processes from previous sessions
 		// and creates a new lockfile for this session
 		const devLock = await prepareDevLock(rootDir, opts.port, logger);
@@ -229,7 +298,10 @@ export const command = createCommand({
 		try {
 			// Setup devmode and gravity (if using public URL)
 			const useMockService = process.env.DEVMODE_SYNC_SERVICE_MOCK === 'true';
-			const apiClient = auth ? new APIClient(getAPIBaseURL(config), logger, config) : null;
+			// Create apiClient with fresh auth API key (important after inline login)
+			const apiClient = auth
+				? new APIClient(getAPIBaseURL(config), logger, auth.apiKey, config)
+				: null;
 			const syncService = apiClient
 				? createDevmodeSyncService({
 						logger,

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

@@ -262,7 +262,7 @@ export async function detectOrmSetup(projectDir: string): Promise<OrmSetup> {
  * @returns SQL DDL statements for auth tables
  */
 export async function generateAuthSchemaSql(logger: Logger, projectDir: string): Promise<string> {
-	const schemaPath = path.join(projectDir, 'node_modules/@agentuity/auth/src/schema.ts');
+	const schemaPath = path.join(projectDir, 'node_modules/@agentuity/auth/dist/schema.js');
 
 	if (!(await Bun.file(schemaPath).exists())) {
 		throw new Error(

package/src/cmd/project/template-flow.ts

@@ -342,11 +342,25 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<void> {
 		}
 		switch (choices.db_action) {
 			case 'Create New': {
+				const dbName = await prompt.text({
+					message: 'Database name',
+					hint: 'Optional - press Enter to auto-generate',
+				});
+				const dbDescription = await prompt.text({
+					message: 'Database description',
+					hint: 'Optional - press Enter to skip',
+				});
 				const created = await tui.spinner({
 					message: 'Provisioning New SQL Database',
 					clearOnSuccess: true,
 					callback: async () => {
-						return createResources(catalystClient, orgId, region!, [{ type: 'db' }]);
+						return createResources(catalystClient, orgId, region!, [
+							{
+								type: 'db',
+								name: dbName || undefined,
+								description: dbDescription || undefined,
+							},
+						]);
 					},
 				});
 				// Collect env vars from newly created resource

package/src/cmd/setup/index.ts

@@ -1,9 +1,12 @@
 import { z } from 'zod';
 import { createCommand } from '../../types';
+import { hasLoggedInBefore } from '../../auth';
 import { showBanner } from '../../banner';
 import * as tui from '../../tui';
 import { getCommand } from '../../command-prefix';
 
+const validateToken = /[\d]{7,}\.[\w-_.]{22}/;
+
 export const command = createCommand({
 	name: 'setup',
 	description: 'Display first-run setup information (internal use)',
@@ -11,22 +14,57 @@ export const command = createCommand({
 	skipUpgradeCheck: true,
 	skipSkill: true,
 	tags: ['read-only', 'fast'],
-	optional: { auth: true },
 	schema: {
 		options: z.object({
 			nonInteractive: z.boolean().optional().describe('Run in non-interactive mode'),
+			setupToken: z.string().optional().describe('Use a one-time use setup token'),
 		}),
 	},
 
 	async handler(ctx) {
-		const { opts, auth } = ctx;
+		const { opts } = ctx;
 		const _nonInteractive = opts.nonInteractive ?? false;
 
+		// validate the one time setup token if provided
+		if (opts?.setupToken && opts.setupToken !== '-' && validateToken.test(opts.setupToken)) {
+			const [hours] = opts.setupToken.split('.');
+			const tokenInterval = Number(hours);
+			if (!Number.isNaN(tokenInterval)) {
+				const now = Math.round(Date.now() / (60_000 * 5));
+				if (tokenInterval === now || tokenInterval === now - 1) {
+					const ok = await tui.spinner({
+						message: 'Validating your identity',
+						clearOnSuccess: true,
+						callback: async () => {
+							const newargs = process.argv.map((x) => (x === 'setup' ? 'login' : x));
+							const r = Bun.spawn({
+								cmd: newargs.concat('--json'),
+								stdout: 'pipe',
+								stderr: 'inherit',
+							});
+							await r.exited;
+							try {
+								const res = JSON.parse(await r.stdout.text()) as { success: boolean };
+								return res.success;
+							} catch {
+								/* fall through */
+							}
+							return false;
+						},
+					});
+					if (ok) {
+						/* TODO */
+						return;
+					}
+				}
+			}
+		}
+
 		tui.newline();
 		showBanner();
 		tui.newline();
 
-		if (!auth?.expires) {
+		if (!(await hasLoggedInBefore())) {
 			tui.output(`${tui.muted('To get started, run:')}`);
 			tui.newline();
 			tui.output(