@crownpeak/dqm-react-component-dev-mcp 1.2.0

package/data/probe/site/cli-mode.md

@@ -0,0 +1,437 @@
+# CLI Reference (Commands & Flags)
+
+Complete reference documentation for all Probe command-line interface commands, options, and usage examples.
+
+## Search Command
+
+Find code across your entire codebase:
+
+```bash
+probe search <QUERY> [PATH] [OPTIONS]
+```
+
+### Core Options
+
+| Option | Function |
+|--------|----------|
+| `<QUERY>` | **Required**: What to search for |
+| `[PATH]` | Where to search (default: current directory) |
+| `--files-only` | List matching files without code blocks |
+| `--ignore <PATTERN>` | Additional patterns to ignore |
+| `--exclude-filenames, -n` | Exclude filenames from matching |
+| `--reranker, -r <TYPE>` | Algorithm: `hybrid`, `hybrid2`, `bm25`, `tfidf` |
+| `--frequency, -s` | Enable smart token matching (default) |
+| `--max-results <N>` | Limit number of results |
+| `--max-bytes <N>` | Limit total bytes of code |
+| `--max-tokens <N>` | Limit total tokens (for AI) |
+| `--allow-tests` | Include test files and code |
+| `--any-term` | Match any search term (OR logic) |
+| `--no-merge` | Keep code blocks separate |
+| `--merge-threshold <N>` | Max lines between blocks to merge (default: 5) |
+| `--session <ID>` | Session ID for caching results |
+| `-o, --format <TYPE>` | Output as: `color` (default), `terminal`, `markdown`, `plain`, `json`, `xml` |
+
+### Command Examples
+
+```bash
+# Basic search - current directory
+probe search "authentication flow"
+
+# Search in specific folder
+probe search "updateUser" ./src/api
+
+# Limit for AI context windows
+probe search "error handling" --max-tokens 8000
+
+# Find raw files without parsing
+probe search "config" --files-only
+
+# Elastic search queries
+# Use AND operator for terms that must appear together
+probe search "error AND handling" ./
+
+# Use OR operator for alternative terms
+probe search "login OR authentication OR auth" ./src
+
+# Group terms with parentheses for complex queries
+probe search "(error OR exception) AND (handle OR process)" ./
+
+# Use wildcards for partial matching
+probe search "auth* connect*" ./
+
+# Exclude terms with NOT operator
+probe search "database NOT sqlite" ./
+
+# Use search hints to filter by file properties
+probe search "function AND ext:rs" ./          # Only search in .rs files
+probe search "class AND file:src/**/*.py" ./   # Only search in Python files under src/
+probe search "error AND dir:tests" ./          # Only search in files under tests/ directory
+probe search "struct AND type:rust" ./         # Only search in Rust files
+probe search "component AND lang:javascript" ./ # Only search in JavaScript files
+
+# Output as JSON for programmatic use
+probe search "authentication" --format json
+
+# Output as XML
+probe search "authentication" --format xml
+```
+
+### Search Hints
+
+Filter search results by file properties using search hints. These filters are applied at the file discovery stage:
+
+| Hint | Description | Examples |
+|------|-------------|----------|
+| `ext:<extension>` | Filter by file extension | `ext:rs`, `ext:py,js,ts` |
+| `file:<pattern>` | Filter by file path pattern (supports globs) | `file:src/**/*.rs`, `file:*test*` |
+| `path:<pattern>` | Alias for `file:` | `path:src/main.rs` |
+| `dir:<pattern>` | Filter by directory pattern | `dir:src`, `dir:tests` |
+| `type:<filetype>` | Filter by ripgrep file type | `type:rust`, `type:javascript` |
+| `lang:<language>` | Filter by programming language | `lang:rust`, `lang:python` |
+
+**Search Hint Examples:**
+
+```bash
+# Search for "function" only in Rust files
+probe search "function AND ext:rs" ./
+
+# Search for "config" in source files with multiple extensions
+probe search "config AND ext:rs,py,js" ./src
+
+# Complex search with multiple filters
+probe search "(error OR exception) AND ext:rs AND dir:src" ./
+
+# Search in test directories only
+probe search "assert AND dir:tests" ./
+```
+
+## Extract Command
+
+Pull complete code blocks from specific files and lines:
+
+```bash
+probe extract <FILES> [OPTIONS]
+```
+
+### Extract Options
+| Option | Function |
+|--------|----------|
+| `<FILES>` | Files to extract from (e.g., `main.rs:42` or `main.rs#function_name`) |
+| `-c, --context <N>` | Add N context lines |
+| `-k, --keep-input` | Preserve and display original input content |
+| `--prompt <TEMPLATE>` | System prompt template for LLM models (`engineer`, `architect`, or path to file) |
+| `--instructions <TEXT>` | User instructions for LLM models |
+| `-o, --format <TYPE>` | Output as: `color` (default), `terminal`, `markdown`, `plain`, `json`, `xml` |
+| `-o, --format <TYPE>` | Output as: `color` (default), `terminal`, `markdown`, `plain`, `json`, `xml` |
+
+### Extraction Examples
+
+```bash
+# Get function containing line 42
+probe extract src/main.rs:42
+
+# Extract multiple blocks
+probe extract src/auth.js:15 src/api.js:27
+
+# Extract by symbol name
+probe extract src/main.rs#handle_extract
+
+# Extract a specific line range
+probe extract src/main.rs:10-20
+
+# Output as JSON
+probe extract src/handlers.rs:108 --format json
+
+# Output as XML
+probe extract src/handlers.rs:108 --format xml
+
+# Add surrounding context
+probe extract src/utils.rs:72 --context 5
+
+# Preserve original input alongside extracted code
+probe extract src/main.rs:42 --keep-input
+
+# Extract from error output while preserving original messages
+rustc main.rs 2>&1 | probe extract -k
+
+# Extract code with LLM prompt and instructions
+probe extract src/auth.rs#authenticate --prompt engineer --instructions "Explain this authentication function"
+
+# Extract code with custom prompt template
+probe extract src/api.js:42 --prompt /path/to/custom/prompt.txt --instructions "Refactor this code"
+```
+
+## Query Command
+
+Find specific code structures using tree-sitter patterns:
+
+```bash
+probe query <PATTERN> <PATH> [OPTIONS]
+```
+
+### Query Options
+
+| Option | Function |
+|--------|----------|
+| `<PATTERN>` | Tree-sitter pattern to search for |
+| `<PATH>` | Where to search |
+| `--language <LANG>` | Specify language (inferred from files if omitted) |
+| `--ignore <PATTERN>` | Additional patterns to ignore |
+| `--allow-tests` | Include test code blocks |
+| `--max-results <N>` | Limit number of results |
+| `-o, --format <TYPE>` | Output as: `color` (default), `terminal`, `markdown`, `plain`, `json`, `xml` |
+
+### Query Examples
+
+```bash
+# Find Rust functions
+probe query "fn $NAME($$$PARAMS) $$$BODY" ./src --language rust
+
+# Find Python functions
+probe query "def $NAME($$$PARAMS): $$$BODY" ./src --language python
+
+# Find Go structs
+probe query "type $NAME struct { $$$FIELDS }" ./src --language go
+
+# Find C++ classes
+probe query "class $NAME { $$$METHODS };" ./src --language cpp
+
+# Output as JSON for programmatic use
+probe query "fn $NAME($$$PARAMS) $$$BODY" ./src --language rust --format json
+```
+
+## Output Formats
+
+Probe supports multiple output formats to suit different needs:
+
+| Format | Description |
+|--------|-------------|
+| `color` | Colorized terminal output (default) |
+| `terminal` | Plain terminal output without colors |
+| `markdown` | Markdown-formatted output |
+| `plain` | Plain text output without formatting |
+| `json` | JSON-formatted output for programmatic use |
+| `xml` | XML-formatted output for programmatic use |
+
+For detailed information about the JSON and XML output formats, see the [Output Formats](./output-formats.md) documentation.
+
+## Power Techniques
+
+### From Compiler Errors
+
+Feed error output directly to extract relevant code:
+
+```bash
+# Extract code from compiler errors
+rustc main.rs 2>&1 | probe extract
+
+# Pull code from test failures
+go test ./... | probe extract
+```
+
+### Unix Pipeline Integration
+
+Chain with other tools for maximum effect:
+
+```bash
+# Find then filter
+probe search "database" | grep "connection"
+
+# Process & format
+probe search "api" --format json | jq '.results[0]'
+```
+
+## Command Combinations
+
+Create powerful workflows by combining features:
+
+```bash
+# Find authentication code without tests
+probe search "authenticate" --max-results 10 --ignore "test" --no-merge
+
+# Extract specific functions with context
+grep -n "handleRequest" ./src/*.js | cut -d':' -f1,2 | probe extract --context 3
+
+# Find and extract error handlers
+probe search "error handling" --files-only | xargs -I{} probe extract {} --format markdown
+```
+
+## Session-Based Caching
+
+Avoid seeing the same code blocks multiple times in a session:
+
+```bash
+# First search - generates a session ID
+probe search "authentication" --session ""
+# Session: a1b2 (example output)
+
+# Subsequent searches - reuse the session ID
+probe search "login" --session "a1b2"
+# Will skip code blocks already shown in the previous search
+
+## Chat Command (`probe-chat`)
+
+Engage in an interactive chat session with the Probe AI agent or send single messages for non-interactive use.
+
+```bash
+probe-chat [PATH] [OPTIONS]
+```
+
+### Chat Options
+
+| Option | Function |
+|--------|----------|
+| `[PATH]` | Path to the codebase to search (overrides `ALLOWED_FOLDERS` env var) |
+| `-d, --debug` | Enable debug mode for verbose logging |
+| `--model-name <model>` | Specify the AI model to use (e.g., `claude-3-opus-20240229`, `gpt-4o`) |
+| `-f, --force-provider <provider>` | Force a specific provider (`anthropic`, `openai`, `google`) |
+| `-w, --web` | Run in web interface mode instead of CLI |
+| `-p, --port <port>` | Port for web server (default: 8080) |
+| `-m, --message <message>` | Send a single message and exit (non-interactive) |
+| `-s, --session-id <sessionId>` | Specify a session ID for the chat |
+| `--json` | Output response as JSON in non-interactive mode |
+| `--max-iterations <number>` | Max tool iterations allowed (default: 30) |
+| `--prompt <value>` | Use a custom prompt (`architect`, `code-review`, `support`, `engineer`, path to file, or string) |
+| `--allow-edit` | **Enable code editing via the `implement` tool (uses Aider)** |
+| `--trace-file [path]` | Enable file-based tracing (default: ./probe-traces.jsonl) |
+| `--trace-remote <url>` | Enable remote tracing to OpenTelemetry collector |
+| `--trace-console` | Enable console tracing for debugging |
+
+### Code Editing (`--allow-edit`)
+
+The `--allow-edit` flag lets Probe make changes to your code files.
+
+#### How It Works
+
+When you enable editing, Probe can modify your code when you ask it to:
+- "Fix this bug in main.py"
+- "Add error handling to this function"
+- "Refactor this code to be cleaner"
+
+#### What You Need
+
+1. **Install a Backend Tool**: Probe can use different tools to make code changes:
+   
+   - **Claude Code** (default if available):
+     ```bash
+     npm install -g @anthropic-ai/claude-code
+     ```
+   
+   - **Aider** (fallback):
+     ```bash
+     pip install aider-chat
+     ```
+
+2. **File Permissions**: Make sure Probe can write to your project files.
+
+#### Backend Configuration
+
+Probe automatically detects which tool to use for code editing:
+1. **Claude Code**: Used by default if installed (cross-platform, including WSL on Windows)
+2. **Aider**: Used as fallback if Claude Code is not available
+
+You can override this behavior by setting the `implement_tool_backend` environment variable:
+```bash
+# Force using Claude Code
+export implement_tool_backend=claude
+probe-chat --allow-edit
+
+# Force using Aider
+export implement_tool_backend=aider
+probe-chat --allow-edit
+```
+
+#### Usage Examples
+
+```bash
+# Start chat with editing enabled
+probe-chat --allow-edit
+
+# Ask for a specific change
+probe-chat --allow-edit --message "Add comments to the main function"
+```
+
+#### Important Safety Notes
+
+- **Always review changes** before keeping them
+- **Test your code** after Probe makes changes
+- **Start small** - try simple changes first to see how it works
+
+#### GitHub Actions Alternative
+
+If you're using Probe in GitHub Actions, you can use `allow_suggestions` instead, which creates reviewable suggestions rather than direct changes. See the [GitHub Actions Integration](./integrations/github-actions.md#code-modification-options) guide for details.
+
+### OpenTelemetry Tracing
+
+The `--trace-file`, `--trace-remote`, and `--trace-console` flags enable comprehensive monitoring and observability for AI interactions.
+
+#### Tracing Options
+
+**File Tracing (`--trace-file`)**
+- Saves traces to a JSON Lines format file for offline analysis
+- Default file path: `./probe-traces.jsonl`
+- Custom path: `--trace-file ./my-traces.jsonl`
+
+**Remote Tracing (`--trace-remote`)**
+- Sends traces to OpenTelemetry collectors (Jaeger, Zipkin, etc.)
+- Requires collector URL: `--trace-remote http://localhost:4318/v1/traces`
+
+**Console Tracing (`--trace-console`)**
+- Outputs traces to console for debugging
+- Useful for development and troubleshooting
+
+#### Usage Examples
+
+```bash
+# Enable file-based tracing
+probe-chat --trace-file
+
+# Enable remote tracing to Jaeger
+probe-chat --trace-remote http://localhost:4318/v1/traces
+
+# Enable console tracing for debugging
+probe-chat --trace-console
+
+# Combine multiple tracing options
+probe-chat --trace-file --trace-remote --trace-console
+
+# Use custom file path
+probe-chat --trace-file ./debug-traces.jsonl
+```
+
+#### What Gets Traced
+
+The tracing system captures detailed information about AI interactions:
+
+- **Performance Metrics**: Response times, request durations, and throughput
+- **Token Usage**: Prompt tokens, completion tokens, and total consumption
+- **Model Information**: Provider, model name, and configuration
+- **Session Data**: Session IDs, iteration counts, and conversation flow
+- **Error Tracking**: Failed requests, timeouts, and error details
+
+For more details on tracing, see the [AI Chat documentation](./ai-chat.md#opentelemetry-tracing).
+
+### Chat Examples
+
+```bash
+# Start interactive chat in the current directory
+probe-chat
+
+# Start interactive chat targeting a specific project path
+probe-chat /path/to/my/project
+
+# Use the 'engineer' persona
+probe-chat --prompt engineer
+
+# Send a single question and get a JSON response
+probe-chat --message "Explain the auth flow in main.go" --json
+
+# Start chat with editing enabled (requires Aider)
+probe-chat /path/to/project --allow-edit
+
+# Start chat with tracing enabled
+probe-chat --trace-file ./session-traces.jsonl
+
+# Start chat with full observability
+probe-chat --trace-file --trace-remote http://localhost:4318/v1/traces --allow-edit
+```