From eabd4f4ad7a3bc6f5c491981c0412089a30e5de8 Mon Sep 17 00:00:00 2001
From: Ciphercat <78522797+0xrsydn@users.noreply.github.com>
Date: Thu, 5 Mar 2026 19:34:47 +0000
Subject: [PATCH] cli: polish clap help text across commands

---
 src/cli/cache.rs  |  3 +++
 src/cli/config.rs |  5 +++++
 src/cli/mod.rs    | 12 +++++++++++-
 src/cli/stocks.rs | 11 +++++++++++
 4 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/src/cli/cache.rs b/src/cli/cache.rs
index f23df65..2717162 100644
--- a/src/cli/cache.rs
+++ b/src/cli/cache.rs
@@ -4,6 +4,7 @@ use crate::cache::Cache;
 use crate::error::IdxError;
 
 #[derive(Debug, Args)]
+#[command(about = "Manage local cache")]
 pub struct CacheCmd {
     #[command(subcommand)]
     pub command: CacheSubcommand,
@@ -11,7 +12,9 @@ pub struct CacheCmd {
 
 #[derive(Debug, Subcommand)]
 pub enum CacheSubcommand {
+    #[command(about = "Show cache usage information")]
     Info,
+    #[command(about = "Clear all cached files")]
     Clear,
 }
 
diff --git a/src/cli/config.rs b/src/cli/config.rs
index 812583a..17f7cc7 100644
--- a/src/cli/config.rs
+++ b/src/cli/config.rs
@@ -4,6 +4,7 @@ use crate::config::{config_path, ensure_default_config, get_config_value, set_co
 use crate::error::IdxError;
 
 #[derive(Debug, Args)]
+#[command(about = "Manage configuration")]
 pub struct ConfigCmd {
     #[command(subcommand)]
     pub command: ConfigSubcommand,
@@ -11,9 +12,13 @@ pub struct ConfigCmd {
 
 #[derive(Debug, Subcommand)]
 pub enum ConfigSubcommand {
+    #[command(about = "Create default configuration file")]
     Init,
+    #[command(about = "Get a configuration value by key")]
     Get { key: String },
+    #[command(about = "Set a configuration value by key")]
     Set { key: String, value: String },
+    #[command(about = "Print configuration file path")]
     Path,
 }
 
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 5c2aacc..ab4200d 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -14,7 +14,12 @@ pub enum Shell {
 }
 
 #[derive(Debug, Parser)]
-#[command(name = "idx", about = "Indonesian stock analysis CLI")]
+#[command(
+    name = "idx",
+    bin_name = "idx",
+    about = "CLI tool for Indonesian stock market (IDX) analysis",
+    long_about = "idx-cli is a Rust command-line tool for Indonesian stock market (IDX) analysis.\nIt supports quote lookup, historical data, local caching, and output formats for both humans and AI agents."
+)]
 pub struct Cli {
     #[arg(short, long, value_enum, global = true)]
     pub output: Option<OutputFormat>,
@@ -34,9 +39,14 @@ pub struct Cli {
 
 #[derive(Debug, Subcommand)]
 pub enum Commands {
+    #[command(about = "Stock data and analysis")]
     Stocks(stocks::StocksCmd),
+    #[command(about = "Manage configuration")]
     Config(config::ConfigCmd),
+    #[command(about = "Manage local cache")]
     Cache(cache::CacheCmd),
+    #[command(about = "Generate shell completions")]
     Completions { shell: Shell },
+    #[command(about = "Show idx-cli version")]
     Version,
 }
diff --git a/src/cli/stocks.rs b/src/cli/stocks.rs
index fdbad69..48b9abe 100644
--- a/src/cli/stocks.rs
+++ b/src/cli/stocks.rs
@@ -8,6 +8,7 @@ use crate::error::IdxError;
 use crate::output::{render_history, render_quotes};
 
 #[derive(Debug, Args)]
+#[command(about = "Stock data and analysis")]
 pub struct StocksCmd {
     #[command(subcommand)]
     pub command: StocksSubcommand,
@@ -15,10 +16,20 @@ pub struct StocksCmd {
 
 #[derive(Debug, Subcommand)]
 pub enum StocksSubcommand {
+    #[command(
+        about = "Get real-time stock quotes",
+        after_help = "Examples:\n  idx stocks quote BBCA\n  idx stocks quote BBCA,BBRI,BMRI\n  idx -o json stocks quote BBCA"
+    )]
     Quote {
+        /// One or more symbols, comma-separated or space-separated.
         symbols: Vec<String>,
     },
+    #[command(
+        about = "Get historical OHLC data",
+        after_help = "Examples:\n  idx stocks history BBCA --period 3mo\n  idx stocks history BBCA --period 1y --interval 1wk"
+    )]
     History {
+        /// Single ticker symbol (e.g. BBCA).
         symbol: String,
         #[arg(long, value_enum, default_value_t = Period::ThreeMonths)]
         period: Period,