From cd5122da4a3654e3fa2a7db1e69eefc235f35e64 Mon Sep 17 00:00:00 2001
From: "blink-so[bot]" <211532188+blink-so[bot]@users.noreply.github.com>
Date: Thu, 12 Jun 2025 21:33:56 +0000
Subject: [PATCH] docs: improve README

This commit addresses issue #10 by making several improvements to the
README.md file.

- Compares the help output of a simple echo command between Cobra and
  Serpent.
- Adds a 'Migrating from Cobra' section.
- Explicitly states that Serpent is a replacement for Cobra and Viper.
- Adds a pointer to the coder/coder repository for a more comprehensive
  example.

Co-authored-by: Atif Ali <10648092+matifali@users.noreply.github.com>
---
 README.md | 49 ++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 46 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index d217918..e2fe080 100644
--- a/README.md
+++ b/README.md
@@ -91,6 +91,49 @@ type Option struct {
 And is used by each [Command](https://pkg.go.dev/github.com/coder/serpent#Command) when
 passed as an array to the `Options` field.
 
-## More coming...
-This README is a stub for now. We'll better explain the design and usage
-of `serpent` in the future.
\ No newline at end of file
+## Comparison with Cobra
+
+Here is a comparison of the `help` output between a simple `echo` command in Cobra and Serpent.
+
+### Cobra
+
+```
+echo is for echoing anything back. Echo works a lot like print, except it has a child command.
+
+Usage:
+  echo [string to echo] [flags]
+
+Flags:
+  -h, --help    help for echo
+  -u, --upper   make the output uppercase
+```
+
+### Serpent
+
+```
+USAGE:
+  echo <text>
+
+  Prints the given text to the console.
+
+OPTIONS:
+      --upper bool
+          Prints the text in upper case.
+```
+
+## Migrating from Cobra
+
+Serpent is designed to be a replacement for Cobra and Viper. If you are familiar with Cobra, the transition to Serpent should be relatively straightforward. The main differences are:
+
+*   **Command Structure:** Serpent uses a `serpent.Command` struct which is similar to `cobra.Command`.
+*   **Options:** Serpent has a more flexible and powerful option system that allows you to define options from multiple sources (flags, environment variables, config files, etc.) in a single place.
+*   **Middleware:** Serpent has a middleware system that allows you to compose functionality and apply it to your commands.
+*   **Testability:** Serpent is designed to be more testable than Cobra. For example, OS stdout and stderr are only available to commands explicitly.
+
+## Serpent vs. Cobra and Viper
+
+Serpent is intended to be a complete replacement for both Cobra and Viper. While Viper is often used with Cobra to provide environment and config file support, Serpent has this functionality built-in. This results in a more integrated and streamlined experience.
+
+## Examples
+
+For a more comprehensive example of a large-scale CLI built with Serpent, please see the [coder/coder](https://github.com/coder/coder) repository.
\ No newline at end of file