ostruct-cli 0.8.29__py3-none-any.whl → 1.0.0__py3-none-any.whl

{ostruct_cli-0.8.29.dist-info → ostruct_cli-1.0.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: ostruct-cli
-Version: 0.8.29
+Version: 1.0.0
 Summary: CLI for OpenAI Structured Output with Multi-Tool Integration
 Author: Yaniv Golan
 Author-email: yaniv@golan.name
@@ -10,55 +10,32 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Provides-Extra: dev
 Provides-Extra: docs
 Provides-Extra: examples
-Requires-Dist: anyio[trio] (==3.7.1) ; extra == "dev"
 Requires-Dist: asyncio-throttle (>=1.0.2,<2.0) ; extra == "examples"
-Requires-Dist: black (==24.8.0) ; extra == "dev"
-Requires-Dist: build (>=1.2.2.post1,<2.0) ; extra == "dev"
+Requires-Dist: bleach (>=6.0.0,<7.0)
 Requires-Dist: cachetools (>=5.3.2,<6.0)
 Requires-Dist: chardet (>=5.0.0,<6.0)
 Requires-Dist: click (>=8.1.7,<9.0)
-Requires-Dist: flake8 (>=6.0,<7.0) ; extra == "dev"
-Requires-Dist: flake8-pyproject (>=1.2.3,<2.0) ; extra == "dev"
-Requires-Dist: hypothesis (>=6.0.0,<7.0) ; extra == "dev"
 Requires-Dist: ijson (>=3.2.3,<4.0)
 Requires-Dist: jinja2 (>=3.1.2,<4.0)
 Requires-Dist: jsonschema (>=4.23.0,<5.0)
-Requires-Dist: mypy (>=1.0,<2.0) ; extra == "dev"
-Requires-Dist: myst-parser (>=3.0.0,<4.0) ; extra == "docs"
+Requires-Dist: myst-parser (>=4.0.1,<5.0) ; extra == "docs"
 Requires-Dist: openai (==1.81.0)
 Requires-Dist: openai-model-registry (>=0.7.0,<1.0)
-Requires-Dist: pre-commit (>=4.1.0,<5.0) ; extra == "dev"
-Requires-Dist: psutil (>=7.0.0,<8.0) ; extra == "dev"
 Requires-Dist: pydantic (>=2.6.3,<3.0)
-Requires-Dist: pyfakefs (>=5.7.4,<6.0) ; extra == "dev"
 Requires-Dist: pygments (>=2.15.0,<3.0)
-Requires-Dist: pytest (>=8.3.4,<9.0) ; extra == "dev"
-Requires-Dist: pytest-asyncio (>=0.25.2,<1.0) ; extra == "dev"
-Requires-Dist: pytest-mock (>=3.14.0,<4.0) ; extra == "dev"
-Requires-Dist: pytest-rerunfailures (>=12.0,<13.0) ; extra == "dev"
 Requires-Dist: python-dotenv (>=1.0.1,<2.0)
-Requires-Dist: python-dotenv (>=1.0.1,<2.0) ; extra == "dev"
 Requires-Dist: pyyaml (>=6.0.2,<7.0)
-Requires-Dist: sphinx (>=7.0.0,<8.0) ; extra == "dev"
+Requires-Dist: rich (>=13.0.0,<14.0.0)
+Requires-Dist: rich-click (>=1.8.9,<2.0.0)
 Requires-Dist: sphinx (>=7.0.0,<8.0) ; extra == "docs"
 Requires-Dist: sphinx-design (>=0.4.1,<1.0) ; extra == "docs"
-Requires-Dist: sphinx-rtd-theme (>=1.0,<2.0) ; extra == "docs"
+Requires-Dist: sphinx-rtd-theme (>=2.0,<3.0) ; extra == "docs"
 Requires-Dist: tenacity (>=8.2.3,<9.0) ; extra == "examples"
 Requires-Dist: tiktoken (==0.9.0)
 Requires-Dist: tomli (>=2.0.1,<3.0) ; (python_version < "3.11") and (extra == "docs")
-Requires-Dist: tomli (>=2.0.1,<3.0) ; extra == "dev"
 Requires-Dist: tomli (>=2.0.1,<3.0) ; python_version < "3.11"
-Requires-Dist: twine (>=6.0.1,<7.0) ; extra == "dev"
-Requires-Dist: types-cachetools (>=5.5.0.20240820) ; extra == "dev"
-Requires-Dist: types-chardet (>=5.0.4.6) ; extra == "dev"
-Requires-Dist: types-click (>=7.1.8,<8.0) ; extra == "dev"
-Requires-Dist: types-jsonschema (>=4.23.0.20241208) ; extra == "dev"
-Requires-Dist: types-pygments (>=2.19.0.20250107) ; extra == "dev"
-Requires-Dist: types-pyyaml (>=6.0.12.20241230) ; extra == "dev"
-Requires-Dist: types-requests (>=2.32.0.20241016) ; extra == "dev"
 Requires-Dist: typing-extensions (>=4.9.0,<5.0)
 Requires-Dist: werkzeug (>=3.1.3,<4.0)
 Description-Content-Type: text/markdown
@@ -95,7 +72,7 @@ ostruct processes unstructured data (text files, code, CSVs, etc.), input variab
 
 <div align="center">
 
-![How ostruct works](src/assets/ostrict-hl-diagram.png)
+![How ostruct works](src/assets/ostruct-hl-diagram.png)
 
 </div>
 
@@ -116,11 +93,11 @@ ostruct can be used for various scenarios, including:
 ### Automated Code Review with Multi-Tool Analysis
 
 ```bash
-# Traditional pattern matching
-ostruct run prompts/task.j2 schemas/code_review.json -p source "examples/security/*.py"
+# Template-only analysis (fast, cost-effective)
+ostruct run prompts/task.j2 schemas/code_review.json --collect source @file-list.txt
 
 # Enhanced with Code Interpreter for deeper analysis
-ostruct run prompts/task.j2 schemas/code_review.json -fc examples/security/ -fs documentation/
+ostruct run prompts/task.j2 schemas/code_review.json --file ci:code examples/security/ --file fs:docs documentation/
 ```
 
 Analyze code for security vulnerabilities, style issues, and performance problems. The enhanced version uses Code Interpreter for execution analysis and File Search for documentation context.
@@ -130,15 +107,15 @@ Analyze code for security vulnerabilities, style issues, and performance problem
 ```bash
 # Budget-friendly static analysis (recommended for most projects)
 ostruct run prompts/static_analysis.j2 schemas/scan_result.json \
-  -d code examples -R --sys-file prompts/system.txt
+  --dir code examples --pattern "*.py" --sys-file prompts/system.txt
 
 # Professional security analysis with Code Interpreter (best balance)
 ostruct run prompts/code_interpreter.j2 schemas/scan_result.json \
-  -dc examples --sys-file prompts/system.txt
+  --dir ci:code examples --sys-file prompts/system.txt
 
 # Comprehensive hybrid analysis for critical applications
 ostruct run prompts/hybrid_analysis.j2 schemas/scan_result.json \
-  -d code examples -R -dc examples --sys-file prompts/system.txt
+  --dir code examples --dir ci:analysis examples --sys-file prompts/system.txt
 ```
 
 **Three optimized approaches** for automated security vulnerability scanning:
@@ -154,8 +131,8 @@ Each approach finds the same core vulnerabilities but with different levels of d
 ```bash
 # Upload data for analysis and visualization
 ostruct run analysis.j2 schemas/analysis_result.json \
-  -fc sales_data.csv -fc customer_data.json \
-  -fs reports/ -ft config.yaml
+  --file ci:sales sales_data.csv --file ci:customers customer_data.json \
+  --dir fs:reports reports/ --file config config.yaml
 ```
 
 Perform sophisticated data analysis using Python execution, generate visualizations, and create comprehensive reports with document context.
@@ -165,11 +142,11 @@ Perform sophisticated data analysis using Python execution, generate visualizati
 ```bash
 # Traditional file comparison
 ostruct run prompts/task.j2 schemas/validation_result.json \
-  -f dev examples/basic/dev.yaml -f prod examples/basic/prod.yaml
+  --file dev examples/basic/dev.yaml --file prod examples/basic/prod.yaml
 
 # Enhanced with environment context
 ostruct run prompts/task.j2 schemas/validation_result.json \
-  -ft dev.yaml -ft prod.yaml -fs infrastructure_docs/
+  --file dev dev.yaml --file prod prod.yaml --dir fs:docs infrastructure_docs/
 ```
 
 Validate configuration files across environments with documentation context for better analysis and recommendations.
@@ -179,11 +156,40 @@ Oh, and also, among endless other use cases:
 ### Etymology Analysis
 
 ```bash
-ostruct run prompts/task.j2 schemas/etymology.json -ft examples/scientific.txt
+ostruct run prompts/task.j2 schemas/etymology.json --file text examples/scientific.txt
 ```
 
 Break down words into their components, showing their origins, meanings, and hierarchical relationships. Useful for linguistics, educational tools, and understanding terminology in specialized fields.
 
+### Optional File References
+
+```bash
+# Attach files with aliases
+ostruct run template.j2 schema.json \
+  --dir source-code src/ \
+  --file config config.yaml
+```
+
+**Two ways to access files in templates:**
+
+```jinja2
+{# Option 1: Automatic XML appendix (optional) #}
+Analyze {{ file_ref("source-code") }} and {{ file_ref("config") }}.
+
+{# Option 2: Manual formatting (full control) #}
+## Source Code
+{% for file in source-code %}
+### {{ file.name }}
+```{{ file.name.split('.')[-1] }}
+{{ file.content }}
+```
+
+{% endfor %}
+
+```
+
+The optional `file_ref()` function provides clean references with automatic XML appendix generation. Alternatively, access files directly for custom formatting and placement control. Perfect for code reviews, documentation analysis, and multi-file processing workflows.
+
 ## Features
 
 ### Core Capabilities
@@ -201,7 +207,7 @@ Break down words into their components, showing their origins, meanings, and hie
 - **File Search**: Vector-based document search and retrieval from uploaded files
 - **Web Search**: Real-time information retrieval and current data access via OpenAI's web search tool
 - **MCP Servers**: Connect to Model Context Protocol servers for extended functionality
-- **Explicit File Routing**: Route different files to specific tools for optimized processing
+- **Explicit Tool Targeting**: Route files to specific tools (prompt, code-interpreter, file-search) with precise control
 
 ### Advanced Features
 
@@ -209,6 +215,7 @@ Break down words into their components, showing their origins, meanings, and hie
 - **Unattended Operation**: Designed for CI/CD and automation scenarios
 - **Progress Reporting**: Real-time progress updates with clear, user-friendly messaging
 - **Model Registry**: Dynamic model management with support for latest OpenAI models
+- **Optional File References**: Clean `file_ref()` function for automatic XML appendix, or direct file access for custom formatting
 
 ## Requirements
 
@@ -219,24 +226,33 @@ Break down words into their components, showing their origins, meanings, and hie
 We provide multiple installation methods to suit different user needs. Choose the one that's right for you.
 
 <details>
-<summary><strong>Recommended: pipx (Python Users)</strong></summary>
+<summary><strong>Recommended: pipx</strong></summary>
 
-For users who have Python installed, `pipx` is the recommended installation method. It installs `ostruct` in an isolated environment, preventing conflicts with other Python packages.
+`pipx` is the recommended installation method. It installs `ostruct` in an isolated environment, preventing conflicts with other Python packages.
 
-1. **Install pipx**:
+**macOS (with Homebrew):**
+```bash
+brew install pipx
+pipx install ostruct-cli       # new users
+pipx upgrade ostruct-cli       # existing users
+```
 
-    ```bash
-    python3 -m pip install --user pipx
-    python3 -m pipx ensurepath
-    ```
+**Linux (Ubuntu/Debian):**
 
-    *(Restart your terminal after running `ensurepath` to update your `PATH`)*
+```bash
+sudo apt install pipx
+pipx install ostruct-cli       # new users
+pipx upgrade ostruct-cli       # existing users
+```
 
-2. **Install ostruct-cli**:
+**Other systems:**
 
-    ```bash
-    pipx install ostruct-cli
-    ```
+```bash
+python3 -m pip install --user pipx
+python3 -m pipx ensurepath
+# Restart your terminal
+pipx install ostruct-cli
+```
 
 </details>
 
@@ -279,7 +295,7 @@ docker run -it --rm \
   -v "$(pwd)":/app \
   -w /app \
   ghcr.io/yaniv-golan/ostruct:latest \
-  run template.j2 schema.json -ft input.txt
+  run template.j2 schema.json --file config input.txt
 ```
 
 This command mounts the current directory into the container and runs `ostruct`.
@@ -315,12 +331,25 @@ If you plan to contribute to the project, see the [Development Setup](#developme
 
 ostruct-cli respects the following environment variables:
 
+**API Configuration:**
+
 - `OPENAI_API_KEY`: Your OpenAI API key (required unless provided via command line)
 - `OPENAI_API_BASE`: Custom API base URL (optional)
 - `OPENAI_API_VERSION`: API version to use (optional)
 - `OPENAI_API_TYPE`: API type (e.g., "azure") (optional)
+
+**System Configuration:**
+
 - `OSTRUCT_DISABLE_REGISTRY_UPDATE_CHECKS`: Set to "1", "true", or "yes" to disable automatic registry update checks
-- `MCP_<NAME>_URL`: Custom MCP server URLs (e.g., `MCP_STRIPE_URL=https://mcp.stripe.com`)
+- `OSTRUCT_MCP_URL_<name>`: Custom MCP server URLs (e.g., `OSTRUCT_MCP_URL_stripe=https://mcp.stripe.com`)
+
+**Template Processing Limits (Template-only files via `--file alias path`):**
+
+- `OSTRUCT_TEMPLATE_FILE_LIMIT`: Maximum individual file size for template access (default: 65536 bytes / 64KB)
+- `OSTRUCT_TEMPLATE_TOTAL_LIMIT`: Maximum total file size for all template files (default: 1048576 bytes / 1MB)
+- `OSTRUCT_TEMPLATE_PREVIEW_LIMIT`: Maximum characters shown in template debugging previews (default: 4096)
+
+> **Note**: Template limits only apply to files accessed via `--file alias path` (template-only routing). Files routed to Code Interpreter (`--file ci:`) or File Search (`--file fs:`) are not subject to these limits.
 
 **💡 Tip**: ostruct automatically loads `.env` files from the current directory. Environment variables take precedence over `.env` file values.
 
@@ -365,78 +394,101 @@ Shell completion will help you with:
 
 ## Enhanced CLI with Multi-Tool Integration
 
-### Migration Notice
+### Breaking Changes in v0.9.0
 
-ostruct now includes powerful multi-tool integration while maintaining **full backward compatibility**. All existing commands continue to work exactly as before, but you can now take advantage of:
+**⚠️ Important:** ostruct v0.9.0 introduces breaking changes to the file attachment system. The legacy file routing syntax has been completely replaced with a new explicit target/alias attachment system.
 
-- **Code Interpreter** for data analysis and visualization
-- **File Search** for document retrieval
-- **Web Search** for real-time information access
-- **MCP Servers** for extended functionality
-- **Explicit File Routing** for optimized processing
+**New capabilities in v0.9.0:**
+
+- **Explicit Tool Targeting**: Direct control over which tools receive files
+- **Enhanced Security**: Three-tier security modes with path validation
+- **Improved Multi-Tool Integration**: Better file sharing between tools
+- **JSON Help Output**: Programmatic access to command help
+- **Migration Guide**: Automated migration scripts for bulk updates
 
 <details>
-<summary><strong>New File Routing Options</strong> (Click to expand)</summary>
+<summary><strong>New Attachment System (v0.9.0)</strong> (Click to expand)</summary>
 
-#### Basic File Routing (Explicit Tool Assignment)
+#### Basic File Attachments
 
 ```bash
-# Template access only (config files, small data)
-ostruct run template.j2 schema.json -ft config.yaml
+# Template access only (default - no tool upload)
+ostruct run template.j2 schema.json --file config config.yaml
 
 # Code Interpreter (data analysis, code execution)
-ostruct run analysis.j2 schema.json -fc data.csv
+ostruct run analysis.j2 schema.json --file ci:data data.csv
 
 # File Search (document retrieval)
-ostruct run search.j2 schema.json -fs documentation.pdf
-
-# Web Search (real-time information)
-ostruct run research.j2 schema.json --enable-tool web-search -V topic="latest AI developments"
+ostruct run search.j2 schema.json --file fs:docs documentation.pdf
 
-# Multiple tools with one file
-ostruct run template.j2 schema.json --file-for code-interpreter shared.json --file-for file-search shared.json
+# Multi-tool attachment (share between tools)
+ostruct run workflow.j2 schema.json --file ci,fs:shared data.json
 ```
 
-#### Directory Routing
+#### Directory Attachments
 
-ostruct provides two directory routing patterns to match different use cases:
+```bash
+# Template-only directory access
+ostruct run template.j2 schema.json --dir config ./config
 
-**Auto-Naming Pattern** (for known directory structures):
+# Upload directory to Code Interpreter
+ostruct run analysis.j2 schema.json --dir ci:datasets ./data
 
-```bash
-# Variables are auto-generated from directory contents
-ostruct run template.j2 schema.json -dt ./config -dc ./datasets -ds ./docs
-# Creates variables like: config_yaml, datasets_csv, docs_pdf (based on actual files)
+# Upload directory to File Search
+ostruct run search.j2 schema.json --dir fs:knowledge ./docs
+
+# Directory with file pattern filtering
+ostruct run template.j2 schema.json --dir source ./src --pattern "*.py"
 ```
 
-**Alias Pattern** (for generic, reusable templates):
+#### File Collections
 
 ```bash
-# Create stable variable names regardless of directory contents
-ostruct run template.j2 schema.json --dta app_config ./config --dca data ./datasets --dsa knowledge ./docs
-# Creates stable variables: app_config, data, knowledge (always these names)
+# Process multiple files from list
+ostruct run batch.j2 schema.json --collect files @file-list.txt
+
+# Upload collection to Code Interpreter
+ostruct run analyze.j2 schema.json --collect ci:data @datasets.txt
 ```
 
-**When to Use Each Pattern:**
+#### Tool Targeting
 
-- Use **auto-naming** (`-dt`, `-dc`, `-ds`) when your template knows the specific directory structure
-- Use **alias syntax** (`--dta`, `--dca`, `--dsa`) when your template is generic and needs stable variable names
+The new system uses explicit targets for precise control:
 
-**Template Example:**
+- **`prompt`** (default): Template access only, no upload
+- **`code-interpreter`** or **`ci`**: Upload for Python execution and analysis
+- **`file-search`** or **`fs`**: Upload to vector store for document search
+- **Multi-target**: `ci,fs:alias` shares file between multiple tools
 
-```jinja
-{# Works with alias pattern - variables are predictable #}
-{% for file in app_config %}
-Configuration: {{ file.name }} = {{ file.content }}
-{% endfor %}
+#### Development Best Practice: Always Use --dry-run
 
-{# Analysis data from stable variable name #}
-{% for file in data %}
-Processing: {{ file.path }}
-{% endfor %}
+**Validate templates before execution** to catch errors early and save API costs:
+
+```bash
+# 1. Validate everything first (catches binary file issues, template errors)
+ostruct run analysis.j2 schema.json --file ci:data report.xlsx --dry-run
+
+# 2. If validation passes, run for real
+ostruct run analysis.j2 schema.json --file ci:data report.xlsx
 ```
 
-This design pattern makes templates reusable across different projects while maintaining full backward compatibility.
+The `--dry-run` flag performs comprehensive validation including template rendering, catching issues like:
+
+- Binary file content access errors
+- Template syntax problems
+- Missing template variables
+- File accessibility issues
+
+#### Security Modes
+
+```bash
+# Strict security with explicit allowlists
+ostruct run template.j2 schema.json \
+  --path-security strict \
+  --allow /safe/directory \
+  --allow-file /specific/file.txt \
+  --file data input.txt
+```
 
 #### MCP Server Integration
 
@@ -458,7 +510,7 @@ models:
 tools:
   code_interpreter:
     auto_download: true
-    output_directory: "./output"
+    output_directory: "./downloads"
     download_strategy: "two_pass_sentinel"  # Enable reliable file downloads
 
 mcp:
@@ -474,6 +526,44 @@ Load custom configuration:
 ostruct --config my-config.yaml run template.j2 schema.json
 ```
 
+### Model Validation
+
+ostruct automatically validates model names against the OpenAI model registry. Only models that support structured output are available for selection, ensuring compatibility with JSON schema outputs.
+
+```bash
+# See all available models with details
+ostruct list-models
+
+# Models are validated at command time
+ostruct run template.j2 schema.json --model invalid-model
+# Error: Invalid model 'invalid-model'. Available models: gpt-4o, gpt-4o-mini, o1 (and 12 more).
+#        Run 'ostruct list-models' to see all 15 available models.
+
+# Shell completion works with model names
+ostruct run template.j2 schema.json --model <TAB>
+# Shows: gpt-4o  gpt-4o-mini  o1  o1-mini  o3-mini  ...
+```
+
+**Model Registry Updates:**
+
+The model list is automatically updated when you run `ostruct update-registry`. If you encounter model validation errors, try updating your registry first:
+
+```bash
+# Update model registry
+ostruct update-registry
+
+# Check available models
+ostruct list-models
+```
+
+**Migration from Free-form Model Names:**
+
+If you have existing scripts with hardcoded model names, they will continue to work as long as the model names are valid. Common issues and solutions:
+
+- **Typos**: `gpt4o` → `gpt-4o`
+- **Old names**: `gpt-4-turbo` → `gpt-4o`
+- **Custom names**: Use `ostruct list-models` to see what's available
+
 ### Code Interpreter File Downloads
 
 **Important**: If you're using Code Interpreter with structured output (JSON schemas), you may need to enable the two-pass download strategy to ensure files are downloaded reliably.
@@ -482,10 +572,14 @@ ostruct --config my-config.yaml run template.j2 schema.json
 
 ```bash
 # Enable reliable file downloads for this run
-ostruct run template.j2 schema.json -fc data.csv --enable-feature ci-download-hack
+ostruct run template.j2 schema.json --file ci:data data.csv --enable-feature ci-download-hack
 
 # Force single-pass mode (override config)
-ostruct run template.j2 schema.json -fc data.csv --disable-feature ci-download-hack
+ostruct run template.j2 schema.json --file ci:data data.csv --disable-feature ci-download-hack
+
+# Handle duplicate output file names
+ostruct run template.j2 schema.json --file ci:data data.csv --ci-duplicate-outputs rename
+ostruct run template.j2 schema.json --file ci:data data.csv --ci-duplicate-outputs skip
 ```
 
 #### Option 2: Configuration File (Recommended for persistent settings)
@@ -497,6 +591,8 @@ tools:
     download_strategy: "two_pass_sentinel"  # Enables reliable file downloads
     auto_download: true
     output_directory: "./downloads"
+    duplicate_outputs: "rename"  # Handle duplicate file names: overwrite|rename|skip
+    output_validation: "basic"   # Validate downloaded files: basic|strict|off
 ```
 
 **Why this is needed**: OpenAI's structured output mode can prevent file download annotations from being generated. The two-pass strategy works around this by making two API calls: one to generate files (without structured output), then another to ensure schema compliance. For detailed technical information, see [docs/known-issues/2025-06-responses-ci-file-output.md](docs/known-issues/2025-06-responses-ci-file-output.md).
@@ -618,47 +714,54 @@ Provide comprehensive analysis and actionable insights.
 }
 ```
 
-3. For more complex scenarios, use explicit file routing with flexible syntax options:
+3. Use the new attachment system for precise tool targeting:
 
 ```bash
-# Auto-naming (fastest for one-off analysis)
+# Basic multi-tool analysis
 ostruct run analysis_template.j2 analysis_schema.json \
-  -fc sales_data.csv \
-  -fc customer_data.json \
-  -fs market_reports.pdf \
-  -ft config.yaml
+  --file ci:sales sales_data.csv \
+  --file ci:customers customer_data.json \
+  --file fs:reports market_reports.pdf \
+  --file config config.yaml
 
-# Mixed syntax with custom variable names
+# Multi-tool attachment with shared data
 ostruct run analysis_template.j2 analysis_schema.json \
-  -fc sales_data.csv \
-  -fc customers customer_data.json \
-  --fsa reports market_reports.pdf \
-  --fta app_config config.yaml
+  --file ci,fs:shared_data data.json \
+  --file prompt:config settings.yaml
 
-# Alias syntax for reusable templates (best tab completion)
+# Directory-based analysis
 ostruct run reusable_analysis.j2 analysis_schema.json \
-  --fca sales_data sales_data.csv \
-  --fca customer_data customer_data.json \
-  --fsa market_reports market_reports.pdf \
-  --fta config config.yaml
+  --dir ci:sales_data ./sales \
+  --dir fs:documentation ./docs \
+  --file config ./config.yaml
 
-# Code review with stable variable names
+# Code review with multiple tool integration
 ostruct run code_review.j2 review_schema.json \
-  --fca source_code source_code/ \
-  --fsa documentation docs/ \
-  --fta eslint_config .eslintrc.json
+  --dir ci:source ./src \
+  --dir fs:docs ./documentation \
+  --file config .eslintrc.json
 ```
 
-### Example 3: Legacy Compatibility
+### Example 3: Migration from v0.8.x
 
-All existing commands continue to work unchanged:
+Legacy commands need to be updated to the new syntax:
 
 ```bash
-# Traditional usage (fully supported)
-ostruct run extract_from_file.j2 schema.json -f text input.txt -d configs
-ostruct run template.j2 schema.json -p "*.py" source -V env=prod
+# Legacy (v0.8.x) - NO LONGER SUPPORTED
+# ostruct run extract_from_file.j2 schema.json --file text input.txt -d configs
+
+# New (v0.9.0) - Updated syntax
+ostruct run extract_from_file.j2 schema.json --file text input.txt --dir configs ./configs
+
+# Legacy pattern matching - NO LONGER SUPPORTED
+# ostruct run template.j2 schema.json --dir "*.py" source --pattern "*.py" -V env=prod
+
+# New pattern matching with directory attachment
+ostruct run template.j2 schema.json --dir source ./source --pattern "*.py" -V env=prod
 ```
 
+**Migration Help:** See `MIGRATION_GUIDE.md` for automated migration scripts and detailed examples.
+
 <details>
 <summary><strong>System Prompt Handling</strong> (Click to expand)</summary>
 

ostruct_cli-1.0.0.dist-info/RECORD

@@ -0,0 +1,80 @@
+ostruct/__init__.py,sha256=X6zo6V7ZNMv731Wi388aTVQngD1410ExGwGx4J6lpyo,187
+ostruct/cli/__init__.py,sha256=njg70kPnRja8KqP_y93CIWPyeNj8EzH8AhHotn0jJAc,820
+ostruct/cli/attachment_processor.py,sha256=_RcE8tdJ5ey5jsL5UBsOadKrAqBjr71nLqZsv8b2kwg,16469
+ostruct/cli/attachment_template_bridge.py,sha256=iehtZ3AR1QoQP_fQxiVH_jV4z-3bCsfvRkwoMz8DEWs,35058
+ostruct/cli/base_errors.py,sha256=o-877bJJA8yJWISRPy0KyL6wDu1-_avddmQIfVePuFM,5989
+ostruct/cli/cache_manager.py,sha256=ej3KrRfkKKZ_lEp2JswjbJ5bW2ncsvna9NeJu81cqqs,5192
+ostruct/cli/cli.py,sha256=RCHjwx2mbRx9N-L1GeMgROqskvipjpwmavVh2z_Etds,8746
+ostruct/cli/click_options.py,sha256=NFcs6amLBtVLOjR6smNbGmDHwBpAXrpxQy5KCiLKPo4,34203
+ostruct/cli/code_interpreter.py,sha256=M8gyPy17s5lu8TsvXMDes4wi78iwqz_yoAQ4axeuhwM,23264
+ostruct/cli/commands/__init__.py,sha256=KuEoh7UF9CWis3VHZ6LAwoRcZrpG8oq9VSQRl1NjEo8,622
+ostruct/cli/commands/list_models.py,sha256=yeuQpUGAmRr4uOHS7teuVHkC9dkqN0yKDOEw_n-ehi0,4662
+ostruct/cli/commands/run.py,sha256=oq2ZXCQehFJnUV34nC9TEaJL8Qb2aZrHAoLu0x3TR2M,16805
+ostruct/cli/commands/update_registry.py,sha256=7DQrPlCJScPVgE2HbFAM7UMap-EdYu58AQWfpI-H7Gw,2483
+ostruct/cli/config.py,sha256=KxkJGxvRiiDr7oinwZVaDqtzRcYyQZ1xcoCtvykq6F4,10143
+ostruct/cli/constants.py,sha256=zyUwq4fladlCsfPnBPh7rSqfSwarbCL3I5HM1dIEf6I,2467
+ostruct/cli/cost_estimation.py,sha256=08hyE-kM5QYzj7y-KB3lMD_RxCMoM_Ve3-IQlSpJAo4,4483
+ostruct/cli/errors.py,sha256=vqdkGx2Znze61ms6BByOYg4D3ScBEK7OFP73PeJJufo,30865
+ostruct/cli/exit_codes.py,sha256=gdvB1dpu0LalEUZrofpk5K6aTQ24n5AfkAK5umludHU,365
+ostruct/cli/explicit_file_processor.py,sha256=mKYQCW4bodk8Ida0sGw8m5MmbiaMCAYvoHUXzU1KDSE,19210
+ostruct/cli/field_utils.py,sha256=bcRi1qQ0Ac2UCfrKSQ677_yu-VzaShm_zN7QLf98qc0,1939
+ostruct/cli/file_info.py,sha256=rNQSkUDUL3qbalovRu1unTixLVDzJ0HU01eFQYlMXlM,21443
+ostruct/cli/file_list.py,sha256=AmnQnXyI1djVbp_pv2VwK2VAqZQpSiTIXPbwu3_wCRQ,23431
+ostruct/cli/file_search.py,sha256=6JvThbrauznfr-nX4M_VG7kRQbSLG9YOQomLR9_IqPE,17566
+ostruct/cli/file_utils.py,sha256=JZprQ-1LHQzI3eBfeCIS6VmxTa2fGUZHygGC8gcwpJM,24367
+ostruct/cli/help_json.py,sha256=IDArJBtPTTMM2KVt36t1PBY72totKH9tVAsRnPuEPcA,8223
+ostruct/cli/json_extract.py,sha256=ZleIxat8g-JnA9VVqWgJaKxN7QzL25itQ8aP0Gb5e4Q,2650
+ostruct/cli/mcp_integration.py,sha256=zC24TZScr-Vio2Zq0lPBJVmATVWoIm2pfWwnO3ztQJ8,18791
+ostruct/cli/model_creation.py,sha256=HGo8Qv7eBF8Co463IR7RcbTCQcaOvd_cBGuRodRCAa4,23261
+ostruct/cli/model_validation.py,sha256=j2az3q88-Ljm2cMMgZ8p_-gcp1vKQnWCknnw0y0YlAw,6675
+ostruct/cli/params.py,sha256=D4j_I6vZYN-lOeqHWyAmLSxAT3u77CUXVvf6sx27Uvo,6353
+ostruct/cli/path_utils.py,sha256=j44q1OoLkqMErgK-qEuhuIZ1VyzqRIvNgxR1et9PoXA,4813
+ostruct/cli/plan_assembly.py,sha256=pCz2fH3MNbUVODMw43_fb-e61vgo5N0GBrZ1VlShs1M,11656
+ostruct/cli/plan_printing.py,sha256=_OSrnaLKi0nLdSSHnf6exaIhJT5YPedKh_8nYgqkluI,12837
+ostruct/cli/progress.py,sha256=rj9nVEco5UeZORMbzd7mFJpFGJjbH9KbBFh5oTE5Anw,3415
+ostruct/cli/progress_reporting.py,sha256=cQoMsRCBlIdRIefGwpBEX744H9pfpD5TdT8sB180hfI,11665
+ostruct/cli/quick_ref_help.py,sha256=_AWPcdxDj9v6DOX6yecahv7dfV38-TwB4sK5HsWmIbo,5014
+ostruct/cli/registry_updates.py,sha256=ohiHdlfrocvThpR_ZjMyqulDKFjRM1hIFKOlNzpaqHg,5138
+ostruct/cli/rich_config.py,sha256=DChXWG97pQRm_QZCTdOIpBhvuIfJXDlqT48vnBdnYKc,9904
+ostruct/cli/runner.py,sha256=a7Zkp4Wn9x6sMmtVtGEwLQ8i8ctTvKo2w36n6WpbuLM,74672
+ostruct/cli/schema_utils.py,sha256=9LnsjxEKg6RIfXQB3nS3pyDggm5n-4-thXf92897gJU,3590
+ostruct/cli/schema_validation.py,sha256=ohEuxJ0KF93qphj0JSZDnrxDn0C2ZU37g-U2JY03onM,8154
+ostruct/cli/security/__init__.py,sha256=Ix0AXDgxJaR0TtR-sG1353DtUF1BPujgjcaA28Cvgh4,898
+ostruct/cli/security/allowed_checker.py,sha256=ceNUEDiTirClq9Kvosytlm01JWj0J37JdiRzLsw3zD8,3462
+ostruct/cli/security/base.py,sha256=q9YUdHEj2eg5w8GEw5403E9OQKIjZbEiaWsvYFnCGLw,1359
+ostruct/cli/security/case_manager.py,sha256=I_ZJSyntLuGx5qVzze559CI-OxsaNPSibkAN8zZ7PvE,2345
+ostruct/cli/security/errors.py,sha256=8jYJFRQyEXIH3Wd2ATWORVoqbDg7qwu0TsuROpsqNfU,5254
+ostruct/cli/security/normalization.py,sha256=6UoFAl8cbvOUETMauyvmYogaoVhJm9WybGcS84biwh8,5488
+ostruct/cli/security/safe_joiner.py,sha256=PHowCeBAkfHfPqRwuO5Com0OemGuq3cHkdu2p9IYNT0,7107
+ostruct/cli/security/security_manager.py,sha256=VQbWxOp76mm8OCpCTtkzBrBh5nb-dKWQbxdZdZdFShM,36419
+ostruct/cli/security/symlink_resolver.py,sha256=wtZdJ_T_0FOy6B1P5ty1odEXQk9vr8BzlWeAFD4huJE,16744
+ostruct/cli/security/types.py,sha256=38qBfUSaYB0NXyOq9DytTg4OnievLSsA4ysI88YdaFY,3545
+ostruct/cli/security/windows_paths.py,sha256=qxC2H2kLwtmQ7YePYde3UrmOJcGnsLEebDLh242sUaI,13453
+ostruct/cli/sentinel.py,sha256=69faYPrhVJmEpYNLsCtf1HF96aan3APqXZdIjxBNZYo,798
+ostruct/cli/serialization.py,sha256=ec0UswDE2onwtZVUoZaMCsGv6zW_tSKdBng2qVo6Ucs,704
+ostruct/cli/services.py,sha256=nLYUbF3DDNuilh7j9q_atUOjTAWta7bxTS3G-zkveaA,21621
+ostruct/cli/template_debug.py,sha256=PEU9w10lIWPaMHbY2_uPr2HwM3154V1aIJ8mc_A5rSQ,25283
+ostruct/cli/template_debug_help.py,sha256=KqKYFIbE81HxTHWT-A2naLdk8PUsTNHTXkLusleGUD4,9178
+ostruct/cli/template_env.py,sha256=mxJPoA4DwbJKQIg2wLmqEsXarR1HrDiR8PhwKNKnAEQ,3535
+ostruct/cli/template_extensions.py,sha256=_lomtDGMGxMfpw05v_-daJ0JbhRm_r_-uEJlPAjbpkI,2699
+ostruct/cli/template_filters.py,sha256=ulo5jRo62zmkApYvDUjO5imUS5osec7eoeYwJsbuMKk,34566
+ostruct/cli/template_io.py,sha256=yUWO-8rZnSdX97DTMSEX8fG9CP1ISsOhm2NZN3Fab9A,8821
+ostruct/cli/template_processor.py,sha256=Y9GMCuA5lASse_AzDCgu8VdcmsAhxQn8qyG546cvBE0,30150
+ostruct/cli/template_rendering.py,sha256=at8RiT9v0peJUBRwDgX1-WJ6pDDMDO0H33MwuWlkowM,15831
+ostruct/cli/template_schema.py,sha256=ckH4rUZnEgfm_BHS9LnMGr8LtDxRmZ0C6UBVrSp8KTc,19604
+ostruct/cli/template_utils.py,sha256=MZdXXjL-x-IXX-5Y8GWopGNBkDE2ItLdCuCl0QWFR_U,14968
+ostruct/cli/template_validation.py,sha256=3wUBoZJZKt0C5TVaT0nmjH_ehyw4Gn1yEBnMDDE8qLU,14327
+ostruct/cli/token_utils.py,sha256=r4KPEO3Sec18Q6mU0aClK6XGShvusgUggXEQgEPPlaA,1369
+ostruct/cli/token_validation.py,sha256=DGc5yyScy0iTvvuF2DaDUgRQaIqVIcm9ZZtuVEyy_oI,10276
+ostruct/cli/types.py,sha256=qQ5mc4OAK8ChVrgaJ9VSn3gS75byrOonjlsc9WdgibE,2782
+ostruct/cli/unattended_operation.py,sha256=kI95SSVJC_taxORXQYrce_qLEnuKc6edwn9tMOye-qs,9383
+ostruct/cli/unicode_compat.py,sha256=bDeVZdWkDv74jVt4AsBl10tRra0v7kV04SNAMyR3q0U,9508
+ostruct/cli/upload_manager.py,sha256=m8BpVRJc7Ag9Ln5bAQPGMtisHSP0m7VVcXhHnqZ5CjI,16368
+ostruct/cli/utils.py,sha256=DV8KAx46rl3GgXLydVhrP6A1xY7ofyir3hEKUslSfek,2149
+ostruct/cli/validators.py,sha256=SRJozxcXgIdbjF0Jv5z2rSbOzeXiTYpzbZKc_WF-5HE,23882
+ostruct/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ostruct_cli-1.0.0.dist-info/LICENSE,sha256=DmGAkaYzhrdzTB9Y2Rvfzd3mJiF9ZrTOhxN8t6wrfHA,1098
+ostruct_cli-1.0.0.dist-info/METADATA,sha256=X6YXB3suiMvexCSUvF0FQUpJk6iotxfF00-F3vmeXqQ,31311
+ostruct_cli-1.0.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+ostruct_cli-1.0.0.dist-info/entry_points.txt,sha256=NFq9IuqHVTem0j9zKjV8C1si_zGcP1RL6Wbvt9fUDXw,48
+ostruct_cli-1.0.0.dist-info/RECORD,,