diff --git a/README.md b/README.md
index 5eeb365..da2ff24 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,164 @@
-# localapi-docs
+# LocalAPI Docs
 
-A CLI tool that generates local, privacy-focused API documentation server from OpenAPI/Swagger specs with interactive endpoint testing
\ No newline at end of file
+A CLI tool that generates local, privacy-focused API documentation server from OpenAPI/Swagger specs with interactive endpoint testing, automatic examples, and multiple output formats running entirely locally.
+
+## Features
+
+- **Local Documentation Server** - Serve interactive HTML docs locally with no external dependencies
+- **Multiple Output Formats** - Generate HTML, Markdown, or JSON documentation
+- **Automatic Example Generation** - Creates realistic request/response examples from your schemas
+- **Full-Text Search** - Search across endpoints, tags, and descriptions
+- **Spec Validation** - Validate OpenAPI specs with detailed error messages
+- **Privacy-Focused** - Everything runs locally, no data leaves your machine
+
+## Installation
+
+```bash
+# Install from source
+pip install -e .
+
+# Or install with dev dependencies
+pip install -e .[dev]
+```
+
+## Usage
+
+### Serve Interactive Documentation
+
+Start a local web server with interactive API documentation:
+
+```bash
+localapi-docs serve petstore.json
+localapi-docs serve petstore.yaml --host 0.0.0.0 --port 8080
+```
+
+The server will automatically open in your default browser.
+
+### Generate Static Documentation
+
+Generate documentation in various formats:
+
+```bash
+# Generate HTML documentation
+localapi-docs generate petstore.json --format html
+
+# Generate Markdown documentation
+localapi-docs generate petstore.json --format markdown
+
+# Generate JSON documentation
+localapi-docs generate petstore.json --format json
+
+# Generate all formats
+localapi-docs generate petstore.json --format all
+```
+
+### Validate OpenAPI Specs
+
+Validate your OpenAPI specification file:
+
+```bash
+localapi-docs validate petstore.json
+localapi-docs validate petstore.yaml --json
+```
+
+### Search Endpoints
+
+Search for endpoints in your API specification:
+
+```bash
+localapi-docs search petstore.json users
+localapi-docs search petstore.json "get pet" --limit 10
+localapi-docs search petstore.json users --json
+```
+
+## Commands
+
+### serve
+
+Start an interactive HTML documentation server.
+
+Options:
+- `--host, -h`: Host to bind to (default: 127.0.0.1)
+- `--port, -p`: Port to serve on (default: 8080)
+- `--no-browser`: Don't open browser automatically
+
+### generate
+
+Generate static documentation in various formats.
+
+Options:
+- `--output, -o`: Output file or directory
+- `--format, -f`: Output format (html, markdown, json, all)
+- `--open`: Open the generated file in browser
+
+### validate
+
+Validate an OpenAPI specification file.
+
+Options:
+- `--json`: Output as JSON
+
+### search
+
+Search for endpoints in an OpenAPI specification.
+
+Options:
+- `--limit, -l`: Maximum results (default: 10)
+- `--json`: Output as JSON
+
+## Examples
+
+### Generate and Open HTML Docs
+
+```bash
+localapi-docs generate api-spec.yaml --format html --open
+```
+
+### Serve on Custom Port
+
+```bash
+localapi-docs serve api-spec.json --port 3000
+```
+
+### Validate with JSON Output
+
+```bash
+localapi-docs validate api-spec.json --json
+```
+
+### Search and Get JSON Results
+
+```bash
+localapi-docs search api-spec.json users --json
+```
+
+## Configuration
+
+No configuration files required. All options are passed via CLI arguments.
+
+## Development
+
+```bash
+# Install development dependencies
+pip install -e .[dev]
+
+# Run tests
+pytest tests/ -v
+
+# Run with coverage
+pytest tests/ --cov=src --cov-report=term-missing
+```
+
+## Supported OpenAPI Versions
+
+- OpenAPI 3.0.x
+- OpenAPI 3.1.x
+
+## Input Formats
+
+- JSON (`.json`)
+- YAML (`.yaml`, `.yml`)
+
+## License
+
+MIT