Improve CLI help with examples and better descriptions

Add comprehensive help text at all levels:
- Main command shows quick start examples and common workflows
- Each subcommand group shows relevant examples
- Individual commands show usage examples in after_help
- Better parameter descriptions explain purpose and usage

Add color-print crate for styled examples in main help.

Author: max-lt

Cargo.lock

@@ -10,6 +10,7 @@ path = "src/main.rs"
 
 [dependencies]
 clap = { version = "4", features = ["derive"] }
+color-print = "0.3"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 dirs = "6"

Cargo.toml

@@ -4,48 +4,53 @@ use colored::Colorize;
 
 #[derive(Subcommand)]
 pub enum AliasCommand {
-    /// Add or update an alias
+    /// Configure a new alias for API or direct database access
+    #[command(after_help = "Examples:\n  \
+        ow alias set prod --api https://dash.openworkers.com\n  \
+        ow alias set local --db postgres://localhost/ow --user admin@example.com\n  \
+        ow alias set dev --api https://localhost:8080 --insecure")]
     Set {
-        /// Alias name
+        /// Alias name (used as prefix: ow <alias> workers list)
         name: String,
 
-        /// API URL (for API backend)
+        /// API URL for HTTP backend (e.g., https://dash.openworkers.com)
         #[arg(long, conflicts_with = "db")]
         api: Option<String>,
 
-        /// API token
+        /// API token (obtained via ow login)
         #[arg(long, requires = "api")]
         token: Option<String>,
 
-        /// Accept invalid TLS certificates (for dev environments)
+        /// Accept invalid TLS certificates (for local development)
         #[arg(long, requires = "api")]
         insecure: bool,
 
-        /// Database URL (for DB backend)
+        /// PostgreSQL URL for direct database access
         #[arg(long, conflicts_with = "api")]
         db: Option<String>,
 
-        /// User email or username to operate as (for DB backend)
+        /// User email to operate as (required for db backend)
         #[arg(long, requires = "db")]
         user: Option<String>,
 
-        /// Overwrite existing alias
+        /// Overwrite existing alias without confirmation
         #[arg(short, long)]
         force: bool,
     },
 
-    /// List all configured aliases
+    /// List all configured aliases (* = default)
     #[command(alias = "ls")]
     List,
 
-    /// Remove an alias
-    #[command(alias = "rm")]
+    /// Remove an alias from configuration
+    #[command(alias = "rm", after_help = "Example:\n  ow alias remove old-prod")]
     Remove {
         /// Alias name to remove
         name: String,
     },
 
-    /// Set the default alias
+    /// Set the default alias (used when no alias prefix is given)
+    #[command(after_help = "Example:\n  ow alias set-default prod")]
     SetDefault {
         /// Alias name to set as default
         name: String,

src/commands/alias.rs

@@ -4,34 +4,40 @@ use colored::Colorize;
 
 #[derive(Subcommand)]
 pub enum DatabasesCommand {
-    /// List all databases
+    /// List all database configurations
     #[command(alias = "ls")]
     List,
 
-    /// Get database details
+    /// Show database configuration details
+    #[command(after_help = "Example:\n  ow databases get my-db")]
     Get {
         /// Database name
         name: String,
     },
 
-    /// Create a new database
+    /// Create a database configuration for SQL access from workers
+    #[command(after_help = "Examples:\n  \
+        ow databases create my-db\n  \
+        ow databases create my-db --provider postgres \\\n    \
+          --connection-string postgres://user:pass@host/db\n  \
+        ow databases create analytics --max-rows 5000 --timeout 60")]
     Create {
-        /// Database name
+        /// Database configuration name
         name: String,
 
-        /// Provider: platform (default) or postgres
+        /// Database provider: platform (managed) or postgres (bring your own)
         #[arg(long, default_value = "platform")]
         provider: String,
 
-        /// Postgres connection string (required for postgres provider)
+        /// PostgreSQL connection string (required for postgres provider)
         #[arg(long)]
         connection_string: Option<String>,
 
-        /// Description
+        /// Description of this database
         #[arg(short, long)]
         description: Option<String>,
 
-        /// Maximum rows per query (default: 1000)
+        /// Maximum rows returned per query (default: 1000)
         #[arg(long)]
         max_rows: Option<i32>,
 
@@ -40,10 +46,10 @@ pub enum DatabasesCommand {
         timeout: Option<i32>,
     },
 
-    /// Delete a database
-    #[command(alias = "rm")]
+    /// Delete a database configuration
+    #[command(alias = "rm", after_help = "Example:\n  ow databases delete old-db")]
     Delete {
-        /// Database name
+        /// Database name to delete
         name: String,
     },
 }

src/commands/databases.rs

@@ -6,71 +6,84 @@ use colored::Colorize;
 
 #[derive(Subcommand)]
 pub enum EnvCommand {
-    /// List all environments
+    /// List all environments with their variable/binding counts
     #[command(alias = "ls")]
     List,
 
-    /// Get environment details
+    /// Show environment details including all variables and bindings
+    #[command(after_help = "Example:\n  ow env get production")]
     Get {
         /// Environment name
         name: String,
     },
 
-    /// Create a new environment
+    /// Create a new environment for organizing variables and bindings
+    #[command(after_help = "Examples:\n  \
+        ow env create production\n  \
+        ow env create staging -d \"Staging environment\"")]
     Create {
         /// Environment name
         name: String,
 
-        /// Environment description
+        /// Description of this environment's purpose
         #[arg(short, long)]
         description: Option<String>,
     },
 
-    /// Delete an environment
-    #[command(alias = "rm")]
+    /// Delete an environment and all its variables/bindings
+    #[command(alias = "rm", after_help = "Example:\n  ow env delete old-env")]
     Delete {
-        /// Environment name
+        /// Environment name to delete
         name: String,
     },
 
-    /// Set a variable or secret
+    /// Set a variable or secret in an environment
+    #[command(after_help = "Examples:\n  \
+        ow env set prod API_URL https://api.example.com\n  \
+        ow env set prod API_KEY sk-xxx --secret")]
     Set {
         /// Environment name
         env: String,
 
-        /// Variable key
+        /// Variable name (conventionally UPPER_SNAKE_CASE)
         key: String,
 
         /// Variable value
         value: String,
 
-        /// Mark as secret (value will be masked)
+        /// Store as secret (value is encrypted and masked in output)
         #[arg(short, long)]
         secret: bool,
     },
 
-    /// Remove a variable or secret
+    /// Remove a variable or secret from an environment
+    #[command(after_help = "Example:\n  ow env unset prod OLD_API_KEY")]
     Unset {
         /// Environment name
         env: String,
 
-        /// Variable key
+        /// Variable name to remove
         key: String,
     },
 
-    /// Bind a resource to an environment
+    /// Bind a resource (KV, database, storage) to an environment
+    #[command(after_help = "Examples:\n  \
+        ow env bind prod KV my-cache --type kv\n  \
+        ow env bind prod DB my-database --type database\n  \
+        ow env bind prod ASSETS my-storage --type assets\n  \
+        ow env bind prod FILES my-storage --type storage")]
     Bind {
         /// Environment name
         env: String,
 
-        /// Binding name (e.g. ASSETS, MY_KV, MY_DB)
+        /// Binding name (accessed as env.NAME in worker code)
         key: String,
 
-        /// Resource name to bind
+        /// Resource name to bind (must exist)
         resource: String,
 
-        /// Binding type
-        #[arg(short = 't', long, value_parser = ["assets", "storage", "kv", "database"])]
+        /// Binding type: assets, storage, kv, or database
+        #[arg(short = 't', long = "type", value_parser = ["assets", "storage", "kv", "database"])]
         binding_type: String,
     },
 }

src/commands/env.rs

@@ -8,26 +8,30 @@ pub enum KvCommand {
     #[command(alias = "ls")]
     List,
 
-    /// Get KV namespace details
+    /// Show KV namespace details
+    #[command(after_help = "Example:\n  ow kv get my-cache")]
     Get {
         /// KV namespace name
         name: String,
     },
 
-    /// Create a new KV namespace
+    /// Create a new KV namespace for key-value storage
+    #[command(after_help = "Examples:\n  \
+        ow kv create my-cache\n  \
+        ow kv create sessions -d \"User sessions\"")]
     Create {
         /// KV namespace name
         name: String,
 
-        /// Description
+        /// Description of what this namespace stores
         #[arg(short, long)]
         description: Option<String>,
     },
 
-    /// Delete a KV namespace
-    #[command(alias = "rm")]
+    /// Delete a KV namespace and all its data
+    #[command(alias = "rm", after_help = "Example:\n  ow kv delete old-cache")]
     Delete {
-        /// KV namespace name
+        /// KV namespace name to delete
         name: String,
     },
 }