diff --git a/README.md b/README.md
index 1a7f0af..5f246d0 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,201 @@
-# envschema
+# EnvSchema
 
-A CLI tool that validates environment variables against a JSON/YAML schema file
\ No newline at end of file
+[![CI](https://7000pct.gitea.bloupla.net/7000pctAUTO/envschema/actions/workflows/ci.yml/badge.svg)](https://7000pct.gitea.bloupla.net/7000pctAUTO/envschema/actions)
+[![PyPI version](https://img.shields.io/pypi/v/envschema.svg)](https://pypi.org/project/envschema/)
+[![Python versions](https://img.shields.io/pypi/pyversions/envschema.svg)](https://pypi.org/project/envschema/)
+[![License](https://img.shields.io/pypi/l/envschema.svg)](https://opensource.org/licenses/MIT)
+
+A CLI tool that validates environment variables against a JSON/YAML schema file. Developers define expected env vars with types, defaults, required flags, and descriptions in a schema. The tool validates actual .env files or runtime environment against this schema, catching type mismatches, missing required vars, and providing helpful error messages.
+
+## Features
+
+- Schema validation with type checking (str, int, bool, list)
+- Missing required variable detection
+- `.env.example` generation from schema
+- CI/CD integration for pre-deployment checks
+- Support for JSON and YAML schema formats
+- Pattern validation with regex support
+
+## Installation
+
+```bash
+pip install envschema
+```
+
+Or install from source:
+
+```bash
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/envschema.git
+cd envschema
+pip install -e .
+```
+
+## Quick Start
+
+1. Create a schema file (`.env.schema.json` or `.env.schema.yaml`):
+
+```json
+{
+  "version": "1.0",
+  "envVars": [
+    {
+      "name": "DATABASE_URL",
+      "type": "str",
+      "required": true,
+      "description": "PostgreSQL connection string"
+    },
+    {
+      "name": "DEBUG_MODE",
+      "type": "bool",
+      "required": false,
+      "default": "false"
+    }
+  ]
+}
+```
+
+2. Validate your `.env` file:
+
+```bash
+envschema validate .env.schema.json --file .env
+```
+
+## CLI Commands
+
+### validate
+
+Validate environment variables against a schema:
+
+```bash
+envschema validate SCHEMA [--file PATH] [--env/--no-env] [--format text|json] [--ci] [--strict]
+```
+
+Options:
+- `SCHEMA`: Path to the schema file (JSON or YAML)
+- `--file`, `-f`: Path to .env file to validate
+- `--env/--no-env`: Include os.environ in validation (default: true)
+- `--format`, `-o`: Output format (text or json, default: text)
+- `--ci`: CI mode (cleaner output)
+- `--strict`: Fail on warnings
+
+### generate
+
+Generate `.env.example` from a schema:
+
+```bash
+envschema generate SCHEMA [--output PATH] [--no-comments]
+```
+
+Options:
+- `SCHEMA`: Path to the schema file
+- `--output`, `-o`: Output file path (default: .env.example)
+- `--no-comments`: Don't include description comments
+
+### check
+
+Validate a schema file:
+
+```bash
+envschema check SCHEMA
+```
+
+## Schema Format
+
+### JSON Schema
+
+```json
+{
+  "version": "1.0",
+  "envVars": [
+    {
+      "name": "VAR_NAME",
+      "type": "str|int|bool|list",
+      "required": true|false,
+      "default": "default_value",
+      "description": "Variable description",
+      "pattern": "regex_pattern"
+    }
+  ]
+}
+```
+
+### YAML Schema
+
+```yaml
+version: "1.0"
+envVars:
+  - name: VAR_NAME
+    type: str
+    required: true
+    default: "value"
+    description: Variable description
+    pattern: "^[A-Z]+$"
+```
+
+## Supported Types
+
+- `str`: String (always valid)
+- `int`: Integer (validates numeric values)
+- `bool`: Boolean (true, false, 1, 0, yes, no, on, off)
+- `list`: Comma-separated list of values
+
+## Examples
+
+### Validate with environment variables
+
+```bash
+export DATABASE_URL="postgres://localhost/mydb"
+export DEBUG_MODE="true"
+envschema validate schema.json
+```
+
+### Validate with .env file
+
+```bash
+envschema validate schema.json --file .env
+```
+
+### CI/CD Integration
+
+```bash
+envschema validate schema.json --file .env --ci --format json
+```
+
+Exit codes:
+- 0: Validation passed
+- 1: Validation failed
+- 2: Error (schema not found, invalid format)
+
+### Generate .env.example
+
+```bash
+envschema generate schema.json
+# Generates .env.example
+
+envschema generate schema.json --output .env.dev
+```
+
+## API Reference
+
+```python
+from envschema import Schema, ValidationEngine, EnvLoader
+
+# Load schema
+schema = Schema.load("schema.json")
+
+# Load environment
+loader = EnvLoader(".env")
+env_vars = loader.load()
+
+# Validate
+engine = ValidationEngine(schema)
+result = engine.validate(env_vars)
+
+if not result.is_valid:
+    print(result.missing_required)
+    print(result.type_errors)
+```
+
+## License
+
+MIT License - see LICENSE file for details.
\ No newline at end of file