vibe-tools

vibe-tools requires API keys for Perplexity AI and Google Gemini. It also supports optional keys for OpenAI, Anthropic, OpenRouter, xAI, Groq, GitHub, and Linear.

There are two primary ways to configure these keys:

1. Interactive Setup: Run vibe-tools install and follow the command-line prompts.
2. Manual Setup: Create a .env file in one of the following locations:
   • ~/.vibe-tools/.env (Home directory)
   • .vibe-tools.env (Project root)

Note for MCP users: To use mcp commands, you must provide at least one of ANTHROPIC_API_KEY or OPENROUTER_API_KEY.

CI/CD Environments: In non-interactive mode (automatically detected in CI), vibe-tools uses environment variables exclusively and will not write to the filesystem.

PERPLEXITY_API_KEY="your-perplexity-api-key"
GEMINI_API_KEY="your-gemini-api-key"
OPENAI_API_KEY="your-openai-api-key"  # Optional, for Stagehand
ANTHROPIC_API_KEY="your-anthropic-api-key" # Optional, for Stagehand and MCP
OPENROUTER_API_KEY="your-openrouter-api-key" # Optional, for MCP
XAI_API_KEY="your-xai-api-key" # Optional, for xAI Grok models
GROQ_API_KEY="your-groq-api-key" # Optional, for Groq models
GITHUB_TOKEN="your-github-token"  # Optional, for enhanced GitHub access
LINEAR_API_KEY="your-linear-api-key" # Optional, for Linear integration

Generate comprehensive documentation for local or remote GitHub repositories. You can include external web documentation as additional context to improve accuracy.

Key Flags:

• --save-to=<file>: Save the generated documentation to a specific file.
• --from-github=<user/repo>[@branch]: Specify the target GitHub repository and optional branch.
• --with-doc=<url>: Add a web URL as additional context for the documentation generation.
• --hint="<text>": Provide a hint to guide the documentation generation.
• --quiet: Run without verbose output.

# Document local repository and save to file
vibe-tools doc --save-to=docs.md

# Document remote GitHub repository
vibe-tools doc --from-github=username/repo-name@branch

# Document with additional web documentation as context
vibe-tools doc --from-github=reactjs/react-redux --with-doc=https://redux.js.org/tutorials/fundamentals/part-5-ui-and-react --save-to=docs/REACT_REDUX.md

Feature behavior files are written in Markdown and define the test scenarios for vibe-tools commands. They must follow this structure:

1. Feature Behavior: The name of the feature.
2. Description: A summary of what the test verifies.
3. Test Scenarios: A list of specific test cases, each containing:
   • Scenario: The name of the test case.
   • Task Description: Instructions for what the AI agent should do.
   • Expected Behavior: A description of the expected outcome.
   • Success Criteria: Specific, measurable criteria for a successful test.

# Feature Behavior: Web Command

## Description

This test verifies that the web command can query online information correctly.

## Test Scenarios

### Scenario 1: Basic Web Query

**Task Description:**
Use vibe-tools to search for information about climate change.

**Expected Behavior:**

- The AI agent should use the web command
- Response should include information about climate change
- The command should complete successfully

**Success Criteria:**

- AI agent correctly uses the vibe-tools web command
- Response contains relevant information about climate change
- Command completes without errors

To implement scenario-level isolation, wrap the executeScenario logic with TestEnvironmentManager. This ensures each scenario runs in its own temporary directory with its required assets copied in, preventing cross-test contamination.

Workflow:

1. Call TestEnvironmentManager.createTempDirectory(scenarioId).
2. Call TestEnvironmentManager.copyAssets(scenario, tempDir) to get a modifiedTaskDescription.
3. Initialize tools (like createCommandExecutionTool) using the tempDir as the cwd.
4. Execute the scenario using the modifiedScenario.
5. Use a finally block to call TestEnvironmentManager.cleanup(tempDir).

// Inside executeScenario implementation
const tempDir = await TestEnvironmentManager.createTempDirectory(scenarioId);
const modifiedTaskDescription = await TestEnvironmentManager.copyAssets(scenario, tempDir);

const modifiedScenario = {
  ...scenario,
  taskDescription: modifiedTaskDescription
};

try {
  const tools = [
    createCommandExecutionTool({
      debug,
      cwd: tempDir,
      scenarioId,
      appendToBuffer
    })
  ];
  // ... execution logic
} finally {
  await TestEnvironmentManager.cleanup(tempDir);
}