diff --git a/README.md b/README.md
index c380f80..608db4c 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,159 @@
 # cmdparse
 
-A CLI tool that parses unstructured CLI command output into structured formats (JSON, CSV, YAML) with field extraction capabilities.
\ No newline at end of file
+A CLI tool that parses unstructured CLI command output into structured formats (JSON, CSV, YAML) with field extraction capabilities.
+
+## Features
+
+- Parse stdin CLI output to JSON/CSV/YAML
+- Auto-detect common output patterns (tables, key-value, delimited)
+- Simple field extraction syntax with dot notation
+- Custom parser definitions via config file
+- Works seamlessly with any Unix pipe
+
+## Installation
+
+```bash
+pip install cmdparse
+```
+
+Or from source:
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+### Basic Usage
+
+```bash
+# Parse table output to JSON
+echo -e "NAME    IMAGE    STATUS\nnginx   nginx:1   running" | cmdparse
+
+# Output as YAML
+cat file.txt | cmdparse -o yaml
+
+# Output as CSV
+cat file.txt | cmdparse -o csv
+```
+
+### Field Extraction
+
+```bash
+# Extract specific fields
+echo -e "NAME    IMAGE    STATUS\nnginx   nginx:1   running" | cmdparse -e NAME -e STATUS
+
+# Use dot notation for nested fields
+```
+
+### Input Format Detection
+
+```bash
+# Auto-detect format (default)
+cat file.txt | cmdparse
+
+# Force specific format
+cat file.txt | cmdparse -f table
+cat file.txt | cmdparse -f key_value
+cat file.txt | cmdparse -f delimited
+```
+
+### Configuration File
+
+```bash
+# Use custom config file
+cat file.txt | cmdparse -c /path/to/config.yaml
+```
+
+## Input Formats
+
+cmdparse automatically detects and parses these formats:
+
+### Table Format
+```
+NAME    IMAGE    STATUS
+nginx   nginx:1   running
+redis   redis:3   stopped
+```
+
+### Key-Value Format (colon)
+```
+name: John
+age: 30
+city: NYC
+```
+
+### Key-Value Format (equals)
+```
+name=John
+age=30
+city=NYC
+```
+
+### Delimited (CSV)
+```
+name,age,city
+John,30,NYC
+Jane,25,LA
+```
+
+### Tab-Delimited (TSV)
+```
+name	age	city
+John	30	NYC
+```
+
+## Output Formats
+
+- `json` - JSON output (default)
+- `yaml` - YAML output
+- `csv` - CSV output
+- `raw` - Raw text representation
+
+## Configuration
+
+Create a `~/.cmdparse.yaml` or `.cmdparse.yaml` in your project with custom parser definitions:
+
+```yaml
+parsers:
+  - name: docker_ps
+    pattern: "NAME.*PORTS"
+    fields:
+      - CONTAINER_ID
+      - IMAGE
+      - STATUS
+      - NAMES
+```
+
+## Unix Pipeline Examples
+
+```bash
+# Parse docker ps output
+docker ps | cmdparse -o json
+
+# Extract specific columns from any table-like output
+df -h | cmdparse -e Filesystem -e Size -e Use%
+
+# Parse key-value config output
+env | cmdparse -f key_value -o yaml
+
+# Process CSV data
+cat data.csv | cmdparse -o json
+```
+
+## Development
+
+```bash
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest -v
+
+# Run with coverage
+pytest --cov=cmdparse
+```
+
+## License
+
+MIT License