mono/packages/kbot/docs_/examples.md

CLI Examples

This page shows various ways to use kbot from the command line.

Basic Modifications

Modify project files based on a prompt:

# Request a change in the current directory context
kbot "Add comprehensive error handling to all API route handlers"

# Use stdin for the prompt
echo "Refactor the database connection logic into a reusable module" | kbot

# Use a file containing the prompt
kbot --prompt ./prompts/refactor_request.md

# Specify target files using glob patterns
kbot --include "src/controllers/**/*.ts" "Ensure all controller methods return consistent JSON responses"

# Target specific files
kbot --include "src/utils/auth.ts,src/middleware/auth.js" "Update authentication logic to support JWT refresh tokens"

Working with Different Input Sources

kbot can process various types of input specified via the --include parameter:

# Include local files and directories
kbot --include "./docs/api.md,./src/server.ts" "Update the API documentation based on the server code"

# Include content from a web URL
kbot --include "https://raw.githubusercontent.com/user/repo/main/README.md" "Summarize this project's README"

# Combine different sources
kbot --include "./config.yaml,https://example.com/api/spec.json" "Generate documentation based on the config and the API spec"

Advanced Data Transformation & Iteration

These examples demonstrate more complex scenarios involving data processing, structured output, and iteration.

Transforming Data with the Iterator Factory

The iterator-factory-example.ts demonstrates advanced usage including transforming specific fields within complex JSON objects, handling arrays, caching results, and generating structured output using the --format option.

To run this example:

# Ensure dependencies are installed, then run:
npm run examples:iterator-factory

# Run without caching:
npm run examples:iterator-factory -- --no-cache

This example uses the createIterator function for fine-grained control. Explore the code in src/examples/core/iterator-factory-example.ts for details.

Structured Output with --format

Force the AI to return data in a specific JSON structure. You can provide the schema as a JSON string, a file path, or a Zod schema string.

# Using a JSON schema file
kbot --include ./product_review.txt \
     --format file:./schemas/review_analysis_schema.json \
     "Analyze this review and extract sentiment, pros, and cons according to the schema"

# Using an inline JSON schema string
kbot --include ./data.json \
     --format '{"type":"object","properties":{"summary":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}}},"required":["summary","keywords"]}' \
     "Summarize this data and extract keywords"

Iterating with --each

Process multiple items (files, models, strings) in sequence.

# Iterate over specific files and output to separate files
kbot --each "./src/moduleA.ts,./src/moduleB.ts" \
     --dst "./docs/${ITEM}.md" \
     "Generate documentation for the module defined in ${ITEM}"

# Test a prompt against multiple models
kbot --each "openai/gpt-4o,anthropic/claude-3-sonnet" \
     --include ./my_code.py \
     --dst "${ITEM}_review.txt" \
     "Review this Python code for potential bugs and suggest improvements"

# Iterate over files matching a glob pattern
kbot --each "./tests/**/*.test.js" \
     --dst "./coverage/${ITEM}.txt" \
     "Analyze the test coverage for ${ITEM}"

Configuration and Control

Using Profiles and Environments

Load variables from configuration files for different environments.

# Load variables from a profile and specify an environment
kbot --profile ./config/profiles.json --env staging "Deploy the staging configuration using variables from the profile"

Custom Output Paths

Control where results are saved.

# Save modifications to a different directory (tool mode)
kbot --output ./refactored_code "Refactor all functions to use async/await"

# Save completion result to a specific file (completion mode)
kbot --mode completion --dst ./summary.md "Summarize the included documents"

Model and Router Selection

Choose the AI provider and specific model.

# Use a specific OpenAI model
kbot --router openai --model gpt-4o "Translate the included text to French"

# Use a model via OpenRouter (default router)
kbot --model anthropic/claude-3.5-sonnet "Write a poem about the included text"

Tool Control

Enable or disable specific tools or categories.

# Disable the 'git' category tools
kbot --disable git "Update code documentation without committing changes"

# Disable specific tools by name
kbot --disableTools "npm_install,file_save" "Analyze dependencies but do not install or save files"

More Examples

For more in-depth examples demonstrating various features like custom tools, different modes, and advanced configurations, please explore the code within the src/examples/ directory of this package.