diff --git a/README.md b/README.md
index e69de29..9d5bbe7 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,84 @@
+# go-pkg/cli
+
+Lightweight, dependency-free command-line argument and option parsing library for Go.
+
+## Overview
+
+This package provides a small, composable CLI parser with support for:
+- boolean, string, int, and array/map options
+- positional arguments (single and repeating)
+- aliases, short flags, defaults and hidden options
+- validation for incompatible options and custom "special" values
+- automatic usage and version printing
+
+See the core parser implementation in [`parser.go`](parser.go) and the high-level API in [`cli.go`](cli.go).
+
+## Features
+
+- Option types: [`AddBoolOpt`](opt-bool.go), [`AddStringOpt`](opt-string.go), [`AddIntOpt`](opt-int.go), [`AddStringArrayOpt`](opt-string-array.go), [`AddIntArrayOpt`](opt-int-array.go), [`AddStringMapOpt`](opt-string-map.go)
+- Positional args: [`AddStringArg`](arg-string.go), [`AddStringArrayArg`](arg-string-array.go)
+- Usage & version output: [`CliParser.Usage`](cli-usage.go), [`CliParser.PrintVersion`](cli-version.go)
+- Option tracing via [`CliParser.TraceOptions`](cli.go) and [`SimpleOptionTracer`](simple-opt-tracer.go)
+- Programmatic option setting: [`SetOptionValue`](opt-manager.go)
+
+## Quick start
+
+Example: define options and parse argv
+
+```go
+package main
+
+import (
+  "fmt"
+  "git.portale-stac.it/go-pkg/cli"
+)
+
+func main() {
+  var parser cli.CliParser
+  parser.Init([]string{"prog", "--debug", "--config", "app.yaml", "input.txt"}, "$VER:prog,0.1.0,2025,email:$")
+
+  // define target variables and options
+  var debug bool
+  var config string
+  var inputs []string
+
+  parser.AddBoolOpt("debug", "d", &debug, "Enable debug")
+  parser.AddStringOpt("config", "c", &config, "app.yaml", "Config file")
+  parser.AddStringArrayArg("files", true, &inputs, "Input files")
+
+  // print usage: parser.Usage() - see [`CliParser.Usage`](cli-usage.go)
+  if err := parser.Parse(); err != nil {
+    fmt.Println("parse error:", err)
+    return
+  }
+
+  fmt.Println("debug:", debug)
+  fmt.Println("config:", config)
+  fmt.Println("inputs:", inputs)
+}
+```
+
+Refer to the unit test for a realistic example: [`cli_test.go`](cli_test.go).
+
+## API Reference
+
+Key types and methods:
+- [`CliParser`](cli.go) — main parser type
+- [`CliParser.Init`](cli.go) — initialize with argv and version
+- [`CliParser.Parse`](cli.go) — run parsing
+- Option constructors: [`AddBoolOpt`](opt-bool.go), [`AddStringOpt`](opt-string.go), [`AddIntOpt`](opt-int.go), [`AddStringArrayOpt`](opt-string-array.go), [`AddIntArrayOpt`](opt-int-array.go), [`AddStringMapOpt`](opt-string-map.go)
+- Arg constructors: [`AddStringArg`](arg-string.go), [`AddStringArrayArg`](arg-string-array.go)
+- Utilities: [`TraceOptions`](cli.go), [`SetOptionValue`](opt-manager.go), [`SimpleOptionTracer`](simple-opt-tracer.go)
+
+For implementation details, consult:
+- parser internals: [`parser.go`](parser.go)
+- option base helpers: [`opt-base.go`](opt-base.go)
+- usage/version printing: [`cli-usage.go`](cli-usage.go), [`cli-version.go`](cli-version.go)
+
+## License
+
+This project is licensed under the terms in [LICENSE](LICENSE).
+
+## Contributing
+
+Open issues or pull requests are welcome. Run and extend the tests in [`cli_test.go`](cli_test.go) when making changes.