docs: update readme

README.md

@@ -1,5 +1,102 @@
+<div align="center">
+
 # cl-parse
 
 Parse _most_ changelog formats into common structured data formats.
 
 ![is_this_structured_data](https://github.com/user-attachments/assets/765b6aee-405b-46e7-8282-a7bb8e6f2e87)
+
+</div>
+
+`cl-parse` is a command-line tool that converts various changelog formats into structured data (JSON, YAML, or TOML). It supports changelogs generated by popular tools like `release-please` and `semantic-release`, making it easier to programmatically work with changelog data.
+
+## Features
+
+- Parses conventional changelog formats
+- Supports multiple output formats (JSON, YAML, TOML)
+- Can fetch additional context from:
+    - Full commit messages
+    - Linked GitHub Issues
+    - GitHub Pull Requests
+    - Azure DevOps Work Items
+    - GitLab Issues and Merge Requests
+
+## Supported Providers
+
+- GitHub (`github.com`)
+- Azure DevOps (`dev.azure.com`)
+- GitLab (`gitlab.com`)
+
+## Installation
+
+Pre-built binaries are available for most platforms on the [releases page](https://github.com/scottmckendry/cl-parse/releases). You can also install the tool from source:
+
+```bash
+git clone https://github.com/scottmckendry/cl-parse && cd cl-parse
+go install .
+```
+
+## Usage
+
+Basic usage:
+
+```bash
+cl-parse CHANGELOG.md
+
+# is the same as
+cl-parse # looks for a file named CHANGELOG.md in the current directory
+```
+
+### Options
+
+```
+Flags:
+      --fetch-item-details   fetch details for related items (e.g. GitHub issues & PRs)
+  -f, --format string        output format (json, yaml, or toml) (default "json")
+      --include-body         include the full commit body in changelog entry
+  -l, --latest              display the most recent version from the changelog
+  -r, --release string      display the changelog entry for a specific release
+      --token string        token for fetching related items
+```
+
+### Examples
+
+Get the latest release in JSON format:
+
+```bash
+cl-parse -l CHANGELOG.md
+```
+
+Get a specific release in YAML format:
+
+```bash
+cl-parse -r v1.0.0 -f yaml CHANGELOG.md
+```
+
+Include full commit messages and fetch related items:
+
+```bash
+cl-parse --include-body --fetch-item-details --token YOUR_TOKEN CHANGELOG.md
+```
+
+## Authentication
+
+If your repository is private (or you're using Azure DevOps), you'll need to provide a token to fetch related items.
+
+## Supported Changelog Formats
+
+- Conventional Changelog
+- release-please
+- semantic-release
+- Keep a Changelog
+
+## Output Format
+
+The tool outputs structured data in your chosen format, including:
+
+- Version information
+- Release date
+- Changes categorized by type (feat, fix, etc.)
+- References to issues and pull requests
+- Optional full commit messages
+- Optional detailed information about linked items