From bae9c0661197fc82ee96ab363ecb3fecd3361439 Mon Sep 17 00:00:00 2001
From: Rob Di Marco <robdimarco@circuitandchisel.com>
Date: Tue, 9 Sep 2025 12:52:41 -0400
Subject: [PATCH] Show help by default instead of running demo
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add comprehensive help module with usage information
- Update CLI to show help when no command is provided
- Require explicit 'demo' command to run the demo
- Add support for help, --help, -h flags
- Improve error handling for unknown commands

Fixes: https://linear.app/novellum/issue/ATXP-240/running-npx-atxp-should-print-out-help

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 packages/atxp/src/help.ts  | 32 ++++++++++++++++++++++++++++++++
 packages/atxp/src/index.ts | 19 +++++++++++++++++--
 2 files changed, 49 insertions(+), 2 deletions(-)
 create mode 100644 packages/atxp/src/help.ts

diff --git a/packages/atxp/src/help.ts b/packages/atxp/src/help.ts
new file mode 100644
index 0000000..3e99043
--- /dev/null
+++ b/packages/atxp/src/help.ts
@@ -0,0 +1,32 @@
+import chalk from 'chalk';
+
+export function showHelp(): void {
+  console.log(chalk.bold(chalk.blue('ATXP CLI')));
+  console.log(chalk.gray('Command line tool for creating ATXP projects and running demos'));
+  console.log();
+  
+  console.log(chalk.bold('Usage:'));
+  console.log('  npx atxp <command> [options]');
+  console.log();
+  
+  console.log(chalk.bold('Commands:'));
+  console.log('  ' + chalk.cyan('demo') + '     ' + 'Run the ATXP demo application');
+  console.log('  ' + chalk.cyan('create') + '   ' + 'Create a new ATXP project');
+  console.log('  ' + chalk.cyan('help') + '     ' + 'Show this help message');
+  console.log();
+  
+  console.log(chalk.bold('Demo Options:'));
+  console.log('  ' + chalk.yellow('--verbose, -v') + '  ' + 'Show detailed logs');
+  console.log('  ' + chalk.yellow('--refresh') + '      ' + 'Force refresh the demo from GitHub');
+  console.log();
+  
+  console.log(chalk.bold('Examples:'));
+  console.log('  npx atxp demo              # Run the demo');
+  console.log('  npx atxp demo --verbose    # Run demo with detailed logs');
+  console.log('  npx atxp create            # Create a new project');
+  console.log();
+  
+  console.log(chalk.bold('Learn more:'));
+  console.log('  Website: ' + chalk.underline('https://atxp.dev'));
+  console.log('  GitHub:  ' + chalk.underline('https://github.com/atxp-dev/cli'));
+}
\ No newline at end of file
diff --git a/packages/atxp/src/index.ts b/packages/atxp/src/index.ts
index 8987755..8a57a1b 100644
--- a/packages/atxp/src/index.ts
+++ b/packages/atxp/src/index.ts
@@ -2,16 +2,31 @@
 
 import { createProject } from './create-project.js';
 import { runDemo } from './run-demo.js';
+import { showHelp } from './help.js';
+
+// Get the command from arguments
+const command = process.argv[2];
 
 // Detect if we're in create mode (npm create atxp or npx atxp create)
 const isCreateMode = process.env.npm_config_argv?.includes('create') || 
                      process.argv.includes('--create') || 
-                     process.argv[2] === 'create';
+                     command === 'create';
 
+// Handle different commands
 if (isCreateMode) {
   console.log('Creating new ATXP project...');
   createProject();
-} else {
+} else if (command === 'demo') {
   console.log('Starting ATXP demo...');
   runDemo();
+} else if (command === 'help' || command === '--help' || command === '-h') {
+  showHelp();
+} else if (!command) {
+  // No command provided - show help instead of running demo
+  showHelp();
+} else {
+  // Unknown command
+  console.log(`Unknown command: ${command}`);
+  console.log('Run "npx atxp help" for usage information.');
+  process.exit(1);
 }
\ No newline at end of file