docs: use positional syntax in all examples

Replace -i flag with positional argument syntax throughout:
- README.md and prompts/trickery_readme.md
- docs/images.md and docs/image-generation.md
- specs/text-input.md
- All test case files
- src/main.rs help examples

Positional is now the preferred syntax, with -i kept for
backwards compatibility only.

Author: claude

README.md

@@ -8,7 +8,7 @@ Idea is simple, imagine you need to generate some docs using LLM as part of CI,
 
 > [!TIP]
 > This README was generated with trickery
-> trickery generate -i ./prompts/trickery_readme.md > README.md
+> trickery generate ./prompts/trickery_readme.md > README.md
 
 
 ## Demo
@@ -28,7 +28,17 @@ trickery --help
 
 ```sh
 export OPENAI_API_KEY=s....d
-trickery generate -i ./prompts/trickery_readme.md > README.md
+trickery generate ./prompts/trickery_readme.md > README.md
+```
+
+### Using with OpenAI-compatible gateways
+
+You can use trickery with any OpenAI-compatible API gateway (like LiteLLM, Azure OpenAI, or local models) by setting the `OPENAI_BASE_URL` environment variable:
+
+```sh
+export OPENAI_API_KEY=your-key
+export OPENAI_BASE_URL=http://localhost:4000/v1
+trickery generate ./prompts/my_prompt.md
 ```
 
 Input file could be any text file, with Jinja2-like template variables, like `{{"{{app_version}}"}}`. To set this variables, please use `-v` flag, like `-v app_version=1.0.0`.

docs/image-generation.md

@@ -4,9 +4,9 @@ Trickery supports generating and editing images using OpenAI's Responses API wit
 
 ## CLI Arguments
 
-### `--input <PATH>` / `-i <PATH>`
+### `[INPUT]` (positional) or `-i <INPUT>`
 
-Path to the prompt template file. Supports Jinja2-style `{{ variable }}` substitution.
+Input prompt: file path or direct text (auto-detected). Supports Jinja2-style `{{ variable }}` substitution when using a file.
 
 ### `--save <PATH>` / `-s <PATH>` (optional)
 
@@ -80,13 +80,13 @@ Template variables for prompt substitution.
 
 ```bash
 # Simple generation with explicit filename
-trickery image -i prompts/generate_diagram.md --save docs/images/colorful-architecture.png
+trickery image prompts/generate_diagram.md --save docs/images/colorful-architecture.png
 
 # Auto-generated filename (e.g., generate_diagram-a3f5x.png)
-trickery image -i prompts/generate_diagram.md
+trickery image prompts/generate_diagram.md
 
 # With quality settings
-trickery image -i prompts/generate_diagram.md -s architecture.png \
+trickery image prompts/generate_diagram.md -s architecture.png \
   --size 1536x1024 \
   --quality high
 ```
@@ -101,12 +101,12 @@ See [prompts/generate_diagram.md](../prompts/generate_diagram.md) for the prompt
 
 ```bash
 # Make an image look realistic
-trickery image -i prompts/make_realistic.md \
+trickery image prompts/make_realistic.md \
   --image test_data/example_images/image1.png \
   --save output.png
 
 # Edit with custom instruction
-trickery image -i prompts/edit_image.md \
+trickery image prompts/edit_image.md \
   --image test_data/example_images/image2.png \
   --save modified.png \
   -v instruction="make it green on pink"
@@ -117,7 +117,7 @@ See [prompts/make_realistic.md](../prompts/make_realistic.md) and [prompts/edit_
 ### Highlight Areas in Image
 
 ```bash
-trickery image -i prompts/highlight_humans.md \
+trickery image prompts/highlight_humans.md \
   --image test_data/example_images/image3.jpg \
   --save highlighted.png
 ```
@@ -127,7 +127,7 @@ See [prompts/highlight_humans.md](../prompts/highlight_humans.md) for the prompt
 ### With Template Variables
 
 ```bash
-trickery image -i prompts/generate_icon.md \
+trickery image prompts/generate_icon.md \
   --save icon.png \
   -v subject="rocket" \
   -v style="flat design"
@@ -139,7 +139,7 @@ See [prompts/generate_icon.md](../prompts/generate_icon.md) for the prompt templ
 
 ```bash
 # Combine elements from multiple images
-trickery image -i prompts/edit_image.md \
+trickery image prompts/edit_image.md \
   --image test_data/example_images/image1.png \
   --image test_data/example_images/image2.png \
   --save composite.png \
@@ -149,7 +149,7 @@ trickery image -i prompts/edit_image.md \
 ### Transparent Background
 
 ```bash
-trickery image -i prompts/generate_icon.md \
+trickery image prompts/generate_icon.md \
   --save logo.png \
   --background transparent \
   --format png \
@@ -160,7 +160,7 @@ trickery image -i prompts/generate_icon.md \
 ### JSON Output
 
 ```bash
-trickery image -i prompts/generate_diagram.md --save result.png -o json
+trickery image prompts/generate_diagram.md --save result.png -o json
 ```
 
 Output:

docs/input-images.md

@@ -34,7 +34,7 @@ Unknown extensions default to PNG MIME type.
 ### Single Local Image
 
 ```bash
-trickery generate -i prompts/describe_image.md --image test_data/example_images/image2.png
+trickery generate prompts/describe_image.md --image test_data/example_images/image2.png
 ```
 
 Where `prompts/describe_image.md` contains:
@@ -45,13 +45,13 @@ Describe what you see in this image in detail.
 ### Image from URL
 
 ```bash
-trickery generate -i prompts/describe_image.md --image https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png
+trickery generate prompts/describe_image.md --image https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png
 ```
 
 ### Multiple Images
 
 ```bash
-trickery generate -i prompts/catalog_images.md \
+trickery generate prompts/catalog_images.md \
   --image test_data/example_images/image1.png \
   --image test_data/example_images/image2.png \
   --image test_data/example_images/image3.jpg
@@ -61,13 +61,13 @@ trickery generate -i prompts/catalog_images.md \
 
 ```bash
 # Low detail for quick classification
-trickery generate -i prompts/describe_image.md --image test_data/example_images/image1.png --image-detail low
+trickery generate prompts/describe_image.md --image test_data/example_images/image1.png --image-detail low
 ```
 
 ### Combined with Variables
 
 ```bash
-trickery generate -i prompts/review_ui.md \
+trickery generate prompts/review_ui.md \
   --image test_data/example_images/image2.png \
   --var focus="accessibility" \
   --var format="bullet points"
@@ -100,7 +100,7 @@ Image support requires a vision-capable model. Recommended models:
 
 Example with explicit model:
 ```bash
-trickery generate -i prompts/describe_image.md --image test_data/example_images/image1.png --model gpt-5.2
+trickery generate prompts/describe_image.md --image test_data/example_images/image1.png --model gpt-5.2
 ```
 
 ## Token Considerations

prompts/trickery_readme.md

@@ -19,7 +19,7 @@ Idea is simple, imagine you need to generate some docs using LLM as part of CI,
 
 > [!TIP]
 > This README was generated with trickery
-> trickery generate -i ./prompts/trickery_readme.md > README.md
+> trickery generate ./prompts/trickery_readme.md > README.md
 
 
 ## Demo
@@ -39,7 +39,7 @@ trickery --help
 
 ```sh
 export OPENAI_API_KEY=s....d
-trickery generate -i ./prompts/trickery_readme.md > README.md
+trickery generate ./prompts/trickery_readme.md > README.md
 ```
 
 Input file could be any text file, with Jinja2-like template variables, like `{{"{{app_version}}"}}`. To set this variables, please use `-v` flag, like `-v app_version=1.0.0`.

specs/text-input.md

@@ -2,17 +2,20 @@
 
 ## Abstract
 
-Trickery's input supports both file paths and direct text, with auto-detection. If the provided value exists as a file, it reads from the file; otherwise, it treats the value as direct prompt text. Input can be provided as a positional argument or with the `-i` flag.
+Trickery's input supports both file paths and direct text, with auto-detection. If the provided value exists as a file, it reads from the file; otherwise, it treats the value as direct prompt text. Input is typically provided as a positional argument.
 
 ## Requirements
 
 ### Input Methods
 
-Two equivalent ways to provide input:
-1. **Positional argument**: `trickery generate "prompt text"`
-2. **Named option**: `trickery generate -i "prompt text"`
+Input is provided as a positional argument:
 
-Both work identically. Positional is preferred for brevity.
+```bash
+trickery generate "prompt text"
+trickery generate prompts/greeting.md
+```
+
+The `-i` flag is also supported for backwards compatibility but positional is preferred.
 
 ### Input Auto-Detection
 
@@ -26,19 +29,17 @@ Once input is provided (either way), this logic applies:
 ```bash
 # File input (file exists, content read from file)
 trickery generate prompts/greeting.md
-trickery generate -i prompts/greeting.md
 
 # Text input (not a file, used as direct prompt)
 trickery generate "Write a haiku"
-trickery generate -i "Write a haiku"
 ```
 
 - Template variables work with both: `--var name=Alice`
 - For `image` command, output filename defaults to `image-xxxxx.png` when input is text
 
 ### Long Text Support
 
-Both positional and `-i` support:
+Positional input supports:
 
 - Multi-line strings (using shell quoting)
 - Special characters and Unicode
@@ -67,11 +68,10 @@ EOF
 
 ## Design Choices
 
-### Why support both positional and -i?
+### Why keep -i as fallback?
 
-1. Positional is more natural for quick one-liners
-2. `-i` flag maintains backwards compatibility
-3. `-i` is clearer when input looks like a flag (edge case)
+1. Backwards compatibility with older scripts
+2. Useful when input looks like a flag (edge case)
 
 ### Why auto-detect instead of separate options?
 

src/main.rs

@@ -152,13 +152,12 @@ the given path, it reads from the file; otherwise treats input as direct text.
 
 **Usage:**
 ```bash
-trickery generate [INPUT]           # positional argument
-trickery generate -i <INPUT>        # or use -i flag
+trickery generate [INPUT] [OPTIONS]
 ```
 
 **Options:**
-- `<INPUT>`: Prompt input as positional arg - file path or direct text (auto-detected)
-- `-i, --input <INPUT>`: Same as positional, alternative syntax
+- `[INPUT]`: Prompt input - file path or direct text (auto-detected)
+- `-i, --input <INPUT>`: Alternative to positional (for backwards compatibility)
 - `-v, --var <KEY=VALUE>`: Variables to be used in prompt (can be repeated)
 - `-m, --model <MODEL>`: Model to use (e.g., gpt-5.2, gpt-5-mini, o1, o3-mini)
 - `-r, --reasoning <LEVEL>`: Reasoning level for o1/o3 models: low, medium, high
@@ -169,18 +168,12 @@ trickery generate -i <INPUT>        # or use -i flag
 **Examples:**
 
 ```bash
-# From a prompt file (positional)
+# From a prompt file
 trickery generate prompts/greeting.md
 
-# From a prompt file (with -i flag)
-trickery generate -i prompts/greeting.md
-
-# Direct text input (positional)
+# Direct text input
 trickery generate "Write a haiku about programming"
 
-# Direct text input (with -i flag)
-trickery generate -i "Write a haiku about programming"
-
 # Long text with shell quoting
 trickery generate "You are a helpful assistant.
 
@@ -211,13 +204,12 @@ at the given path, it reads from the file; otherwise treats input as direct text
 
 **Usage:**
 ```bash
-trickery image [INPUT]           # positional argument
-trickery image -i <INPUT>        # or use -i flag
+trickery image [INPUT] [OPTIONS]
 ```
 
 **Options:**
-- `<INPUT>`: Prompt input as positional arg - file path or direct text (auto-detected)
-- `-i, --input <INPUT>`: Same as positional, alternative syntax
+- `[INPUT]`: Prompt input - file path or direct text (auto-detected)
+- `-i, --input <INPUT>`: Alternative to positional (for backwards compatibility)
 - `-s, --save <FILE>`: Output file path (auto-generated if not provided)
 - `-v, --var <KEY=VALUE>`: Variables to be used in prompt (can be repeated)
 - `-m, --model <MODEL>`: Model to use (e.g., gpt-4.1, gpt-5, gpt-5.2)
@@ -232,15 +224,12 @@ trickery image -i <INPUT>        # or use -i flag
 **Examples:**
 
 ```bash
-# From a prompt file (positional)
+# From a prompt file
 trickery image prompts/logo.md
 
-# Direct text input (positional)
+# Direct text input
 trickery image "A cute cartoon cat sitting on a rainbow"
 
-# With -i flag
-trickery image -i prompts/logo.md
-
 # Long descriptive prompt
 trickery image "A professional logo for a tech startup called 'CloudSync'.
 Modern, minimalist design with blue and white colors."
@@ -300,7 +289,7 @@ Keep it concise and friendly.
 
 **Usage:**
 ```bash
-trickery generate -i prompts/email.md --var name="Alice" --var topic="quarterly review"
+trickery generate prompts/email.md --var name="Alice" --var topic="quarterly review"
 ```
 
 ## Exit Codes
@@ -376,8 +365,8 @@ mod tests {
     fn test_full_help_contains_examples() {
         let full_help = include_str!("main.rs");
         // Verify examples are present
-        assert!(full_help.contains("trickery generate -i"));
-        assert!(full_help.contains("trickery image -i"));
+        assert!(full_help.contains("trickery generate prompts/"));
+        assert!(full_help.contains("trickery image prompts/"));
         assert!(full_help.contains("trickery completion bash"));
         assert!(full_help.contains("--var name="));
     }

test_cases/basic_generation.md

@@ -10,13 +10,13 @@ Validates that trickery can generate output from a simple prompt file without va
 ## Steps
 
 ### 1. Generate from simple prompt
-**Run:** `trickery generate -i prompts/dad_jokes.md`
+**Run:** `trickery generate prompts/dad_jokes.md`
 **Expect:** LLM response printed to stdout (a dad joke)
 
 ### 2. Generate with model selection
-**Run:** `trickery generate -i prompts/dad_jokes.md -m gpt-4o-mini`
+**Run:** `trickery generate prompts/dad_jokes.md -m gpt-4o-mini`
 **Expect:** LLM response from specified model
 
 ### 3. Generate with max tokens limit
-**Run:** `trickery generate -i prompts/dad_jokes.md --max-tokens 50`
+**Run:** `trickery generate prompts/dad_jokes.md --max-tokens 50`
 **Expect:** Response truncated to approximately 50 tokens

test_cases/error_handling.md

@@ -8,22 +8,18 @@ Validates proper error messages for invalid inputs and missing requirements.
 
 ## Steps
 
-### 1. Missing input file
+### 1. Missing input
 **Run:** `trickery generate`
-**Expect:** Error: "Input file path is required"
+**Expect:** Error: "Input is required"
 
-### 2. Non-existent file
-**Run:** `trickery generate -i nonexistent.md`
-**Expect:** Error: "Failed to read input file 'nonexistent.md': No such file"
-
-### 3. Missing API key
-**Run:** `unset OPENAI_API_KEY && trickery generate -i prompts/dad_jokes.md`
+### 2. Missing API key
+**Run:** `unset OPENAI_API_KEY && trickery generate prompts/dad_jokes.md`
 **Expect:** Error indicating missing or invalid API key
 
-### 4. Invalid variable format
-**Run:** `trickery generate -i prompts/dad_jokes.md --var invalidformat`
+### 3. Invalid variable format
+**Run:** `trickery generate prompts/dad_jokes.md --var invalidformat`
 **Expect:** Error: "invalid KEY=VALUE: no `=` found"
 
-### 5. Invalid reasoning level
-**Run:** `trickery generate -i prompts/dad_jokes.md -r invalid`
+### 4. Invalid reasoning level
+**Run:** `trickery generate prompts/dad_jokes.md -r invalid`
 **Expect:** Error about invalid reasoning level value