Skip to content

Commit d47ed16

Browse files
echobtechobt
authored
feat(cli): improve help display with categorized commands (#541)
- Add custom help template with organized command categories - Group commands by function: Execution, Session, Auth, Config, etc. - Add emoji prefixes to category headers for visual clarity - Hide internal/debug commands from default help output - Update ASCII art banner with decorative border - Reorganize after-help section with Quick Start first - Add display_order to control command listing sequence
1 parent 0f82b85 commit d47ed16

File tree

2 files changed

+180
-96
lines changed

2 files changed

+180
-96
lines changed

‎src/cortex-cli/src/cli/args.rs‎

Lines changed: 83 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
use clap::{Args, Parser, Subcommand};
66
use std::path::PathBuf;
77

8-
use super::styles::{AFTER_HELP, BEFORE_HELP, categories, get_styles};
8+
use super::styles::{AFTER_HELP, BEFORE_HELP, HELP_TEMPLATE, categories, get_styles};
99
use crate::acp_cmd::AcpCli;
1010
use crate::agent_cmd::AgentCli;
1111
use crate::alias_cmd::AliasCli;
@@ -115,7 +115,8 @@ pub enum ColorMode {
115115
subcommand_negates_reqs = true,
116116
override_usage = "cortex [OPTIONS] [PROMPT]\n cortex [OPTIONS] <COMMAND> [ARGS]",
117117
before_help = BEFORE_HELP,
118-
after_help = AFTER_HELP
118+
after_help = AFTER_HELP,
119+
help_template = HELP_TEMPLATE
119120
)]
120121
pub struct Cli {
121122
#[clap(flatten)]
@@ -229,9 +230,9 @@ pub struct InteractiveArgs {
229230
/// CLI subcommands.
230231
#[derive(Subcommand)]
231232
pub enum Commands {
232-
/// Initialize AGENTS.md in the current directory.
233-
Init(InitCommand),
234-
233+
// ========================================================================
234+
// 🚀 Execution (order 1-9)
235+
// ========================================================================
235236
/// Run Cortex non-interactively with advanced options
236237
#[command(visible_alias = "r", display_order = 1)]
237238
#[command(next_help_heading = categories::EXECUTION)]
@@ -242,6 +243,9 @@ pub enum Commands {
242243
#[command(next_help_heading = categories::EXECUTION)]
243244
Exec(ExecCli),
244245

246+
// ========================================================================
247+
// 📋 Session Management (order 10-19)
248+
// ========================================================================
245249
/// Resume a previous interactive session
246250
#[command(display_order = 10)]
247251
#[command(next_help_heading = categories::SESSION)]
@@ -267,6 +271,9 @@ pub enum Commands {
267271
#[command(next_help_heading = categories::SESSION)]
268272
Delete(DeleteCommand),
269273

274+
// ========================================================================
275+
// 🔐 Authentication (order 20-29)
276+
// ========================================================================
270277
/// Authenticate with Cortex API
271278
#[command(display_order = 20)]
272279
#[command(next_help_heading = categories::AUTH)]
@@ -282,6 +289,9 @@ pub enum Commands {
282289
#[command(next_help_heading = categories::AUTH)]
283290
Whoami,
284291

292+
// ========================================================================
293+
// 🔌 Extensibility (order 30-39)
294+
// ========================================================================
285295
/// Manage agents (list, create, show)
286296
#[command(display_order = 30)]
287297
#[command(next_help_heading = categories::EXTENSION)]
@@ -302,6 +312,9 @@ pub enum Commands {
302312
#[command(next_help_heading = categories::EXTENSION)]
303313
Acp(AcpCli),
304314

315+
// ========================================================================
316+
// ⚙️ Configuration (order 40-49)
317+
// ========================================================================
305318
/// Show or edit configuration
306319
#[command(display_order = 40)]
307320
#[command(next_help_heading = categories::CONFIG)]
@@ -317,6 +330,14 @@ pub enum Commands {
317330
#[command(next_help_heading = categories::CONFIG)]
318331
Features(FeaturesCommand),
319332

333+
/// Initialize AGENTS.md in the current directory
334+
#[command(display_order = 43)]
335+
#[command(next_help_heading = categories::CONFIG)]
336+
Init(InitCommand),
337+
338+
// ========================================================================
339+
// 🛠️ Utilities (order 50-59)
340+
// ========================================================================
320341
/// GitHub integration (actions, workflows)
321342
#[command(visible_alias = "gh", display_order = 50)]
322343
#[command(next_help_heading = categories::UTILITIES)]
@@ -342,79 +363,88 @@ pub enum Commands {
342363
#[command(next_help_heading = categories::UTILITIES)]
343364
Completion(CompletionCommand),
344365

345-
/// Run commands within a Cortex-provided sandbox
346-
#[command(visible_alias = "sb", display_order = 60)]
347-
#[command(next_help_heading = categories::ADVANCED)]
348-
Sandbox(SandboxArgs),
349-
350-
/// Run the HTTP API server (for desktop/web integration)
351-
#[command(display_order = 61)]
352-
#[command(next_help_heading = categories::ADVANCED)]
353-
Serve(ServeCommand),
354-
355-
/// Discover Cortex servers on the local network
356-
#[command(display_order = 62)]
357-
#[command(next_help_heading = categories::ADVANCED)]
358-
Servers(ServersCommand),
359-
360-
/// View prompt history from past sessions
361-
#[command(display_order = 63)]
362-
#[command(next_help_heading = categories::ADVANCED)]
363-
History(HistoryCommand),
364-
366+
// ========================================================================
367+
// 🔧 Maintenance (order 60-69)
368+
// ========================================================================
365369
/// Check for and install updates
366-
#[command(display_order = 70)]
367-
#[command(next_help_heading = categories::ADVANCED)]
370+
#[command(display_order = 60)]
371+
#[command(next_help_heading = categories::MAINTENANCE)]
368372
Upgrade(UpgradeCli),
369373

370374
/// Uninstall Cortex CLI
371-
#[command(display_order = 71)]
372-
#[command(next_help_heading = categories::ADVANCED)]
375+
#[command(display_order = 61)]
376+
#[command(next_help_heading = categories::MAINTENANCE)]
373377
Uninstall(UninstallCli),
374378

375-
/// Debug and diagnostic commands
376-
#[command(display_order = 99)]
377-
#[command(next_help_heading = categories::ADVANCED)]
378-
Debug(DebugCli),
379+
/// Data compaction and cleanup (logs, sessions, history)
380+
#[command(visible_aliases = ["gc", "cleanup"], display_order = 62)]
381+
#[command(next_help_heading = categories::MAINTENANCE)]
382+
Compact(CompactCli),
379383

380-
/// Manage plugins
381-
#[command(visible_alias = "plugins")]
382-
Plugin(PluginCli),
384+
/// Manage cache
385+
#[command(display_order = 63)]
386+
#[command(next_help_heading = categories::MAINTENANCE)]
387+
Cache(CacheCli),
388+
389+
/// View application logs
390+
#[command(display_order = 64)]
391+
#[command(next_help_heading = categories::MAINTENANCE)]
392+
Logs(LogsCli),
383393

384394
/// Submit feedback and bug reports
385-
#[command(visible_alias = "report")]
395+
#[command(visible_alias = "report", display_order = 65)]
396+
#[command(next_help_heading = categories::MAINTENANCE)]
386397
Feedback(FeedbackCli),
387398

388399
/// Lock/protect sessions from deletion
389-
#[command(visible_alias = "protect")]
400+
#[command(visible_alias = "protect", display_order = 66)]
401+
#[command(next_help_heading = categories::MAINTENANCE)]
390402
Lock(LockCli),
391403

392404
/// Manage command aliases
393-
#[command(visible_alias = "aliases")]
405+
#[command(visible_alias = "aliases", display_order = 67)]
406+
#[command(next_help_heading = categories::MAINTENANCE)]
394407
Alias(AliasCli),
395408

396-
/// Manage cache
397-
Cache(CacheCli),
398-
399-
/// Data compaction and cleanup (logs, sessions, history)
400-
#[command(visible_aliases = ["gc", "cleanup"])]
401-
Compact(CompactCli),
409+
/// Manage plugins
410+
#[command(visible_alias = "plugins", display_order = 68)]
411+
#[command(next_help_heading = categories::MAINTENANCE)]
412+
Plugin(PluginCli),
402413

403-
/// View application logs
404-
Logs(LogsCli),
414+
// ========================================================================
415+
// Hidden commands (internal/debug/advanced)
416+
// ========================================================================
417+
/// Debug and diagnostic commands
418+
#[command(display_order = 99, hide = true)]
419+
Debug(DebugCli),
405420

406421
/// Start interactive shell/REPL mode
407-
#[command(visible_aliases = ["interactive", "repl"])]
422+
#[command(visible_aliases = ["interactive", "repl"], hide = true)]
408423
Shell(ShellCli),
409424

425+
/// Execute and manage task DAGs (dependency graphs)
426+
#[command(visible_alias = "tasks", hide = true)]
427+
Dag(DagCli),
428+
429+
/// Discover Cortex servers on the local network
430+
#[command(hide = true)]
431+
Servers(ServersCommand),
432+
433+
/// View prompt history from past sessions
434+
#[command(hide = true)]
435+
History(HistoryCommand),
436+
410437
/// Manage workspace/project settings
411-
#[command(visible_alias = "project")]
438+
#[command(visible_alias = "project", hide = true)]
412439
Workspace(WorkspaceCli),
413440

414-
/// Execute and manage task DAGs (dependency graphs)
415-
#[command(visible_alias = "tasks", display_order = 55)]
416-
#[command(next_help_heading = categories::UTILITIES)]
417-
Dag(DagCli),
441+
/// Run commands within a Cortex-provided sandbox
442+
#[command(visible_alias = "sb", hide = true)]
443+
Sandbox(SandboxArgs),
444+
445+
/// Run the HTTP API server (for desktop/web integration)
446+
#[command(hide = true)]
447+
Serve(ServeCommand),
418448
}
419449

420450
// ============================================================================

‎src/cortex-cli/src/cli/styles.rs‎

Lines changed: 97 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -27,55 +27,109 @@ pub fn get_styles() -> Styles {
2727

2828
/// After-help section with environment variables documentation.
2929
pub const AFTER_HELP: &str = color_print::cstr!(
30-
r#"
31-
<cyan,bold>ENVIRONMENT VARIABLES:</>
32-
<green,bold>CORTEX_HOME</> Override config directory (default: ~/.config/cortex)
33-
<green,bold>CORTEX_API_KEY</> API key (alternative to --with-api-key)
34-
<green,bold>CORTEX_MODEL</> Default model (alternative to --model)
35-
<green,bold>CORTEX_LOG_LEVEL</> Log verbosity (error, warn, info, debug, trace)
36-
<green,bold>NO_COLOR</> Disable colored output (set to '1' or 'true')
37-
<green,bold>VISUAL</> Editor for /edit command (fallback: EDITOR)
38-
<green,bold>EDITOR</> Fallback editor if VISUAL is not set
39-
40-
<cyan,bold>PATHS:</>
41-
<green,bold>Config file</> ~/.config/cortex/config.toml
42-
<green,bold>Sessions</> ~/.local/share/cortex/sessions/
43-
<green,bold>Logs</> ~/.cache/cortex/logs/
44-
<green,bold>Agents</> ~/.cortex/agents/ (personal), .cortex/agents/ (project)
45-
46-
<cyan,bold>QUICK START:</>
47-
<yellow>cortex</> Start interactive TUI
48-
<yellow>cortex</> <dim>"fix the bug"</> Start TUI with initial prompt
49-
<yellow>cortex run</> <dim>"explain this"</> Non-interactive single request
50-
<yellow>cortex exec</> <dim>"run tests"</> Headless execution for CI/CD
51-
<yellow>cortex resume --last</> Continue most recent session
52-
53-
<cyan,bold>LEARN MORE:</>
54-
Documentation: <blue,underline>https://docs.cortex.foundation</>
55-
Report issues: <blue,underline>https://github.com/CortexLM/cortex-cli/issues</>
56-
"#
30+
r#"<cyan,bold>📚 QUICK START</>
31+
<green,bold>cortex</> Start interactive TUI
32+
<green,bold>cortex</> <dim>"fix the bug"</> Start TUI with initial prompt
33+
<green,bold>cortex run</> <dim>"explain this"</> Non-interactive single request
34+
<green,bold>cortex exec</> <dim>"run tests"</> Headless execution for CI/CD
35+
<green,bold>cortex resume --last</> Continue most recent session
36+
37+
<cyan,bold>🌍 ENVIRONMENT VARIABLES</>
38+
<yellow>CORTEX_HOME</> Override config directory (default: ~/.config/cortex)
39+
<yellow>CORTEX_API_KEY</> API key (alternative to --with-api-key)
40+
<yellow>CORTEX_MODEL</> Default model (alternative to --model)
41+
<yellow>CORTEX_LOG_LEVEL</> Log verbosity (error, warn, info, debug, trace)
42+
<yellow>NO_COLOR</> Disable colored output (set to '1' or 'true')
43+
<yellow>VISUAL</>/<yellow>EDITOR</> Editor for /edit command
44+
45+
<cyan,bold>📁 PATHS</>
46+
<dim>Config</> ~/.config/cortex/config.toml
47+
<dim>Sessions</> ~/.local/share/cortex/sessions/
48+
<dim>Logs</> ~/.cache/cortex/logs/
49+
<dim>Agents</> ~/.cortex/agents/ (personal), .cortex/agents/ (project)
50+
51+
<cyan,bold>🔗 LEARN MORE</>
52+
<blue,underline>https://docs.cortex.foundation</> Documentation
53+
<blue,underline>https://github.com/CortexLM/cortex-cli</> Source & Issues"#
5754
);
5855

5956
/// Before-help section with ASCII art banner.
6057
pub const BEFORE_HELP: &str = color_print::cstr!(
61-
r#"
62-
<cyan,bold> ██████╗ ██████╗ ██████╗ ████████╗███████╗██╗ ██╗</>
63-
<cyan,bold> ██╔════╝██╔═══██╗██╔══██╗╚══██╔══╝██╔════╝╚██╗██╔╝</>
64-
<cyan,bold> ██║ ██║ ██║██████╔╝ ██║ █████╗ ╚███╔╝ </>
65-
<cyan,bold> ██║ ██║ ██║██╔══██╗ ██║ ██╔══╝ ██╔██╗ </>
66-
<cyan,bold> ╚██████╗╚██████╔╝██║ ██║ ██║ ███████╗██╔╝ ██╗</>
67-
<cyan,bold> ╚═════╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝ ╚══════╝╚═╝ ╚═╝</>
68-
<dim> AI-Powered Coding Agent</>
69-
"#
58+
r#"<cyan,bold> ╔═══════════════════════════════════════════════════╗
59+
║ ██████╗ ██████╗ ██████╗ ████████╗███████╗██╗ ██╗║
60+
║ ██╔════╝██╔═══██╗██╔══██╗╚══██╔══╝██╔════╝╚██╗██╔╝║
61+
║ ██║ ██║ ██║██████╔╝ ██║ █████╗ ╚███╔╝ ║
62+
║ ██║ ██║ ██║██╔══██╗ ██║ ██╔══╝ ██╔██╗ ║
63+
║ ╚██████╗╚██████╔╝██║ ██║ ██║ ███████╗██╔╝ ██╗║
64+
║ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝ ╚══════╝╚═╝ ╚═╝║
65+
╚═══════════════════════════════════════════════════╝</>
66+
<dim> AI-Powered Coding Agent</>"#
7067
);
7168

7269
/// Command category display names for styled help output.
7370
pub mod categories {
74-
pub const EXECUTION: &str = "Execution Modes";
75-
pub const SESSION: &str = "Session Management";
76-
pub const AUTH: &str = "Authentication";
77-
pub const EXTENSION: &str = "Extensibility";
78-
pub const CONFIG: &str = "Configuration";
79-
pub const UTILITIES: &str = "Utilities";
80-
pub const ADVANCED: &str = "Advanced";
71+
pub const EXECUTION: &str = "🚀 Execution";
72+
pub const SESSION: &str = "📋 Session Management";
73+
pub const AUTH: &str = "🔐 Authentication";
74+
pub const EXTENSION: &str = "🔌 Extensibility";
75+
pub const CONFIG: &str = "⚙️ Configuration";
76+
pub const UTILITIES: &str = "🛠️ Utilities";
77+
pub const MAINTENANCE: &str = "🔧 Maintenance";
8178
}
79+
80+
/// Custom help template with categorized commands.
81+
///
82+
/// Since clap doesn't natively support subcommand categories in help output,
83+
/// we define a custom template that manually lists commands by category.
84+
pub const HELP_TEMPLATE: &str = color_print::cstr!(
85+
r#"{before-help}
86+
{about-with-newline}
87+
{usage-heading} {usage}
88+
89+
<cyan,bold>🚀 Execution:</>
90+
<green,bold>run</> Run Cortex non-interactively with advanced options <dim>[aliases: r]</>
91+
<green,bold>exec</> Execute in headless mode (for CI/CD, scripts) <dim>[aliases: e]</>
92+
93+
<cyan,bold>📋 Session Management:</>
94+
<green,bold>resume</> Resume a previous interactive session
95+
<green,bold>sessions</> List previous sessions
96+
<green,bold>export</> Export a session to JSON format
97+
<green,bold>import</> Import a session from JSON file or URL
98+
<green,bold>delete</> Delete a session
99+
100+
<cyan,bold>🔐 Authentication:</>
101+
<green,bold>login</> Authenticate with Cortex API
102+
<green,bold>logout</> Remove stored authentication credentials
103+
<green,bold>whoami</> Show currently authenticated user
104+
105+
<cyan,bold>🔌 Extensibility:</>
106+
<green,bold>agent</> Manage agents (list, create, show)
107+
<green,bold>mcp</> Manage MCP (Model Context Protocol) servers
108+
<green,bold>acp</> Start ACP server for IDE integration (e.g., Zed)
109+
110+
<cyan,bold>⚙️ Configuration:</>
111+
<green,bold>config</> Show or edit configuration
112+
<green,bold>models</> List available models
113+
<green,bold>features</> Inspect feature flags
114+
<green,bold>init</> Initialize AGENTS.md in the current directory
115+
116+
<cyan,bold>🛠️ Utilities:</>
117+
<green,bold>github</> GitHub integration (actions, workflows) <dim>[aliases: gh]</>
118+
<green,bold>pr</> Checkout a pull request
119+
<green,bold>scrape</> Scrape web content to markdown/text/html
120+
<green,bold>stats</> Show usage statistics
121+
<green,bold>completion</> Generate shell completion scripts
122+
123+
<cyan,bold>🔧 Maintenance:</>
124+
<green,bold>upgrade</> Check for and install updates
125+
<green,bold>uninstall</> Uninstall Cortex CLI
126+
<green,bold>compact</> Data compaction and cleanup <dim>[aliases: gc, cleanup]</>
127+
<green,bold>cache</> Manage cache
128+
<green,bold>logs</> View application logs
129+
<green,bold>feedback</> Submit feedback and bug reports <dim>[aliases: report]</>
130+
<green,bold>lock</> Lock/protect sessions from deletion <dim>[aliases: protect]</>
131+
<green,bold>alias</> Manage command aliases <dim>[aliases: aliases]</>
132+
<green,bold>plugin</> Manage plugins <dim>[aliases: plugins]</>
133+
134+
{options}{after-help}"#
135+
);

0 commit comments

Comments
 (0)