# Command Line Parameters

This document describes the command line parameters available for `kbot`.

**Note:** Many parameters support environment variable substitution (e.g., `${VAR_NAME}`).

## Core Parameters

| Parameter | Description | Default | Required |
|-----------|-------------|---------|----------|
| `prompt`  | The main instruction or question for the AI. Can be a string, a file path (e.g., `file:./my_prompt.md`), or an environment variable. | - | Yes (or implied by context) |
| `model`   | AI model ID to use for processing (e.g., `openai/gpt-4o`). See available models via helper functions or router documentation. | Depends on router/config | No |
| `router`  | The API provider to use. | `openrouter` | No |
| `mode`    | The operational mode. See [Modes](./modes.md) for details. | `tools` | No |

## Input & File Selection

| Parameter | Description | Default | Required |
|-----------|-------------|---------|----------|
| `path`    | Target directory for local file operations or context. | `.` | No |
| `include` | Specify input files or content. Accepts comma-separated glob patterns (e.g., `src/**/*.ts`), file paths, directory paths, or **web URLs** (e.g., `https://example.com/page`). | `[]` | No |
| `exclude` | Comma-separated glob patterns or paths to exclude from processing (e.g., `src/**/*.test.ts,temp/`). | `[]` | No |
| `globExtension` | Specify a glob extension behavior to find related files. Available presets: `match-cpp`. Also accepts a custom glob pattern with variables like `${SRC_DIR}`, `${SRC_NAME}`, `${SRC_EXT}` (e.g., `"${SRC_DIR}/${SRC_NAME}*.h"` to find headers for a .cpp file). | - | No |
| `query`   | JSONPath query to extract specific data from input objects (often used with structured input files). | `null` | No |

## Output & Formatting

| Parameter | Description | Default | Required |
|-----------|-------------|---------|----------|
| `output`  | Output path for modified files (primarily for `tools` mode operations like refactoring). | - | No |
| `dst`     | Destination path/filename for the main result (primarily for `completion` or `assistant` mode). Supports `${MODEL_NAME}` and `${ROUTER}` substitutions. | - | No |
| `format`  | Defines the desired structure for the AI's output. Can be a Zod schema object, a Zod schema string, a JSON schema string, or a path to a JSON schema file (e.g., `file:./schema.json`). Ensures the output conforms to the specified structure. | - | No |
| `filters` | Post-processing filters applied to the output (primarily `completion` mode with `--dst`). Can be a comma-separated string of filter names (e.g., `unwrapMarkdown,trim`). | `''` | No |

## Tool Usage

| Parameter | Description | Default | Required |
|-----------|-------------|---------|----------|
| `tools`   | Comma-separated list of tool names or paths to custom tool files to enable. | (List of default tools) | No |
| `disable` | Comma-separated list of tool *categories* to disable (e.g., `filesystem,git`). | `[]` | No |
| `disableTools` | Comma-separated list of specific tool *names* to disable. | `[]` | No |

## Iteration & Advanced Control

| Parameter | Description | Default | Required |
|-----------|-------------|---------|----------|
| `each`    | Iterate the task over multiple items. Accepts a GLOB pattern, path to a JSON file (array), or comma-separated strings. The current item is available as the `${ITEM}` variable in other parameters (e.g., `--dst="${ITEM}-output.md"`). Can be used to test different models (e.g., `--each="openai/gpt-3.5-turbo,openai/gpt-4o"`). | - | No |
| `variables` | Define custom key-value variables for use in prompts or other parameters (e.g., `--variables.PROJECT_NAME=MyProject`). Access via `${variableName}`. | `{}` | No |

## Configuration & Authentication

| Parameter | Description | Default | Required |
|-----------|-------------|---------|----------|
| `api_key` | Explicit API key for the selected router. Overrides keys from config files. | - | No |
| `baseURL` | Custom base URL for the API endpoint (e.g., for local LLMs via Ollama). Set automatically for known routers or can be specified directly. | - | No |
| `config`  | Path to a JSON configuration file containing API keys and potentially other settings. | - | No |
| `profile` | Path to a profile file (JSON or .env format) for loading environment-specific variables. | - | No |
| `env`     | Specifies the environment section to use within the profile file. | `default` | No |
| `preferences` | Path to a preferences file (e.g., containing user details like location, email). Used to provide context to the AI. | (System-specific default, often `~/.kbot/Preferences`) | No |

## Debugging & Logging

| Parameter | Description | Default | Required |
|-----------|-------------|---------|----------|
| `logLevel` | Logging verbosity level (e.g., 0=error, 4=debug). | `4` | No |
| `logs`    | Directory to store log files and temporary outputs (like `params.json`). | `./logs` | No |
| `dry`     | Perform a dry run: log parameters and configurations without executing the AI request. | `false` | No |
| `dump`    | Path to generate a script file representing the current command invocation. | - | No |