# Using and Creating Commands in FlowAI

G'day! This guide will help you understand and create custom commands in FlowAI. Commands are a ripper way to automate your common workflows without having to remember complex pipe operations and prompt file combinations.

## Getting Help

To see all available options and commands:
```bash
flowai
# or
flowai --help
```

To see a list of available commands:
```bash
flowai --command list
```

To get help with a specific command:
```bash
flowai --command help [command-name]
```

## What Are Commands?

Commands are pre-configured combinations of:
- A context-gathering shell command
- A prompt template file
- An optional user input prompt
- An optional output format setting
- An optional user input guide

Instead of typing something like:
```bash
git diff -w --staged | flowai --prompt-file ~/flowai-prompts/code-review.txt "Review these changes"
```

You can simply use:
```bash
flowai --command staged-code-review
```

## Command Configuration

Commands are defined in `~/flowai-prompts/prompt-index.txt` using a CSV format:
```csv
label,description,context_command,prompt_file,format,user_input
"staged-commit-message","Generate commit message","git diff -w --staged","~/flowai-prompts/prompt-commit-message.txt","raw","Brief description of the changes (optional)"
"pull-request","Create PR description","git log [Input branch name]..HEAD","~/flowai-prompts/prompt-pull-request.txt","raw","What is the main purpose of these changes?"
"staged-code-review","Review staged changes","git diff -w --staged","~/flowai-prompts/prompt-code-review.txt","markdown",""
```

Each field serves a specific purpose:
- `label`: The command name used with `--command`
- `description`: A brief explanation shown in the command list
- `context_command`: The shell command that generates the context
- `prompt_file`: The prompt template to use
- `format`: Optional output format ('raw' or 'markdown', defaults to markdown if not specified)
- `user_input`: Optional prompt to guide user input (if no command-line prompt is provided)

## User Input Handling

Commands can handle user input in two ways:

1. Command-line prompt (takes precedence):
```bash
# Provide description directly in command
flowai --command staged-commit-message "Added new format column"
```

2. Interactive prompt (if defined and no command-line prompt):
```bash
# Will prompt: "Brief description of the changes (optional):"
flowai --command staged-commit-message
```

You can:
- Provide input directly in the command (traditional way)
- Let the command prompt you for input (if defined)
- Skip the input entirely (just press Enter when prompted)

## Platform-Specific Commands

FlowAI automatically handles platform compatibility by allowing commands to be prefixed with the target platform:
- `win:` for Windows-specific commands
- `unix:` for Unix-based systems (Mac/Linux)

For example:
```csv
"unix:help","Get help with using FlowAI","cat ~/.config/flowai/docs/*.md","~/flowai-prompts/prompt-help.txt","markdown",""
"win:help","Get help with using FlowAI","type %USERPROFILE%\\.config\\flowai\\docs\\*.md","~/flowai-prompts/prompt-help.txt","markdown",""
```

When you run a command (e.g., `flowai --command help`), FlowAI automatically selects the appropriate version for your platform. Commands without a platform prefix work on all platforms.

## Interactive Input

Commands can prompt for user input using square brackets in the `context_command`:
```csv
"blame-lines","Find who changed specific lines","git blame -L [Enter line range (e.g. 10,20)] [Enter file path]","~/flowai-prompts/blame-analysis.txt","raw",""
```

When running this command, FlowAI will:
1. Ask for the line range
2. Ask for the file path
3. Replace the bracketed text with user input
4. Run the resulting command

## Output Formatting

Commands can specify their output format using the `format` column:
- `markdown`: Format the output as markdown (default if not specified)
- `raw`: Output plain text without markdown formatting

This is useful for:
- Commands that generate structured output (use 'markdown')
- Commands that generate raw data or code (use 'raw')
- Commands where you want to control the exact formatting

Example:
```csv
"staged-commit-message","Generate commit message","git diff -w --staged","~/flowai-prompts/prompt-commit-message.txt","raw","Brief description of the changes (optional)"
"code-review","Review code changes","git diff -w","~/flowai-prompts/prompt-code-review.txt","markdown",""
```

The format setting in the command overrides the default behavior and the `--no-markdown` flag.

## Command Ideas

Here are some ripper ideas for custom commands:

### 1. Git Workflows
- `branch-summary`: Show what's been done in the current branch
  ```csv
  "branch-summary","Summarize branch changes","git log main..HEAD","~/flowai-prompts/branch-summary.txt","markdown","Focus areas to highlight (optional)"
  ```

- `commit-suggest`: Suggest commit message for staged changes
  ```csv
  "commit-suggest","Generate commit message","git diff --staged","~/flowai-prompts/commit-message.txt","raw","Brief description of changes (optional)"
  ```

### 2. Code Analysis
- `complexity-check`: Analyze function complexity
  ```csv
  "complexity-check","Check code complexity","cat [Enter file path]","~/flowai-prompts/complexity-analysis.txt","markdown","Specific concerns to address"
  ```

- `docstring-gen`: Generate Python docstrings
  ```csv
  "docstring-gen","Generate docstrings","cat [Enter file path]","~/flowai-prompts/docstring-generator.txt","raw","Style guide to follow (e.g., Google, NumPy)"
  ```

### 3. Testing
- `test-generator`: Generate unit tests
  ```csv
  "test-generator","Create unit tests","cat [Enter source file]","~/flowai-prompts/test-generator.txt","raw","Testing framework to use"
  ```

- `test-coverage`: Analyze test coverage gaps
  ```csv
  "test-coverage","Find coverage gaps","coverage report","~/flowai-prompts/coverage-analysis.txt","markdown",""
  ```

## Tips for Creating Commands

1. **Keep It Simple**
   - Start with common tasks you do frequently
   - Use descriptive command names
   - Keep descriptions clear and concise

2. **Smart Prompting**
   - Use brackets for required user input in context commands
   - Make prompt text descriptive
   - Include examples in the prompt text
   - Use user_input for optional guidance

3. **Context is Key**
   - Ensure context commands provide enough information
   - Consider using multiple commands with pipes
   - Test commands with different inputs

4. **Reusability**
   - Make commands generic enough to reuse
   - Use parameters for flexibility
   - Document any requirements

5. **Output Format**
   - Use 'markdown' for human-readable output with structure
   - Use 'raw' for code, commit messages, or other plain text
   - Default to markdown if unsure

6. **User Input**
   - Add user_input prompts for commands that benefit from guidance
   - Make prompts optional when possible
   - Include examples in the prompt text
   - Keep prompts concise but clear

## Example Usage

Here's how to use some of the commands above:

```bash
# Generate docstrings for a Python file
flowai --command docstring-gen
# When prompted: Enter Python file: src/main.py

# Create a sprint summary
flowai --command sprint-summary
# When prompted: Days ago (e.g. 14): 7

# Analyze security implications of changes
flowai --command security-review
# When prompted: Enter branch/commit: feature/new-auth
```

Remember, you can always list available commands with:
```bash
flowai --command list
```

Or get details about a specific command with:
```bash
flowai --command help [command-name]
```

# FlowAI Commands

FlowAI supports various commands to help with your development workflow.

## Environment Compatibility

FlowAI is designed to work across different environments:
- Regular Unix/Linux systems
- macOS
  - Works with system shells and Homebrew-installed shells
  - Supports both Intel and Apple Silicon paths
- Windows (using cmd.exe)
- Docker containers and minimal environments
  - Automatically detects available shells
  - Works with limited environment variables
  - Compatible with common container base images
  - Falls back to available shell paths if environment variables aren't set

Shell Detection:
1. Windows: Always uses cmd.exe
2. Unix/Mac:
   - Checks $BASH and $SHELL environment variables
   - Falls back to common shell paths
   - Supports both system and custom-installed shells 