explorbot 0.4.5 → 0.4.6

package/boat/api-tester/src/apibot.ts

@@ -2,10 +2,10 @@ import { existsSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
 import { AIProvider } from '../../../src/ai/provider.ts';
 import { RequestStore } from '../../../src/api/request-store.ts';
-import { extractEndpointDefinition, loadSpec, searchEndpoints, validateSpecs } from '../../../src/api/spec-reader.ts';
+import { extractEndpointDefinition, loadSpec, resolveEndpoints, searchEndpoints, validateSpecs } from '../../../src/api/spec-reader.ts';
 import { KnowledgeTracker } from '../../../src/knowledge-tracker.ts';
 import { Reporter } from '../../../src/reporter.ts';
-import { Plan } from '../../../src/test-plan.ts';
+import { Plan, type Test } from '../../../src/test-plan.ts';
 import { setVerboseMode, tag } from '../../../src/utils/logger.ts';
 import { Chief } from './ai/chief.ts';
 import { Curler } from './ai/curler.ts';
@@ -170,6 +170,18 @@ export class ApiBot {
     return this.configParser;
   }
 
+  getOptions(): ApibotOptions {
+    return this.options;
+  }
+
+  async runTest(test: Test): Promise<{ success: boolean }> {
+    return this.agentCurler().test(test, {
+      specDefinition: this.tryGetEndpointDefinition(test.startUrl!),
+      baseEndpoint: this.config.api.baseEndpoint,
+      searchSpec: (query: string) => this.searchSpec(query),
+    });
+  }
+
   getRequestState(): RequestStore {
     return this.requestState;
   }
@@ -178,6 +190,10 @@ export class ApiBot {
     return extractEndpointDefinition(this.apiSpec, endpoint, this.config.api.baseEndpoint);
   }
 
+  expandEndpoints(pattern: string): string[] {
+    return resolveEndpoints(this.apiSpec, this.configParser.resolveEndpointPath(pattern), this.config.api.baseEndpoint);
+  }
+
   searchSpec(query: string): string {
     return searchEndpoints(this.apiSpec, query, this.config.api.baseEndpoint);
   }

package/boat/api-tester/src/cli.ts

@@ -1,100 +1,33 @@
-import fs from 'node:fs';
-import path from 'node:path';
 import { Command } from 'commander';
 import { ConfigCommand } from '../../../src/commands/config-command.ts';
 import { RecommendedModelsCommand } from '../../../src/commands/recommended-models-command.ts';
 import { listSites } from '../../../src/global-config.ts';
 import { setPreserveConsoleLogs } from '../../../src/utils/logger.ts';
-import { getStyles } from './ai/chief/styles.ts';
 import { ApiBot, type ApibotOptions } from './apibot.ts';
+import { ExploreCommand } from './commands/explore-command.ts';
+import { runInit } from './commands/init-command.ts';
+import { KnowCommand } from './commands/know-command.ts';
+import { PlanCommand } from './commands/plan-command.ts';
+import { TestCommand } from './commands/test-command.ts';
 import { ApibotConfigParser } from './config.ts';
 
-function buildOptions(options: any): ApibotOptions {
-  return {
-    verbose: options.verbose || options.debug,
-    config: options.config,
-    path: options.path,
-    baseEndpoint: options.endpoint,
-    spec: options.spec,
-    header: options.header,
-  };
-}
-
-function addCommonOptions(cmd: Command): Command {
-  return cmd
-    .option('-v, --verbose', 'Enable verbose logging')
-    .option('--debug', 'Enable debug logging')
-    .option('-c, --config <path>', 'Path to configuration file')
-    .option('-p, --path <path>', 'Working directory path')
-    .option('--endpoint <url>', 'Base API endpoint to test (env: EXPLORBOT_URL)')
-    .option('--spec <path>', 'OpenAPI spec file or URL (env: EXPLORBOT_API_SPEC)')
-    .option('-H, --header <header>', 'Header sent with every request, as "Name: value". Repeatable (env: EXPLORBOT_API_HEADERS)', (value: string, previous: string[] = []) => [...previous, value]);
-}
-
-function selectTests(tests: any[], index?: string): any[] {
-  if (!index || index === '*' || index === 'all') {
-    return tests.filter((t) => t.status === 'pending');
-  }
-
-  const rangeMatch = index.match(/^(\d+)-(\d+)$/);
-  if (rangeMatch) {
-    const start = Number.parseInt(rangeMatch[1]) - 1;
-    const end = Number.parseInt(rangeMatch[2]);
-    return tests.slice(start, end);
-  }
-
-  if (index.includes(',')) {
-    const indices = index.split(',').map((i) => Number.parseInt(i.trim()) - 1);
-    return indices.map((i) => tests[i]).filter(Boolean);
-  }
-
-  const num = Number.parseInt(index);
-  if (!Number.isNaN(num) && tests[num - 1]) {
-    return [tests[num - 1]];
-  }
-
-  return tests.filter((t) => t.status === 'pending');
-}
-
 export function createApiCommands(name = 'api'): Command {
   const cmd = new Command(name);
   cmd.description('AI-powered API testing tool');
 
-  addCommonOptions(cmd.command('plan <endpoint>').description('Generate test plan for an API endpoint').option('--style <style>', 'Planning style: basename of a file in rules/chief/styles/').option('--fresh', 'Start planning from scratch')).action(async (endpoint, options) => {
-    setPreserveConsoleLogs(true);
-    try {
-      const bot = new ApiBot({ ...buildOptions(options), endpoint });
-      await bot.start();
-
-      await bot.plan(endpoint, { style: options.style, fresh: options.fresh });
-
-      const plan = bot.getCurrentPlan();
-      if (!plan?.tests.length) {
-        console.error('No test scenarios generated.');
-        process.exit(1);
-      }
-
-      console.log(`\nPlan: ${plan.title} (${plan.tests.length} tests)\n`);
-      plan.tests.forEach((test, i) => {
-        console.log(`  ${i + 1}. [${test.priority}] ${test.scenario}`);
+  addCommonOptions(cmd.command('plan <endpoint>').description('Generate test plan for an API endpoint'))
+    .option('--style <style>', 'Planning style: basename of a file in rules/chief/styles/')
+    .option('--fresh', 'Start planning from scratch')
+    .action(async (endpoint, options) => {
+      await run(name, options, endpoint, async (bot) => {
+        const command = new PlanCommand(bot);
+        command.prefix = name;
+        command.style = options.style;
+        command.fresh = !!options.fresh;
+        await command.execute(endpoint);
+        return 0;
       });
-
-      const savedPath = bot.savePlan();
-      if (savedPath) {
-        console.log(`\nSaved to: ${savedPath}`);
-        console.log('\nRun tests:');
-        console.log(`  ${name} test ${savedPath} 1       # run first test`);
-        console.log(`  ${name} test ${savedPath} 1-3     # run tests 1 to 3`);
-        console.log(`  ${name} test ${savedPath} *       # run all tests`);
-      }
-
-      await bot.stop();
-      process.exit(0);
-    } catch (error) {
-      console.error('Failed:', error instanceof Error ? error.message : 'Unknown error');
-      process.exit(1);
-    }
-  });
+    });
 
   addCommonOptions(cmd.command('config [endpoint]').description('Show models, config file and paths used by this run'))
     .option('--json', 'Print the resolved config as JSON')
@@ -116,87 +49,22 @@ export function createApiCommands(name = 'api'): Command {
   RecommendedModelsCommand.register(cmd);
 
   addCommonOptions(cmd.command('test <planfile> [index]').description('Execute tests from a plan file. Index: 1, 1-3, *')).action(async (planfile, index, options) => {
-    setPreserveConsoleLogs(true);
-    try {
-      const bot = new ApiBot(buildOptions(options));
-      await bot.start();
-
-      const plan = bot.loadPlan(planfile);
-      console.log(`Plan loaded: "${plan.title}" (${plan.tests.length} tests)`);
-
-      const tests = selectTests(plan.tests, index);
-      console.log(`Running ${tests.length} test(s)\n`);
-
-      let passed = 0;
-      let failed = 0;
-
-      for (const test of tests) {
-        const specDefinition = bot.tryGetEndpointDefinition(test.startUrl);
-        const result = await bot.agentCurler().test(test, {
-          specDefinition,
-          baseEndpoint: bot.getConfig().api.baseEndpoint,
-          searchSpec: (query) => bot.searchSpec(query),
-        });
-        if (result.success) passed++;
-        else failed++;
-      }
-
-      bot.savePlan();
-
-      console.log(`\nResults: ${passed} passed, ${failed} failed out of ${tests.length}`);
-      await bot.stop();
-      process.exit(failed > 0 ? 1 : 0);
-    } catch (error) {
-      console.error('Failed:', error instanceof Error ? error.message : 'Unknown error');
-      process.exit(1);
-    }
+    await run(name, options, undefined, async (bot) => {
+      const command = new TestCommand(bot);
+      command.index = index;
+      await command.execute(planfile);
+      if (command.failed) return 1;
+      return 0;
+    });
   });
 
-  addCommonOptions(cmd.command('explore <endpoint>').description('Full cycle: plan all styles, execute tests, re-plan. The endpoint may be the base endpoint itself')).action(async (endpoint, options) => {
-    setPreserveConsoleLogs(true);
-    try {
-      if (URL.canParse(endpoint)) options.endpoint ||= endpoint;
-      const bot = new ApiBot({ ...buildOptions(options), endpoint });
-      await bot.start();
-
-      const styles = Object.keys(getStyles());
-      let totalPassed = 0;
-      let totalFailed = 0;
-      let totalTests = 0;
-
-      for (const style of styles) {
-        console.log(`\n=== Style: ${style} ===\n`);
-
-        const plan = await bot.plan(endpoint, { style, fresh: true });
-        if (!plan?.tests.length) {
-          console.log(`No tests generated for style: ${style}`);
-          continue;
-        }
-
-        const pending = plan.getPendingTests();
-        for (const test of pending) {
-          const specDefinition = bot.tryGetEndpointDefinition(test.startUrl);
-          const result = await bot.agentCurler().test(test, {
-            specDefinition,
-            baseEndpoint: bot.getConfig().api.baseEndpoint,
-            searchSpec: (query) => bot.searchSpec(query),
-          });
-          totalTests++;
-          if (result.success) totalPassed++;
-          else totalFailed++;
-        }
-
-        bot.savePlan(style);
-      }
-
-      console.log('\n=== Final Results ===');
-      console.log(`Total: ${totalTests} tests, ${totalPassed} passed, ${totalFailed} failed`);
-      await bot.stop();
-      process.exit(totalFailed > 0 ? 1 : 0);
-    } catch (error) {
-      console.error('Failed:', error instanceof Error ? error.message : 'Unknown error');
-      process.exit(1);
-    }
+  addCommonOptions(cmd.command('explore <endpoint>').description('Full cycle: plan, execute tests, re-plan. Use * to cover many endpoints, or the base endpoint for all of them')).action(async (endpoint, options) => {
+    await run(name, options, endpoint, async (bot) => {
+      const command = new ExploreCommand(bot);
+      await command.execute(endpoint);
+      if (command.result.failed) return 1;
+      return 0;
+    });
   });
 
   cmd
@@ -204,87 +72,11 @@ export function createApiCommands(name = 'api'): Command {
     .description('Initialize a new apibot project with configuration')
     .option('-f, --force', 'Overwrite existing config file')
     .option('-p, --path <path>', 'Working directory for initialization')
+    .option('--provider <name>', 'AI provider written into the config')
+    .option('--endpoint <url>', 'Base API endpoint, with --spec skips the questions')
+    .option('--spec <path>', 'OpenAPI spec file or URL')
     .action(async (options) => {
-      const originalCwd = process.cwd();
-      if (options.path) {
-        const resolvedPath = path.resolve(options.path);
-        fs.mkdirSync(resolvedPath, { recursive: true });
-        process.chdir(resolvedPath);
-        console.log(`Working in: ${resolvedPath}`);
-      }
-
-      const configPath = path.resolve('apibot.config.ts');
-
-      if (fs.existsSync(configPath) && !options.force) {
-        console.log(`Config file already exists: ${configPath}`);
-        console.log('Use --force to overwrite.');
-        process.exit(1);
-      }
-
-      const rl = await import('node:readline');
-      const iface = rl.createInterface({ input: process.stdin, output: process.stdout });
-      const ask = (q: string, fallback = ''): Promise<string> => new Promise((resolve) => iface.question(q, (a: string) => resolve(a.trim() || fallback)));
-
-      console.log('Apibot — API Testing Tool Setup\n');
-
-      const baseEndpoint = await ask('Base API endpoint (e.g., https://api.example.com/v1): ');
-      if (!baseEndpoint) {
-        console.error('Base endpoint is required.');
-        iface.close();
-        process.exit(1);
-      }
-
-      const spec = await ask('OpenAPI spec file or URL (e.g., openapi.yaml or https://.../ — or press Enter to skip): ');
-      const knowledge = await ask('Describe your API (auth method, data formats, special rules — or press Enter to skip): ');
-
-      iface.close();
-
-      const specLine = spec ? `\n    spec: ['${spec}'],` : '';
-
-      const configContent = `import { openai } from '@ai-sdk/openai';
-
-export default {
-  ai: {
-    model: openai('gpt-4o'),
-  },
-  api: {
-    baseEndpoint: '${baseEndpoint}',${specLine}
-    headers: {
-      // 'Authorization': 'Bearer <token>',
-    },
-    // bootstrap: async ({ headers, baseEndpoint }) => {
-    //   // Run before tests — e.g. obtain auth token
-    //   // Return headers to merge: { Authorization: 'Bearer ...' }
-    // },
-    // teardown: async ({ headers, baseEndpoint }) => {
-    //   // Run after tests — e.g. cleanup test data
-    // },
-  },
-  dirs: {
-    output: 'output',
-    knowledge: 'knowledge',
-  },
-};
-`;
-
-      fs.writeFileSync(configPath, configContent, 'utf8');
-      console.log(`\nCreated: ${configPath}`);
-
-      fs.mkdirSync('output', { recursive: true });
-      fs.mkdirSync('knowledge', { recursive: true });
-
-      if (knowledge) {
-        const knowledgePath = path.resolve('knowledge', 'general.md');
-        fs.writeFileSync(knowledgePath, `---\nendpoint: "*"\n---\n${knowledge}\n`, 'utf8');
-        console.log(`Created: ${knowledgePath}`);
-      }
-
-      console.log('\nNext steps:');
-      console.log('1. Edit apibot.config.ts — set your AI provider and API headers');
-      console.log(`2. Add API knowledge: ${name} know /users "CRUD endpoint for user management"`);
-      console.log(`3. Plan tests: ${name} plan /users`);
-
-      if (process.cwd() !== originalCwd) process.chdir(originalCwd);
+      await runInit({ ...options, baseEndpoint: options.endpoint, prefix: name });
     });
 
   cmd
@@ -294,42 +86,61 @@ export default {
     .option('-c, --config <path>', 'Path to configuration file')
     .option('-p, --path <path>', 'Working directory path')
     .action(async (endpoint, description, options) => {
-      if (!description) {
-        const rl = await import('node:readline');
-        const iface = rl.createInterface({ input: process.stdin, output: process.stdout });
-        description = await new Promise<string>((resolve) => iface.question(`Describe ${endpoint}: `, (a: string) => resolve(a.trim())));
-        iface.close();
-      }
-
-      if (!description) {
-        console.error('Description is required.');
-        process.exit(1);
-      }
-
-      let knowledgeDir = 'knowledge';
+      const command = new KnowCommand(new ApiBot(buildOptions(options)));
+      command.prefix = name;
+      command.knowledge = description || (await askDescription(endpoint));
       try {
-        const { ApibotConfigParser } = await import('./config.ts');
-        await ApibotConfigParser.getInstance().loadConfig({ config: options.config, path: options.path });
-        knowledgeDir = ApibotConfigParser.getInstance().getKnowledgeDir();
-      } catch {
-        if (options.path) knowledgeDir = path.join(path.resolve(options.path), 'knowledge');
+        await command.execute(endpoint);
+      } catch (error) {
+        console.error(error instanceof Error ? error.message : 'Unknown error');
+        process.exit(1);
       }
+    });
 
-      fs.mkdirSync(knowledgeDir, { recursive: true });
+  return cmd;
+}
 
-      const filename = endpoint.replace(/^\//, '').replace(/[^a-zA-Z0-9]/g, '_') || 'general';
-      const filePath = path.join(knowledgeDir, `${filename}.md`);
+async function run(name: string, options: any, endpoint: string | undefined, body: (bot: ApiBot) => Promise<number>): Promise<void> {
+  setPreserveConsoleLogs(true);
+  try {
+    if (endpoint && URL.canParse(endpoint)) options.endpoint ||= endpoint;
+    const bot = new ApiBot({ ...buildOptions(options), endpoint });
+    await bot.start();
+    const code = await body(bot);
+    await bot.stop();
+    process.exit(code);
+  } catch (error) {
+    console.error('Failed:', error instanceof Error ? error.message : 'Unknown error');
+    process.exit(1);
+  }
+}
 
-      const content = `---\nendpoint: "${endpoint}"\n---\n${description}\n`;
+async function askDescription(endpoint: string): Promise<string> {
+  const rl = await import('node:readline');
+  const iface = rl.createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await new Promise<string>((resolve) => iface.question(`Describe ${endpoint}: `, (text: string) => resolve(text.trim())));
+  iface.close();
+  return answer;
+}
 
-      if (fs.existsSync(filePath)) {
-        fs.appendFileSync(filePath, `\n---\n${description}\n`, 'utf8');
-        console.log(`Updated: ${filePath}`);
-      } else {
-        fs.writeFileSync(filePath, content, 'utf8');
-        console.log(`Created: ${filePath}`);
-      }
-    });
+function buildOptions(options: any): ApibotOptions {
+  return {
+    verbose: options.verbose || options.debug,
+    config: options.config,
+    path: options.path,
+    baseEndpoint: options.endpoint,
+    spec: options.spec,
+    header: options.header,
+  };
+}
 
-  return cmd;
+function addCommonOptions(cmd: Command): Command {
+  return cmd
+    .option('-v, --verbose', 'Enable verbose logging')
+    .option('--debug', 'Enable debug logging')
+    .option('-c, --config <path>', 'Path to configuration file')
+    .option('-p, --path <path>', 'Working directory path')
+    .option('--endpoint <url>', 'Base API endpoint to test (env: EXPLORBOT_URL)')
+    .option('--spec <path>', 'OpenAPI spec file or URL (env: EXPLORBOT_API_SPEC)')
+    .option('-H, --header <header>', 'Header sent with every request, as "Name: value". Repeatable (env: EXPLORBOT_API_HEADERS)', (value: string, previous: string[] = []) => [...previous, value]);
 }

package/boat/api-tester/src/commands/api-command.ts

@@ -0,0 +1,10 @@
+import { BaseCommand } from '../../../../src/commands/base-command.ts';
+import type { ApiBot } from '../apibot.ts';
+
+export abstract class ApiCommand extends BaseCommand<ApiBot> {
+  prefix = 'apibot';
+
+  protected get bot(): ApiBot {
+    return this.explorBot;
+  }
+}

package/boat/api-tester/src/commands/explore-command.ts

@@ -0,0 +1,52 @@
+import figureSet from 'figures';
+import { tag } from '../../../../src/utils/logger.ts';
+import { getStyles } from '../ai/chief/styles.ts';
+import { ApiCommand } from './api-command.ts';
+
+export class ExploreCommand extends ApiCommand {
+  name = 'explore';
+  description = 'Full cycle: plan, execute tests, re-plan. Use * to cover many endpoints, or the base endpoint for all of them';
+  result: ExploreResult = { tests: 0, passed: 0, failed: 0 };
+
+  async execute(endpoint: string): Promise<void> {
+    const styles = Object.keys(getStyles());
+    const endpoints = this.bot.expandEndpoints(endpoint);
+
+    for (const [index, target] of endpoints.entries()) {
+      let runStyles = [styles[index % styles.length]];
+      if (endpoints.length === 1) runStyles = styles;
+      if (endpoints.length > 1) tag('info').log(`Endpoint ${index + 1}/${endpoints.length}: ${target}`);
+
+      for (const style of runStyles) {
+        await this.runStyle(target, style);
+      }
+    }
+
+    tag('info').log(`${figureSet.tick} ${this.result.tests} tests completed: ${this.result.passed} passed, ${this.result.failed} failed`);
+  }
+
+  private async runStyle(endpoint: string, style: string): Promise<void> {
+    tag('info').log(`Planning style: ${style}`);
+
+    const plan = await this.bot.plan(endpoint, { style, fresh: true });
+    if (!plan?.tests.length) {
+      tag('warning').log(`No tests generated for style: ${style}`);
+      return;
+    }
+
+    for (const test of plan.getPendingTests()) {
+      const outcome = await this.bot.runTest(test);
+      this.result.tests++;
+      if (outcome.success) this.result.passed++;
+      else this.result.failed++;
+    }
+
+    this.bot.savePlan(style);
+  }
+}
+
+export interface ExploreResult {
+  tests: number;
+  passed: number;
+  failed: number;
+}

package/boat/api-tester/src/commands/init-command.ts

@@ -0,0 +1,119 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import chalk from 'chalk';
+import { envTemplate, modelLines } from '../../../../src/commands/init-command.ts';
+import { missingModelRoles } from '../../../../src/config.ts';
+import { log, tag } from '../../../../src/utils/logger.ts';
+
+export async function runInit(options: InitOptions): Promise<void> {
+  const provider = options.provider || 'openrouter';
+  const originalCwd = process.cwd();
+
+  if (options.path) {
+    const dir = path.resolve(options.path);
+    mkdirSync(dir, { recursive: true });
+    process.chdir(dir);
+    log(`Working in directory: ${dir}`);
+  }
+
+  const configPath = path.resolve('apibot.config.js');
+  if (existsSync(configPath) && !options.force) {
+    log(`Config file already exists: ${configPath}`);
+    log('Use --force to overwrite existing file');
+    process.exit(1);
+  }
+
+  const answers = await ask(options);
+  if (!answers.baseEndpoint) {
+    tag('error').log('Base endpoint is required.');
+    process.exit(1);
+  }
+
+  if (!answers.spec) {
+    tag('error').log('OpenAPI spec is required. Chief plans from it and Curler looks up schemas in it.');
+    process.exit(1);
+  }
+
+  writeFileSync(configPath, configTemplate(provider, answers.baseEndpoint, answers.spec), 'utf8');
+  log(`Created config file: ${configPath}`);
+
+  const envPath = path.resolve('.env');
+  if (!existsSync(envPath)) {
+    writeFileSync(envPath, `${envTemplate(provider)}\n`, 'utf8');
+    log(`Created env file: ${envPath}`);
+  }
+
+  mkdirSync('output', { recursive: true });
+  mkdirSync('knowledge', { recursive: true });
+
+  if (answers.knowledge) {
+    const knowledgePath = path.resolve('knowledge', 'general.md');
+    writeFileSync(knowledgePath, `---\nendpoint: "*"\n---\n${answers.knowledge}\n`, 'utf8');
+    log(`Created knowledge file: ${knowledgePath}`);
+  }
+
+  const missing = missingModelRoles(provider);
+  if (missing.length) {
+    tag('warning').log(`No recommended ${missing.join(' and ')} for ${provider} — set the model ids in ${configPath}`);
+  }
+
+  log('');
+  log('Next steps:');
+  log('1. Add your provider API key to .env');
+  log('2. Describe the API so the plans match it');
+  tag('substep').log(chalk.yellow(`${options.prefix} know /users "CRUD endpoint for user management"`));
+  log('3. Plan and run tests for one endpoint');
+  tag('substep').log(chalk.yellow(`${options.prefix} explore /users`));
+
+  if (process.cwd() !== originalCwd) process.chdir(originalCwd);
+}
+
+function configTemplate(provider: string, baseEndpoint: string, spec: string): string {
+  return `// Models are written as 'provider/model-id' so they resolve without a local node_modules.
+// https://github.com/testomatio/explorbot/blob/main/docs/basics/providers.md
+
+export default {
+  ai: {
+${modelLines(provider, ['model', 'agenticModel'])}
+  },
+
+  api: {
+    baseEndpoint: '${baseEndpoint}',
+    spec: ['${spec}'],
+  },
+};
+`;
+}
+
+async function ask(options: InitOptions): Promise<Answers> {
+  if (options.baseEndpoint) {
+    return { baseEndpoint: options.baseEndpoint, spec: options.spec || '', knowledge: '' };
+  }
+
+  const rl = await import('node:readline');
+  const iface = rl.createInterface({ input: process.stdin, output: process.stdout });
+  const question = (text: string): Promise<string> => new Promise((resolve) => iface.question(text, (answer: string) => resolve(answer.trim())));
+
+  log('Apibot — API Testing Tool Setup\n');
+  const baseEndpoint = await question('Base API endpoint (e.g. https://api.example.com/v1): ');
+  const spec = await question('OpenAPI spec file or URL: ');
+  const knowledge = await question('Describe your API, its auth and its rules (Enter to skip): ');
+  iface.close();
+
+  return { baseEndpoint, spec, knowledge };
+}
+
+interface InitOptions {
+  force?: boolean;
+  path?: string;
+  provider?: string;
+  baseEndpoint?: string;
+  spec?: string;
+  prefix: string;
+}
+
+interface Answers {
+  baseEndpoint: string;
+  spec: string;
+  knowledge: string;
+}

package/boat/api-tester/src/commands/know-command.ts

@@ -0,0 +1,44 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { tag } from '../../../../src/utils/logger.ts';
+import { ApiCommand } from './api-command.ts';
+
+export class KnowCommand extends ApiCommand {
+  name = 'know';
+  aliases = ['add-knowledge'];
+  description = 'Add API knowledge for an endpoint';
+  knowledge = '';
+
+  async execute(endpoint: string): Promise<void> {
+    if (!this.knowledge) {
+      throw new Error('Description is required.');
+    }
+
+    const knowledgeDir = await this.resolveKnowledgeDir();
+    fs.mkdirSync(knowledgeDir, { recursive: true });
+
+    const filename = endpoint.replace(/^\//, '').replace(/[^a-zA-Z0-9]/g, '_') || 'general';
+    const filePath = path.join(knowledgeDir, `${filename}.md`);
+
+    if (fs.existsSync(filePath)) {
+      fs.appendFileSync(filePath, `\n---\n${this.knowledge}\n`, 'utf8');
+      tag('success').log(`Updated: ${filePath}`);
+      return;
+    }
+
+    fs.writeFileSync(filePath, `---\nendpoint: "${endpoint}"\n---\n${this.knowledge}\n`, 'utf8');
+    tag('success').log(`Created: ${filePath}`);
+  }
+
+  private async resolveKnowledgeDir(): Promise<string> {
+    const parser = this.bot.getConfigParser();
+    const options = this.bot.getOptions();
+    try {
+      await parser.loadConfig(options);
+      return parser.getKnowledgeDir();
+    } catch {
+      if (options.path) return path.join(path.resolve(options.path), 'knowledge');
+      return 'knowledge';
+    }
+  }
+}