# CLI Examples

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

## Basic Modifications

Modify project files based on a prompt:

```bash
# 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:

```bash
# 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:

```bash
# 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.

```bash
# 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.

```bash
# 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.

```bash
# 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.

```bash
# 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.

```bash
# 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.

```bash
# 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.