@plosson/agentio 0.4.0 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plosson/agentio",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "CLI for LLM agents to interact with communication and tracking services",
   "type": "module",
   "license": "MIT",
@@ -46,6 +46,7 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
+    "@inquirer/prompts": "^8.2.0",
     "commander": "^14.0.2",
     "googleapis": "^169.0.0",
     "libsodium-wrappers": "^0.8.1",

package/src/commands/config.ts

@@ -7,9 +7,15 @@ import { loadConfig, saveConfig, setEnv, unsetEnv, listEnv } from '../config/con
 import { getAllCredentials, setAllCredentials } from '../auth/token-store';
 import { CliError, handleError } from '../utils/errors';
 import { confirm } from '../utils/stdin';
-import type { Config } from '../types/config';
+import { isInteractive, interactiveCheckbox, interactiveSelect } from '../utils/interactive';
+import type { Config, ServiceName } from '../types/config';
 import type { StoredCredentials } from '../types/tokens';
 
+interface ProfileSelection {
+  service: ServiceName;
+  profile: string;
+}
+
 const ALGORITHM = 'aes-256-gcm';
 
 interface ExportedData {
@@ -94,6 +100,7 @@ export function registerConfigCommands(program: Command): void {
     .description('Export configuration and credentials (as environment variables by default, or to a file)')
     .option('--key <key>', 'Encryption key (64 hex characters). If not provided, a random key will be generated')
     .option('--file <path>', 'Write encrypted config to file instead of outputting AGENTIO_CONFIG')
+    .option('--all', 'Export all profiles without prompting for selection')
     .action(async (options) => {
       try {
         // Validate key if provided
@@ -115,23 +122,103 @@ export function registerConfigCommands(program: Command): void {
         const configData = await loadConfig();
         const credentials = await getAllCredentials();
 
+        // Build list of all available profiles
+        const allProfiles: ProfileSelection[] = [];
+        for (const [service, profiles] of Object.entries(configData.profiles)) {
+          if (profiles) {
+            for (const profile of profiles) {
+              allProfiles.push({ service: service as ServiceName, profile });
+            }
+          }
+        }
+
+        if (allProfiles.length === 0) {
+          throw new CliError(
+            'NOT_FOUND',
+            'No profiles configured',
+            'Add profiles first with: agentio <service> profile add'
+          );
+        }
+
+        // Determine which profiles to export
+        let selectedProfiles: ProfileSelection[];
+
+        if (options.all || !isInteractive()) {
+          // Export all profiles
+          selectedProfiles = allProfiles;
+        } else {
+          // Interactive: ask user to select profiles
+          const exportAll = await interactiveSelect({
+            message: 'What would you like to export?',
+            choices: [
+              { name: `All profiles (${allProfiles.length})`, value: 'all' },
+              { name: 'Select specific profiles', value: 'select' },
+            ],
+            default: 'all',
+          });
+
+          if (exportAll === 'all') {
+            selectedProfiles = allProfiles;
+          } else {
+            selectedProfiles = await interactiveCheckbox({
+              message: 'Select profiles to export:',
+              choices: allProfiles.map((p) => ({
+                name: `${p.service}: ${p.profile}`,
+                value: p,
+                checked: false,
+              })),
+              required: true,
+            });
+          }
+        }
+
+        // Filter config and credentials based on selection
+        const filteredConfig: Config = { profiles: {} };
+        const filteredCredentials: StoredCredentials = {};
+
+        for (const { service, profile } of selectedProfiles) {
+          // Add to filtered config
+          if (!filteredConfig.profiles[service]) {
+            (filteredConfig.profiles as Record<string, string[]>)[service] = [];
+          }
+          (filteredConfig.profiles as Record<string, string[]>)[service].push(profile);
+
+          // Add credentials if they exist
+          if (credentials[service]?.[profile]) {
+            if (!filteredCredentials[service]) {
+              filteredCredentials[service] = {};
+            }
+            filteredCredentials[service][profile] = credentials[service][profile];
+          }
+        }
+
+        // Include env vars if they exist
+        if (configData.env) {
+          filteredConfig.env = configData.env;
+        }
+
         const exportData: ExportedData = {
           version: 1,
-          config: configData,
-          credentials,
+          config: filteredConfig,
+          credentials: filteredCredentials,
         };
 
         // Encrypt the data
         const key = deriveKeyFromPassword(encryptionKey);
         const encrypted = encrypt(JSON.stringify(exportData), key);
 
+        const profileCount = selectedProfiles.length;
+        const profileText = profileCount === 1 ? 'profile' : 'profiles';
+
         if (options.file) {
           // Write to file, output just the key
           const filePath = options.file.startsWith('/') ? options.file : join(process.cwd(), options.file);
           await writeFile(filePath, encrypted, { mode: 0o600 });
+          console.error(`Exported ${profileCount} ${profileText} to ${filePath}`);
           console.log(`AGENTIO_KEY=${encryptionKey}`);
         } else {
           // Output as environment variables
+          console.error(`Exported ${profileCount} ${profileText}`);
           console.log(`AGENTIO_KEY=${encryptionKey}`);
           console.log(`AGENTIO_CONFIG=${encrypted}`);
         }

package/src/commands/docs.ts

@@ -0,0 +1,126 @@
+import { Command } from 'commander';
+
+interface CommandInfo {
+  fullPath: string;
+  description: string;
+  arguments: string[];
+  options: Array<{ flags: string; description: string; defaultValue?: string }>;
+}
+
+function collectCommands(cmd: Command, parentPath: string = ''): CommandInfo[] {
+  const results: CommandInfo[] = [];
+  const help = cmd.createHelp();
+
+  // Get visible subcommands (filters out help command)
+  const subcommands = help.visibleCommands(cmd).filter((c) => c.name() !== 'help');
+
+  for (const subcmd of subcommands) {
+    const fullPath = parentPath ? `${parentPath} ${subcmd.name()}` : subcmd.name();
+
+    // Get arguments
+    const args = help.visibleArguments(subcmd).map((arg) => {
+      const argName = arg.variadic ? `${arg.name()}...` : arg.name();
+      return arg.required ? `<${argName}>` : `[${argName}]`;
+    });
+
+    // Get options (filter out help)
+    const options = help
+      .visibleOptions(subcmd)
+      .filter((opt) => !opt.long?.includes('help'))
+      .map((opt) => {
+        const flags = opt.flags;
+        const desc = opt.description;
+        const defaultVal = opt.defaultValue;
+        return { flags, description: desc, defaultValue: defaultVal };
+      });
+
+    const description = subcmd.description() || '';
+
+    // Only add if it's a leaf command or has its own action
+    const childCommands = help.visibleCommands(subcmd).filter((c) => c.name() !== 'help');
+    if (childCommands.length === 0 || options.length > 0 || args.length > 0) {
+      results.push({
+        fullPath,
+        description,
+        arguments: args,
+        options,
+      });
+    }
+
+    // Recurse into subcommands
+    results.push(...collectCommands(subcmd, fullPath));
+  }
+
+  return results;
+}
+
+function formatOption(opt: { flags: string; description: string; defaultValue?: string }): string {
+  let line = opt.flags;
+  if (opt.description) {
+    line += `: ${opt.description}`;
+  }
+  if (opt.defaultValue !== undefined && opt.defaultValue !== '') {
+    line += ` (default: ${opt.defaultValue})`;
+  }
+  return line;
+}
+
+// Commands excluded from docs output by default (utility/meta commands)
+const EXCLUDED_COMMANDS = ['config', 'status', 'update', 'claude', 'docs'];
+
+function generateDocs(program: Command, services?: string[]): string {
+  const lines: string[] = [];
+  const version = program.version();
+
+  lines.push(`# agentio CLI v${version}`);
+  lines.push('');
+
+  let commands = collectCommands(program, 'agentio');
+
+  // Filter by services if specified, otherwise exclude utility commands
+  // Always exclude profile subcommands
+  commands = commands.filter((cmd) => {
+    if (cmd.fullPath.includes(' profile ')) {
+      return false;
+    }
+    const parts = cmd.fullPath.split(' ');
+    const service = parts[1];
+    if (services && services.length > 0) {
+      return services.includes(service);
+    }
+    return !EXCLUDED_COMMANDS.includes(service);
+  });
+
+  for (const cmd of commands) {
+    // Header with full path and arguments
+    let header = `## ${cmd.fullPath}`;
+    if (cmd.arguments.length > 0) {
+      header += ` ${cmd.arguments.join(' ')}`;
+    }
+    lines.push(header);
+
+    // Description
+    if (cmd.description) {
+      lines.push(cmd.description);
+    }
+
+    // Options
+    for (const opt of cmd.options) {
+      lines.push(formatOption(opt));
+    }
+
+    lines.push('');
+  }
+
+  return lines.join('\n').trimEnd();
+}
+
+export function registerDocsCommand(program: Command): void {
+  program
+    .command('docs')
+    .description('Output CLI reference for LLMs')
+    .option('--service <names>', 'Filter by service (comma-separated)', (val) => val.split(',').map((s: string) => s.trim()))
+    .action((options) => {
+      console.log(generateDocs(program, options.service));
+    });
+}

package/src/commands/gchat.ts

@@ -10,6 +10,7 @@ import { createGoogleAuth } from '../auth/token-manager';
 import { GChatClient } from '../services/gchat/client';
 import { CliError, handleError } from '../utils/errors';
 import { readStdin, prompt } from '../utils/stdin';
+import { interactiveSelect } from '../utils/interactive';
 import { printGChatSendResult, printGChatMessageList, printGChatMessage, printGChatSpaceList } from '../utils/output';
 import type { GChatCredentials, GChatWebhookCredentials, GChatOAuthCredentials } from '../types/gchat';
 
@@ -133,7 +134,8 @@ export function registerGChatCommands(program: Command): void {
     });
 
   gchat
-    .command('get <message-id>')
+    .command('get')
+    .argument('<message-id>', 'Message ID')
     .description('Get a message from a Google Chat space (OAuth profiles only)')
     .option('--profile <name>', 'Profile name (optional if only one profile exists)')
     .requiredOption('--space <id>', 'Space ID')
@@ -187,9 +189,15 @@ export function registerGChatCommands(program: Command): void {
       try {
         console.error('\nGoogle Chat Setup\n');
 
-        const profileType = await prompt('Choose profile type (webhook/oauth): ');
+        const profileType = await interactiveSelect({
+          message: 'Choose profile type:',
+          choices: [
+            { name: 'Webhook', value: 'webhook', description: 'Simple incoming webhook URL' },
+            { name: 'OAuth', value: 'oauth', description: 'Full API access with Google Workspace account' },
+          ],
+        });
 
-        if (profileType.toLowerCase() === 'webhook') {
+        if (profileType === 'webhook') {
           if (!options.profile) {
             throw new CliError(
               'INVALID_PARAMS',
@@ -198,10 +206,8 @@ export function registerGChatCommands(program: Command): void {
             );
           }
           await setupWebhookProfile(options.profile);
-        } else if (profileType.toLowerCase() === 'oauth') {
-          await setupOAuthProfile(options.profile);
         } else {
-          throw new CliError('INVALID_PARAMS', 'Profile type must be "webhook" or "oauth"');
+          await setupOAuthProfile(options.profile);
         }
       } catch (error) {
         handleError(error);

package/src/commands/gdocs.ts

@@ -24,7 +24,8 @@ export function registerGDocsCommands(program: Command): void {
     .description('Google Docs operations');
 
   gdocs
-    .command('get <doc-id-or-url>')
+    .command('get')
+    .argument('<doc-id-or-url>', 'Document ID or URL')
     .description('Export a document')
     .option('--profile <name>', 'Profile name (optional if only one profile exists)')
     .option('--format <format>', 'Export format: markdown or docx', 'markdown')

package/src/commands/gdrive.ts

@@ -95,7 +95,8 @@ Query Syntax Examples:
     });
 
   gdrive
-    .command('get <file-id-or-url>')
+    .command('get')
+    .argument('<file-id-or-url>', 'File ID or URL')
     .description('Get file metadata')
     .option('--profile <name>', 'Profile name')
     .action(async (fileIdOrUrl: string, options) => {
@@ -132,7 +133,8 @@ Query Syntax Examples:
     });
 
   gdrive
-    .command('download <file-id-or-url>')
+    .command('download')
+    .argument('<file-id-or-url>', 'File ID or URL')
     .description('Download a file (or export Google Workspace files)')
     .option('--profile <name>', 'Profile name')
     .requiredOption('--output <path>', 'Output file path')
@@ -164,7 +166,8 @@ Examples:
     });
 
   gdrive
-    .command('put <file-path>')
+    .command('put')
+    .argument('<file-path>', 'Local file path')
     .description('Upload a file to Google Drive')
     .option('--profile <name>', 'Profile name')
     .option('--name <name>', 'Name for the file in Drive (defaults to local filename)')

package/src/commands/gmail.ts

@@ -101,7 +101,8 @@ export function registerGmailCommands(program: Command): void {
     });
 
   gmail
-    .command('get <message-id>')
+    .command('get')
+    .argument('<message-id>', 'Message ID')
     .description('Get a message')
     .option('--profile <name>', 'Profile name (optional if only one profile exists)')
     .option('--format <format>', 'Body format: text, html, or raw', 'text')
@@ -275,7 +276,8 @@ Query Syntax Examples:
     });
 
   gmail
-    .command('archive <message-id...>')
+    .command('archive')
+    .argument('<message-id...>', 'Message ID(s)')
     .description('Archive one or more messages')
     .option('--profile <name>', 'Profile name (optional if only one profile exists)')
     .action(async (messageIds: string[], options) => {
@@ -291,7 +293,8 @@ Query Syntax Examples:
     });
 
   gmail
-    .command('mark <message-id...>')
+    .command('mark')
+    .argument('<message-id...>', 'Message ID(s)')
     .description('Mark one or more messages as read or unread')
     .option('--profile <name>', 'Profile name (optional if only one profile exists)')
     .option('--read', 'Mark as read')
@@ -316,7 +319,8 @@ Query Syntax Examples:
     });
 
   gmail
-    .command('attachment <message-id>')
+    .command('attachment')
+    .argument('<message-id>', 'Message ID')
     .description('Download attachments from a message')
     .option('--profile <name>', 'Profile name (optional if only one profile exists)')
     .option('--name <filename>', 'Download specific attachment by filename (downloads all if not specified)')
@@ -359,7 +363,8 @@ Query Syntax Examples:
     });
 
   gmail
-    .command('export <message-id>')
+    .command('export')
+    .argument('<message-id>', 'Message ID')
     .description('Export a message as PDF')
     .option('--profile <name>', 'Profile name (optional if only one profile exists)')
     .option('--output <path>', 'Output file path', 'message.pdf')

package/src/commands/jira.ts

@@ -5,7 +5,8 @@ import { createProfileCommands } from '../utils/profile-commands';
 import { performJiraOAuthFlow, refreshJiraToken, type AtlassianSite } from '../auth/jira-oauth';
 import { JiraClient } from '../services/jira/client';
 import { CliError, handleError } from '../utils/errors';
-import { readStdin, prompt } from '../utils/stdin';
+import { readStdin } from '../utils/stdin';
+import { interactiveSelect } from '../utils/interactive';
 import {
   printJiraProjectList,
   printJiraIssueList,
@@ -220,20 +221,14 @@ export function registerJiraCommands(program: Command): void {
 
         // Site selection callback
         const selectSite = async (sites: AtlassianSite[]): Promise<AtlassianSite> => {
-          console.error('\nMultiple JIRA sites found:\n');
-          sites.forEach((site, index) => {
-            console.error(`  [${index + 1}] ${site.name} (${site.url})`);
+          return interactiveSelect({
+            message: 'Select a JIRA site:',
+            choices: sites.map((site) => ({
+              name: site.name,
+              value: site,
+              description: site.url,
+            })),
           });
-          console.error('');
-
-          const choice = await prompt(`? Select a site (1-${sites.length}): `);
-          const index = parseInt(choice, 10) - 1;
-
-          if (isNaN(index) || index < 0 || index >= sites.length) {
-            throw new CliError('INVALID_PARAMS', 'Invalid selection');
-          }
-
-          return sites[index];
         };
 
         const result = await performJiraOAuthFlow(selectSite);

package/src/commands/sql.ts

@@ -6,6 +6,7 @@ import { createClientGetter } from '../utils/client-factory';
 import { SqlClient } from '../services/sql/client';
 import { CliError, handleError } from '../utils/errors';
 import { readStdin, prompt } from '../utils/stdin';
+import { interactiveSelect } from '../utils/interactive';
 import type { SqlCredentials } from '../types/sql';
 
 const getSqlClient = createClientGetter<SqlCredentials, SqlClient>({
@@ -138,31 +139,16 @@ async function promptInteractiveConnection(): Promise<string> {
   console.error('\nSQL Database Setup (Interactive)\n');
 
   // Database type
-  console.error('Database type:');
-  console.error('  1. PostgreSQL');
-  console.error('  2. MySQL');
-  console.error('  3. SQLite\n');
-
-  const typeChoice = await prompt('? Select type (1-3): ');
-  let dbType: 'postgres' | 'mysql' | 'sqlite';
-  let defaultPort: string;
-
-  switch (typeChoice) {
-    case '1':
-      dbType = 'postgres';
-      defaultPort = '5432';
-      break;
-    case '2':
-      dbType = 'mysql';
-      defaultPort = '3306';
-      break;
-    case '3':
-      dbType = 'sqlite';
-      defaultPort = '';
-      break;
-    default:
-      throw new CliError('INVALID_PARAMS', 'Invalid database type selection');
-  }
+  const dbType = await interactiveSelect({
+    message: 'Select database type:',
+    choices: [
+      { name: 'PostgreSQL', value: 'postgres' as const, description: 'Default port 5432' },
+      { name: 'MySQL', value: 'mysql' as const, description: 'Default port 3306' },
+      { name: 'SQLite', value: 'sqlite' as const, description: 'Local file database' },
+    ],
+  });
+
+  const defaultPort = dbType === 'postgres' ? '5432' : dbType === 'mysql' ? '3306' : '';
 
   // SQLite only needs a file path
   if (dbType === 'sqlite') {

package/src/index.ts

@@ -15,6 +15,7 @@ import { registerUpdateCommand } from './commands/update';
 import { registerConfigCommands } from './commands/config';
 import { registerClaudeCommands } from './commands/claude';
 import { registerStatusCommand } from './commands/status';
+import { registerDocsCommand } from './commands/docs';
 
 declare const BUILD_VERSION: string | undefined;
 
@@ -48,5 +49,6 @@ registerUpdateCommand(program);
 registerConfigCommands(program);
 registerClaudeCommands(program);
 registerStatusCommand(program);
+registerDocsCommand(program);
 
 program.parse();

package/src/utils/interactive.ts

@@ -0,0 +1,145 @@
+import {
+  select,
+  checkbox,
+  confirm as inquirerConfirm,
+  input,
+} from '@inquirer/prompts';
+import { CliError } from './errors';
+
+export interface SelectChoice<T> {
+  name: string;
+  value: T;
+  description?: string;
+}
+
+export interface CheckboxChoice<T> {
+  name: string;
+  value: T;
+  checked?: boolean;
+}
+
+/**
+ * Check if running in an interactive terminal.
+ */
+export function isInteractive(): boolean {
+  return process.stdin.isTTY === true;
+}
+
+/**
+ * Interactive select prompt. Falls back to default or throws if not in TTY.
+ */
+export async function interactiveSelect<T>(options: {
+  message: string;
+  choices: SelectChoice<T>[];
+  default?: T;
+}): Promise<T> {
+  if (!isInteractive()) {
+    if (options.default !== undefined) {
+      return options.default;
+    }
+    throw new CliError(
+      'INVALID_PARAMS',
+      'Interactive input required but not running in terminal',
+      'Run this command in an interactive terminal'
+    );
+  }
+
+  return select({
+    message: options.message,
+    choices: options.choices,
+    default: options.default,
+    loop: false,
+  });
+}
+
+/**
+ * Interactive checkbox (multi-select) prompt. Falls back to default or throws if not in TTY.
+ */
+export async function interactiveCheckbox<T>(options: {
+  message: string;
+  choices: CheckboxChoice<T>[];
+  required?: boolean;
+}): Promise<T[]> {
+  if (!isInteractive()) {
+    // Return all checked items as default
+    const defaults = options.choices.filter((c) => c.checked).map((c) => c.value);
+    if (defaults.length > 0 || !options.required) {
+      return defaults;
+    }
+    throw new CliError(
+      'INVALID_PARAMS',
+      'Interactive input required but not running in terminal',
+      'Run this command in an interactive terminal'
+    );
+  }
+
+  const result = await checkbox({
+    message: options.message,
+    choices: options.choices,
+    loop: false,
+  });
+
+  if (options.required && result.length === 0) {
+    throw new CliError('INVALID_PARAMS', 'At least one option must be selected');
+  }
+
+  return result;
+}
+
+/**
+ * Interactive confirm prompt. Falls back to default or throws if not in TTY.
+ */
+export async function interactiveConfirm(options: {
+  message: string;
+  default?: boolean;
+}): Promise<boolean> {
+  if (!isInteractive()) {
+    if (options.default !== undefined) {
+      return options.default;
+    }
+    throw new CliError(
+      'INVALID_PARAMS',
+      'Interactive input required but not running in terminal',
+      'Run this command in an interactive terminal'
+    );
+  }
+
+  return inquirerConfirm({
+    message: options.message,
+    default: options.default,
+  });
+}
+
+/**
+ * Interactive text input prompt. Falls back to default or throws if not in TTY.
+ */
+export async function interactiveInput(options: {
+  message: string;
+  default?: string;
+  required?: boolean;
+}): Promise<string> {
+  if (!isInteractive()) {
+    if (options.default !== undefined) {
+      return options.default;
+    }
+    if (!options.required) {
+      return '';
+    }
+    throw new CliError(
+      'INVALID_PARAMS',
+      'Interactive input required but not running in terminal',
+      'Run this command in an interactive terminal'
+    );
+  }
+
+  const result = await input({
+    message: options.message,
+    default: options.default,
+  });
+
+  if (options.required && !result.trim()) {
+    throw new CliError('INVALID_PARAMS', 'Input is required');
+  }
+
+  return result;
+}