feat: suggest next actions

src/cli-core.ts

@@ -5,6 +5,7 @@
 import { Command as CommanderCommand } from 'commander';
 import type { Argument, CommandSpec, Specs } from './types.js';
 import { printDeprecated } from './utils/messages.js';
+import { exitWithError } from './utils/exit.js';
 
 export interface ModuleLoader {
   (commandPath: string[]): Promise<{
@@ -33,16 +34,11 @@ export function setupErrorHandlers() {
       console.error('\nOperation cancelled');
       process.exit(1);
     }
-    console.error(
-      '\nError:',
-      reason instanceof Error ? reason.message : reason
-    );
-    process.exit(1);
+    exitWithError(reason);
   });
 
   process.on('uncaughtException', (error) => {
-    console.error('\nError:', error.message);
-    process.exit(1);
+    exitWithError(error);
   });
 }
 
@@ -369,6 +365,11 @@ async function loadAndExecuteCommand(
   positionalArgs: string[] = [],
   options: Record<string, unknown> = {}
 ) {
+  // Set JSON mode globally for error handlers
+  if (options.json || options.format === 'json') {
+    globalThis.__TIGRIS_JSON_MODE = true;
+  }
+
   const { module, error: loadError } = await loadModule(pathParts);
 
   if (loadError || !module) {

src/global.d.ts

@@ -2,3 +2,7 @@ declare module '*.yaml' {
   const content: string;
   export default content;
 }
+
+// Global JSON mode flag set by CLI core when --json or --format=json is used
+// eslint-disable-next-line no-var
+declare var __TIGRIS_JSON_MODE: boolean | undefined;

src/lib/access-keys/assign.ts

@@ -10,6 +10,11 @@ import {
   printFailure,
   msg,
 } from '../../utils/messages.js';
+import {
+  exitWithError,
+  getSuccessNextActions,
+  printNextActions,
+} from '../../utils/exit.js';
 
 const context = msg('access-keys', 'assign');
 
@@ -44,12 +49,12 @@ export default async function assign(options: Record<string, unknown>) {
 
   if (!id) {
     printFailure(context, 'Access key ID is required');
-    process.exit(1);
+    exitWithError('Access key ID is required', context);
   }
 
   if (admin && revokeRoles) {
     printFailure(context, 'Cannot use --admin and --revoke-roles together');
-    process.exit(1);
+    exitWithError('Cannot use --admin and --revoke-roles together', context);
   }
 
   const loginMethod = await getLoginMethod();
@@ -59,15 +64,21 @@ export default async function assign(options: Record<string, unknown>) {
       context,
       'Bucket roles can only be managed when logged in via OAuth.\nRun "tigris login oauth" first.'
     );
-    process.exit(1);
+    exitWithError(
+      'Bucket roles can only be managed when logged in via OAuth.\nRun "tigris login oauth" first.',
+      context
+    );
   }
 
   const authClient = getAuthClient();
   const isAuthenticated = await authClient.isAuthenticated();
 
   if (!isAuthenticated) {
     printFailure(context, 'Not authenticated. Run "tigris login oauth" first.');
-    process.exit(1);
+    exitWithError(
+      'Not authenticated. Run "tigris login oauth" first.',
+      context
+    );
   }
 
   const accessToken = await authClient.getAccessToken();
@@ -85,7 +96,7 @@ export default async function assign(options: Record<string, unknown>) {
 
     if (error) {
       printFailure(context, error.message);
-      process.exit(1);
+      exitWithError(error, context);
     }
 
     if (format === 'json') {
@@ -107,15 +118,21 @@ export default async function assign(options: Record<string, unknown>) {
         context,
         'At least one bucket name is required (or use --admin or --revoke-roles)'
       );
-      process.exit(1);
+      exitWithError(
+        'At least one bucket name is required (or use --admin or --revoke-roles)',
+        context
+      );
     }
 
     if (roles.length === 0) {
       printFailure(
         context,
         'At least one role is required (or use --admin or --revoke-roles)'
       );
-      process.exit(1);
+      exitWithError(
+        'At least one role is required (or use --admin or --revoke-roles)',
+        context
+      );
     }
 
     // Validate all roles
@@ -125,7 +142,10 @@ export default async function assign(options: Record<string, unknown>) {
           context,
           `Invalid role "${role}". Valid roles are: ${validRoles.join(', ')}`
         );
-        process.exit(1);
+        exitWithError(
+          `Invalid role "${role}". Valid roles are: ${validRoles.join(', ')}`,
+          context
+        );
       }
     }
 
@@ -147,20 +167,31 @@ export default async function assign(options: Record<string, unknown>) {
         context,
         `Number of roles (${roles.length}) must be 1 or match number of buckets (${buckets.length})`
       );
-      process.exit(1);
+      exitWithError(
+        `Number of roles (${roles.length}) must be 1 or match number of buckets (${buckets.length})`,
+        context
+      );
     }
   }
 
   const { error } = await assignBucketRoles(id, assignments, { config });
 
   if (error) {
     printFailure(context, error.message);
-    process.exit(1);
+    exitWithError(error, context);
   }
 
   if (format === 'json') {
-    console.log(JSON.stringify({ action: 'assigned', id, assignments }));
+    const nextActions = getSuccessNextActions(context);
+    const output: Record<string, unknown> = {
+      action: 'assigned',
+      id,
+      assignments,
+    };
+    if (nextActions.length > 0) output.nextActions = nextActions;
+    console.log(JSON.stringify(output));
   }
 
   printSuccess(context);
+  printNextActions(context);
 }

src/lib/access-keys/create.ts

@@ -10,6 +10,11 @@ import {
   printFailure,
   msg,
 } from '../../utils/messages.js';
+import {
+  exitWithError,
+  getSuccessNextActions,
+  printNextActions,
+} from '../../utils/exit.js';
 
 const context = msg('access-keys', 'create');
 
@@ -25,7 +30,7 @@ export default async function create(options: Record<string, unknown>) {
 
   if (!name) {
     printFailure(context, 'Access key name is required');
-    process.exit(1);
+    exitWithError('Access key name is required', context);
   }
 
   const loginMethod = await getLoginMethod();
@@ -35,15 +40,21 @@ export default async function create(options: Record<string, unknown>) {
       context,
       'Access keys can only be created when logged in via OAuth.\nRun "tigris login oauth" first.'
     );
-    process.exit(1);
+    exitWithError(
+      'Access keys can only be created when logged in via OAuth.\nRun "tigris login oauth" first.',
+      context
+    );
   }
 
   const authClient = getAuthClient();
   const isAuthenticated = await authClient.isAuthenticated();
 
   if (!isAuthenticated) {
     printFailure(context, 'Not authenticated. Run "tigris login oauth" first.');
-    process.exit(1);
+    exitWithError(
+      'Not authenticated. Run "tigris login oauth" first.',
+      context
+    );
   }
 
   const accessToken = await authClient.getAccessToken();
@@ -60,18 +71,22 @@ export default async function create(options: Record<string, unknown>) {
 
   if (error) {
     printFailure(context, error.message);
-    process.exit(1);
+    exitWithError(error, context);
   }
 
   if (format === 'json') {
-    console.log(
-      JSON.stringify({
-        action: 'created',
-        name: data.name,
-        id: data.id,
-        secret: data.secret,
-      })
-    );
+    const nextActions = getSuccessNextActions(context, {
+      name: data.name,
+      id: data.id,
+    });
+    const output: Record<string, unknown> = {
+      action: 'created',
+      name: data.name,
+      id: data.id,
+      secret: data.secret,
+    };
+    if (nextActions.length > 0) output.nextActions = nextActions;
+    console.log(JSON.stringify(output));
   } else {
     console.log(`  Name: ${data.name}`);
     console.log(`  Access Key ID: ${data.id}`);
@@ -83,4 +98,5 @@ export default async function create(options: Record<string, unknown>) {
   }
 
   printSuccess(context);
+  printNextActions(context, { name: data.name, id: data.id });
 }

src/lib/access-keys/delete.ts

@@ -10,6 +10,7 @@ import {
   printFailure,
   msg,
 } from '../../utils/messages.js';
+import { exitWithError } from '../../utils/exit.js';
 import { requireInteractive, confirm } from '../../utils/interactive.js';
 
 const context = msg('access-keys', 'delete');
@@ -27,7 +28,7 @@ export default async function remove(options: Record<string, unknown>) {
 
   if (!id) {
     printFailure(context, 'Access key ID is required');
-    process.exit(1);
+    exitWithError('Access key ID is required', context);
   }
 
   const loginMethod = await getLoginMethod();
@@ -37,15 +38,21 @@ export default async function remove(options: Record<string, unknown>) {
       context,
       'Access keys can only be deleted when logged in via OAuth.\nRun "tigris login oauth" first.'
     );
-    process.exit(1);
+    exitWithError(
+      'Access keys can only be deleted when logged in via OAuth.\nRun "tigris login oauth" first.',
+      context
+    );
   }
 
   const authClient = getAuthClient();
   const isAuthenticated = await authClient.isAuthenticated();
 
   if (!isAuthenticated) {
     printFailure(context, 'Not authenticated. Run "tigris login oauth" first.');
-    process.exit(1);
+    exitWithError(
+      'Not authenticated. Run "tigris login oauth" first.',
+      context
+    );
   }
 
   if (!force) {
@@ -71,7 +78,7 @@ export default async function remove(options: Record<string, unknown>) {
 
   if (error) {
     printFailure(context, error.message);
-    process.exit(1);
+    exitWithError(error, context);
   }
 
   if (format === 'json') {

src/lib/access-keys/get.ts

@@ -10,6 +10,7 @@ import {
   printFailure,
   msg,
 } from '../../utils/messages.js';
+import { exitWithError } from '../../utils/exit.js';
 
 const context = msg('access-keys', 'get');
 
@@ -25,7 +26,7 @@ export default async function get(options: Record<string, unknown>) {
 
   if (!id) {
     printFailure(context, 'Access key ID is required');
-    process.exit(1);
+    exitWithError('Access key ID is required', context);
   }
 
   const loginMethod = await getLoginMethod();
@@ -35,15 +36,21 @@ export default async function get(options: Record<string, unknown>) {
       context,
       'Access keys can only be retrieved when logged in via OAuth.\nRun "tigris login oauth" first.'
     );
-    process.exit(1);
+    exitWithError(
+      'Access keys can only be retrieved when logged in via OAuth.\nRun "tigris login oauth" first.',
+      context
+    );
   }
 
   const authClient = getAuthClient();
   const isAuthenticated = await authClient.isAuthenticated();
 
   if (!isAuthenticated) {
     printFailure(context, 'Not authenticated. Run "tigris login oauth" first.');
-    process.exit(1);
+    exitWithError(
+      'Not authenticated. Run "tigris login oauth" first.',
+      context
+    );
   }
 
   const accessToken = await authClient.getAccessToken();
@@ -60,7 +67,7 @@ export default async function get(options: Record<string, unknown>) {
 
   if (error) {
     printFailure(context, error.message);
-    process.exit(1);
+    exitWithError(error, context);
   }
 
   if (format === 'json') {