add vsc extension docs

docs/cli-reference/flags.mdx

@@ -0,0 +1,191 @@
+---
+title: "Flags Reference"
+description: "Complete reference for all Codeflash CLI flags and options"
+icon: "list"
+sidebarTitle: "Flags Reference"
+keywords: ["flags", "options", "arguments", "command line"]
+---
+
+# Flags Reference
+
+Complete reference for all Codeflash CLI flags and command-line options.
+
+---
+
+## Main Command Flags
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--file` | `PATH` | Optimize only this file |
+| `--function` | `NAME` | Optimize only this function (requires `--file`) |
+| `--all` | `[PATH]` | Optimize all functions. Optional path to start from |
+| `--replay-test` | `PATH` | Path to replay test file(s) |
+| `--benchmark` | flag | Enable benchmark mode |
+| `--no-pr` | flag | Don't create PR, update locally |
+| `--no-gen-tests` | flag | Don't generate tests |
+| `--no-draft` | flag | Skip draft PRs |
+| `--worktree` | flag | Use git worktree |
+| `--staging-review` | flag | Upload to staging |
+| `--verbose` / `-v` | flag | Verbose debug output |
+| `--verify-setup` | flag | Run setup verification |
+| `--version` | flag | Show version |
+
+---
+
+## Configuration Override Flags
+
+Override settings from `pyproject.toml` via command line.
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--config-file` | `PATH` | Path to pyproject.toml |
+| `--module-root` | `PATH` | Python module root directory |
+| `--tests-root` | `PATH` | Tests directory |
+| `--benchmarks-root` | `PATH` | Benchmarks directory |
+
+<Accordion title="Complete Examples">
+<Tabs>
+  <Tab title="Linux/macOS">
+    ```bash
+    # Override config file location
+    codeflash --file src/app.py --function main --config-file configs/pyproject.toml --no-pr
+
+    # Override module root
+    codeflash --file src/app.py --function main --module-root src --no-pr
+
+    # Override tests root
+    codeflash --file src/app.py --function main --tests-root tests/unit --no-pr
+
+    # Combine multiple overrides
+    codeflash --file src/app.py --function main \
+      --module-root src \
+      --tests-root tests \
+      --no-pr
+    ```
+  </Tab>
+  <Tab title="Windows">
+    ```powershell
+    # Override config file location
+    codeflash --file src\app.py --function main --config-file configs\pyproject.toml --no-pr
+
+    # Override module root
+    codeflash --file src\app.py --function main --module-root src --no-pr
+
+    # Override tests root
+    codeflash --file src\app.py --function main --tests-root tests\unit --no-pr
+    ```
+  </Tab>
+</Tabs>
+</Accordion>
+
+---
+
+## Optimize Subcommand Flags
+
+Flags specific to the `codeflash optimize` command.
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--output` | `PATH` | Trace file output path (default: `codeflash.trace`) |
+| `--timeout` | `INT` | Maximum trace time in seconds |
+| `--max-function-count` | `INT` | Max times to trace a function (default: 100) |
+| `--config-file-path` | `PATH` | Path to pyproject.toml |
+| `--trace-only` | flag | Only trace, don't optimize |
+
+<Info>
+  The `--output` flag specifies where to save the trace file. If not specified, it defaults to `codeflash.trace` in the current directory.
+</Info>
+
+---
+
+## Behavior Flags
+
+Control how Codeflash behaves during optimization.
+
+| Flag | Description |
+|------|-------------|
+| `--no-pr` | Run locally without creating a pull request |
+| `--no-gen-tests` | Use only existing tests, skip test generation |
+| `--no-draft` | Skip optimization for draft PRs (CI mode) |
+| `--worktree` | Use git worktree for isolated optimization |
+| `--staging-review` | Upload optimizations to staging for review |
+| `--verbose` / `-v` | Enable verbose debug logging |
+
+<Accordion title="Complete Examples">
+```bash
+# Local optimization only
+codeflash --file src/app.py --function main --no-pr
+
+# Use only existing tests
+codeflash --file src/app.py --function main --no-gen-tests --no-pr
+
+# Enable verbose logging
+codeflash --file src/app.py --function main --verbose --no-pr
+
+# Use worktree for isolation
+codeflash --file src/app.py --function main --worktree --no-pr
+
+# Upload to staging
+codeflash --all --staging-review --no-pr
+```
+</Accordion>
+
+---
+
+## Flag Combinations
+
+Common flag combinations for different use cases:
+
+### Local Development
+
+```bash
+# Optimize locally with verbose output
+codeflash --file src/app.py --function main --no-pr --verbose
+```
+
+### CI/CD Pipeline
+
+```bash
+# Skip draft PRs and use existing tests only
+codeflash --all --no-draft --no-gen-tests
+```
+
+### Debugging
+
+```bash
+# Trace only with custom output and timeout
+codeflash optimize app.py --trace-only --output debug.trace --timeout 60
+```
+
+### Custom Configuration
+
+```bash
+# Override multiple config settings
+codeflash --file src/app.py --function main \
+  --module-root src \
+  --tests-root tests/unit \
+  --benchmarks-root tests/benchmarks \
+  --no-pr
+```
+
+---
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card
+    title="Optimization Commands"
+    icon="bullseye"
+    href="/cli-reference/optimization"
+  >
+    Learn how to use optimization commands
+  </Card>
+  <Card
+    title="Troubleshooting"
+    icon="wrench"
+    href="/cli-reference/troubleshooting"
+  >
+    Fix common issues
+  </Card>
+</CardGroup>
+