diff --git a/README.md b/README.md
index ec4d52f..7813f18 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,263 @@
-# api-mock-cli
+# API Mock CLI
 
-A CLI tool to create shareable local mock servers from API definitions with routing, validation, and templating support
\ No newline at end of file
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/downloads/)
+[![Test Status](https://img.shields.io/badge/tests-passing-green)](https://7000pct.gitea.bloupla.net/7000pctAUTO/api-mock-cli/actions)
+
+A powerful CLI tool that converts API definitions into shareable local mock servers. Developers provide endpoint definitions with response templates, and the tool automatically generates a fully functional mock server with intelligent routing, request validation, and dynamic response templating.
+
+## Features
+
+- **Automatic Mock Server**: Spin up a FastAPI-based mock server from YAML/JSON endpoint definitions
+- **Smart Endpoint Routing**: Pattern matching for endpoints including path parameters and HTTP methods
+- **Shareable Local URLs**: Expose your local server via ngrok tunneling for team collaboration
+- **Request Validation**: Validate incoming requests against JSON schemas
+- **Dynamic Response Templating**: Generate responses using Jinja2 variable substitution
+- **Offline Mode**: Run without external dependencies for testing environments
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install api-mock-cli
+```
+
+Or from source:
+
+```bash
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/api-mock-cli.git
+cd api-mock-cli
+pip install -e .
+```
+
+### Basic Usage
+
+1. **Initialize a new mock project:**
+
+```bash
+api-mock init --name my-api
+cd my-api
+```
+
+2. **Start the mock server:**
+
+```bash
+api-mock start
+```
+
+3. **Test your endpoints:**
+
+```bash
+curl http://localhost:8000/api/hello
+```
+
+## Commands
+
+### init
+
+Create a new mock project structure with predefined templates.
+
+```bash
+api-mock init --name my-api [--template basic|full|minimal]
+```
+
+**Options:**
+- `--name` (required): Name of the mock project
+- `--template`: Project template (default: basic)
+  - `basic`: Simple single-endpoint setup
+  - `full`: Multi-endpoint with validation examples
+  - `minimal`: Bare-bones structure
+
+### start
+
+Start the mock server with optional configuration.
+
+```bash
+api-mock start [--port 8000] [--host 0.0.0.0] [--offline] [--reload]
+```
+
+**Options:**
+- `--port`: Server port (default: 8000)
+- `--host`: Server host (default: 0.0.0.0)
+- `--offline`: Disable ngrok tunneling
+- `--reload`: Enable auto-reload on file changes
+
+### stop
+
+Stop the running mock server.
+
+```bash
+api-mock stop
+```
+
+### generate
+
+Generate a new endpoint definition file.
+
+```bash
+api-mock generate EndpointName --method GET --path /api/endpoint
+```
+
+**Options:**
+- `EndpointName` (required): Name for the new endpoint
+- `--method`: HTTP method (GET, POST, PUT, DELETE, PATCH)
+- `--path`: URL path for the endpoint
+
+## Configuration
+
+Create a `config.yaml` file in your project root:
+
+```yaml
+name: my-mock-api
+version: 1.0.0
+server:
+  port: 8000
+  host: 0.0.0.0
+  tunnel: true
+  offline: false
+  reload: true
+  log_level: info
+```
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `API_MOCK_PORT` | Server port | 8000 |
+| `API_MOCK_HOST` | Server host | 0.0.0.0 |
+| `API_MOCK_OFFLINE` | Run without tunneling | false |
+| `NGROK_AUTHTOKEN` | ngrok authentication token | - |
+| `API_MOCK_LOG_LEVEL` | Logging level | info |
+
+## Endpoint Definition
+
+Define endpoints in `endpoints.yaml`:
+
+```yaml
+version: "1.0.0"
+endpoints:
+  - path: /api/users/{id}
+    method: GET
+    name: Get User
+    description: Retrieve a user by ID
+    response:
+      status_code: 200
+      body:
+        id: "{{request.path.id}}"
+        name: "John Doe"
+        email: "john@example.com"
+    validators:
+      body:
+        type: object
+        required: [name, email]
+        properties:
+          name: {type: string, minLength: 1}
+          email: {type: string, format: email}
+```
+
+### Response Templating
+
+Use Jinja2 templates for dynamic responses:
+
+| Template | Description |
+|----------|-------------|
+| `{{request.path.id}}` | Path parameters |
+| `{{request.query.page}}` | Query parameters |
+| `{{request.body.name}}` | Request body fields |
+| `{{request.headers.Authorization}}` | Request headers |
+| `{{uuid}}` | Generate UUID v4 |
+| `{{timestamp}}` | Current ISO timestamp |
+| `{{random_int(1, 100)}}` | Random integer in range |
+| `{{random_choice}}` | Random item from list |
+
+### Response Headers
+
+```yaml
+response:
+  status_code: 201
+  headers:
+    Content-Type: application/json
+    X-Request-Id: "{{uuid}}"
+  body:
+    success: true
+```
+
+### Status Codes
+
+```yaml
+response:
+  status_code: 404
+  body:
+    error: "Resource not found"
+```
+
+## Project Structure
+
+```
+my-api/
+├── config.yaml
+├── endpoints.yaml
+├── responses/
+│   └── user.json
+├── schemas/
+│   └── user.json
+└── README.md
+```
+
+## Offline Mode
+
+Run the mock server without ngrok tunnel for internal networks or testing:
+
+```bash
+api-mock start --offline
+```
+
+## Installation for Development
+
+```bash
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/api-mock-cli.git
+cd api-mock-cli
+
+python -m venv venv
+source venv/bin/activate
+
+pip install -e ".[dev]"
+
+pytest tests/ -v
+ruff check .
+```
+
+## Tech Stack
+
+- **FastAPI**: Web framework for building APIs
+- **Click**: CLI framework
+- **Uvicorn**: ASGI server
+- **Pydantic**: Data validation
+- **PyNgrok**: ngrok integration for tunneling
+- **Jinja2**: Template engine
+- **PyYAML**: YAML parsing
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Changelog
+
+### v0.1.0 (2024-01-29)
+
+- Initial release
+- Basic mock server functionality
+- Endpoint routing with path parameters
+- Request validation support
+- Response templating with Jinja2
+- ngrok tunnel integration
+- CLI commands: init, start, stop, generate