@4ge/cli 0.2.0 → 0.2.1

package/dist/base.js

@@ -117,7 +117,7 @@ export class BaseCommand extends Command {
         options?.onStatusChange?.('refreshing-token');
         const credential = await ensureFreshToken();
         if (!credential) {
-            const message = 'Not authenticated. Run `4ge auth login --token <api_key>` first.';
+            const message = 'Not authenticated. Run `4ge auth:login --token <api_key>` first.';
             if (this.isJsonMode) {
                 this.outputErrorAndExit({ message, code: 'NO_CREDENTIALS' });
             }

package/dist/commands/auth/status.js

@@ -12,7 +12,7 @@ export default class AuthStatus extends BaseCommand {
                 this.outputErrorAndExit({ message: 'Not authenticated', code: 'NO_CREDENTIALS' });
             }
             else {
-                this.log('Not authenticated. Run `4ge auth login --token <api_key>` to authenticate.');
+                this.log('Not authenticated. Run `4ge auth:login --token <api_key>` to authenticate.');
             }
             return;
         }
@@ -37,7 +37,7 @@ export default class AuthStatus extends BaseCommand {
                 this.outputErrorAndExit({
                     message,
                     code,
-                    hint: refreshError.message || "Run '4ge auth login' to re-authenticate."
+                    hint: refreshError.message || "Run '4ge auth:login' to re-authenticate."
                 });
             }
             else {
@@ -47,7 +47,7 @@ export default class AuthStatus extends BaseCommand {
                 else {
                     this.log('⚠ Session expired — token refresh failed.');
                 }
-                this.log(`  ${refreshError.message || "Run '4ge auth login' to re-authenticate."}`);
+                this.log(`  ${refreshError.message || "Run '4ge auth:login' to re-authenticate."}`);
             }
             return;
         }
@@ -65,7 +65,7 @@ export default class AuthStatus extends BaseCommand {
                         this.outputErrorAndExit({
                             message: 'API validation failed for 4GE_API_KEY',
                             code: 'ENV_CREDENTIAL_OVERRIDE',
-                            hint: 'The 4GE_API_KEY environment variable is overriding stored credentials but is invalid. Unset it to use credentials from "4ge auth login".'
+                            hint: 'The 4GE_API_KEY environment variable is overriding stored credentials but is invalid. Unset it to use credentials from "4ge auth:login".'
                         });
                     }
                     else {
@@ -77,7 +77,7 @@ export default class AuthStatus extends BaseCommand {
                         this.log('⚠ Using API key from 4GE_API_KEY environment variable, but server validation failed.');
                         this.log('');
                         this.log('The 4GE_API_KEY environment variable takes priority over stored credentials.');
-                        this.log('FIX: Unset 4GE_API_KEY (e.g., `unset 4GE_API_KEY`) to use credentials from `4ge auth login`.');
+                        this.log('FIX: Unset 4GE_API_KEY (e.g., `unset 4GE_API_KEY`) to use credentials from `4ge auth:login`.');
                     }
                     else {
                         this.log(`Authenticated via ${activeCredential.source}${activeCredential.profile ? ` (profile: ${activeCredential.profile})` : ''}, but API validation failed.`);

package/dist/commands/config/index.js

@@ -3,7 +3,7 @@ export default class ConfigIndex extends Command {
     static description = 'Manage CLI configuration';
     static hidden = true;
     async run() {
-        this.log('Use `4ge config manage` for interactive configuration.');
-        this.log('Use `4ge config show`, `4ge config get`, or `4ge config set` for direct access.');
+        this.log('Use `4ge config:manage` for interactive configuration.');
+        this.log('Use `4ge config:show`, `4ge config:get`, or `4ge config:set` for direct access.');
     }
 }

package/dist/commands/config/show.js

@@ -26,8 +26,8 @@ export default class ConfigShow extends BaseCommand {
             ] }));
         if (this.isInteractiveMode) {
             await this.handleActionHints([
-                { label: 'Set config', command: '4ge config set <key> <value>' },
-                { label: 'Get config', command: '4ge config get <key>' },
+                { label: 'Set config', command: '4ge config:set <key> <value>' },
+                { label: 'Get config', command: '4ge config:get <key>' },
             ]);
         }
     }

package/dist/commands/epic/list.js

@@ -75,7 +75,7 @@ export default class EpicList extends BaseCommand {
                         const selectedId = await this.selectOption('Select an epic for details:', options, { headerVariant: 'compact' });
                         if (selectedId) {
                             const { default: chalk } = await import('chalk');
-                            this.log(`\n  🚀 Run: ${chalk.cyan(`4ge epic show ${selectedId}`)}\n`);
+                            this.log(`\n  🚀 Run: ${chalk.cyan(`4ge epic:show ${selectedId}`)}\n`);
                         }
                     }
                     if (metadata?.action_hints) {

package/dist/commands/feature/list.js

@@ -77,7 +77,7 @@ export default class FeatureList extends BaseCommand {
                         const selectedId = await this.selectOption('Select a feature for details:', options, { headerVariant: 'compact' });
                         if (selectedId) {
                             const { default: chalk } = await import('chalk');
-                            this.log(`\n  🚀 Run: ${chalk.cyan(`4ge feature show ${selectedId}`)}\n`);
+                            this.log(`\n  🚀 Run: ${chalk.cyan(`4ge feature:show ${selectedId}`)}\n`);
                         }
                     }
                     if (metadata?.action_hints) {

package/dist/commands/flow/list.js

@@ -69,7 +69,7 @@ export default class FlowList extends BaseCommand {
                         const selectedId = await this.selectOption('Select a flow for details:', options, { headerVariant: 'compact' });
                         if (selectedId) {
                             const { default: chalk } = await import('chalk');
-                            this.log(`\n  🚀 Run: ${chalk.cyan(`4ge flow show ${selectedId}`)}\n`);
+                            this.log(`\n  🚀 Run: ${chalk.cyan(`4ge flow:show ${selectedId}`)}\n`);
                         }
                     }
                     if (metadata?.action_hints) {

package/dist/commands/idea/graduate.js

@@ -74,8 +74,8 @@ export default class IdeaGraduate extends BaseCommand {
                 if (this.isInteractiveMode) {
                     const { default: chalk } = await import('chalk');
                     this.log(`\n  🚀 Next steps:`);
-                    this.log(`  - Project info: ${chalk.cyan(`4ge project info --id ${result.id}`)}`);
-                    this.log(`  - Pull plan:    ${chalk.cyan(`4ge plan pull --project ${result.id}`)}`);
+                    this.log(`  - Project info: ${chalk.cyan(`4ge project:info --id ${result.id}`)}`);
+                    this.log(`  - Pull plan:    ${chalk.cyan(`4ge plan:pull --project ${result.id}`)}`);
                     if (metadata?.action_hints) {
                         await this.handleActionHints(metadata.action_hints);
                     }

package/dist/commands/init.js

@@ -326,7 +326,7 @@ export default class Init extends BaseCommand {
                     this.log(`Skill installed at: ${skillPath}`);
                     this.log(chalk.dim('Reload your AI agent to pick up the new skill.'));
                 }
-                this.log(chalk.dim('\nConfigure additional settings with: 4ge config manage'));
+                this.log(chalk.dim('\nConfigure additional settings with: 4ge config:manage'));
                 this.log(chalk.dim('Available: default mode, hierarchy settings, pull settings\n'));
             }
         }

package/dist/commands/login.js

@@ -1,5 +1,5 @@
 import AuthLogin from './auth/login.js';
 export default class Login extends AuthLogin {
-    static description = 'Alias for `4ge auth login`';
+    static description = 'Alias for `4ge auth:login`';
     static hidden = false;
 }

package/dist/commands/project/index.js

@@ -4,6 +4,6 @@ export default class Project extends BaseCommand {
     static hidden = true;
     async run() {
         await this.renderHeader('ready', 'compact');
-        this.log('Use `4ge project list` to list projects.');
+        this.log('Use `4ge project:list` to list projects.');
     }
 }

package/dist/commands/project/list.js

@@ -62,7 +62,7 @@ export default class ProjectList extends BaseCommand {
                         const selectedId = await this.selectOption('Select a project for details:', options, { headerVariant: 'compact' });
                         if (selectedId) {
                             const { default: chalk } = await import('chalk');
-                            this.log(`\n  🚀 Run: ${chalk.cyan(`4ge project show ${selectedId}`)}\n`);
+                            this.log(`\n  🚀 Run: ${chalk.cyan(`4ge project:show ${selectedId}`)}\n`);
                         }
                     }
                     if (metadata?.action_hints) {

package/dist/commands/story/list.js

@@ -65,7 +65,7 @@ export default class StoryList extends BaseCommand {
                         const selectedId = await this.selectOption('Select a story for details:', options, { headerVariant: 'compact' });
                         if (selectedId) {
                             const { default: chalk } = await import('chalk');
-                            this.log(`\n  🚀 Run: ${chalk.cyan(`4ge story show ${selectedId}`)}\n`);
+                            this.log(`\n  🚀 Run: ${chalk.cyan(`4ge story:show ${selectedId}`)}\n`);
                         }
                     }
                     if (metadata?.action_hints) {

package/dist/commands/template/list.js

@@ -66,7 +66,7 @@ export default class TemplateList extends BaseCommand {
                     const selectedId = await this.selectOption('Select a template for details:', options, { headerVariant: 'compact' });
                     if (selectedId) {
                         const { default: chalk } = await import('chalk');
-                        this.log(`\n  🚀 Run: ${chalk.cyan(`4ge template info --id ${selectedId}`)}\n`);
+                        this.log(`\n  🚀 Run: ${chalk.cyan(`4ge template:info --id ${selectedId}`)}\n`);
                     }
                 }
                 if (metadata?.action_hints) {

package/dist/commands/template/pull.js

@@ -87,8 +87,8 @@ export default class TemplatePull extends BaseCommand {
         }
         if (this.isInteractiveMode) {
             await this.handleActionHints([
-                { label: 'List template features', command: `4ge template feature list ${templateId}` },
-                { label: 'Project info', command: '4ge project info' },
+                { label: 'List template features', command: `4ge template:feature:list ${templateId}` },
+                { label: 'Project info', command: '4ge project:info' },
             ]);
         }
     }

package/dist/commands/whoami.js

@@ -1,5 +1,5 @@
 import AuthStatus from './auth/status.js';
 export default class Whoami extends AuthStatus {
-    static description = 'Alias for `4ge auth status`';
+    static description = 'Alias for `4ge auth:status`';
     static hidden = false;
 }

package/dist/core/auth/api-client.js

@@ -16,7 +16,7 @@ export function isAuthError(error) {
  */
 export function getAuthErrorHint(error) {
     if (error?.code === 'TOKEN_EXPIRED') {
-        return "Run '4ge auth login' to re-authenticate";
+        return "Run '4ge auth:login' to re-authenticate";
     }
     if (error?.code === 'INVALID_API_KEY') {
         return 'Check your 4GE_API_KEY environment variable';
@@ -146,7 +146,7 @@ export function createApiClient(opts) {
                 code: isPatAuth ? 'INVALID_API_KEY' : 'TOKEN_EXPIRED',
                 hint: isPatAuth
                     ? 'Check your 4GE_API_KEY environment variable'
-                    : "Run '4ge auth login' to re-authenticate",
+                    : "Run '4ge auth:login' to re-authenticate",
             };
             return authError;
         }

package/dist/core/auth/token-refresh.js

@@ -66,7 +66,7 @@ export async function ensureFreshToken() {
     }
     if (result.error || !result.data) {
         // Server is reachable and explicitly rejected the refresh token.
-        throw new Error(`Session expired. Please re-authenticate: run '4ge auth login'\n` +
+        throw new Error(`Session expired. Please re-authenticate: run '4ge auth:login'\n` +
             `Details: ${result.error?.message || 'Refresh token is invalid or expired'}`);
     }
     try {

package/dist/core/project/markdown.js

@@ -33,5 +33,5 @@ export function generateReadmeMd(project, filesGenerated) {
 ${fileLinks}
 
 ---
-*Generated by \`4ge project pull\` on ${date}*`;
+*Generated by \`4ge project:pull\` on ${date}*`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4ge/cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "4ge Service Architecture Bridge & CLI",
   "main": "dist/index.js",
   "bin": {

package/skills/4ge-cli.md

@@ -13,15 +13,30 @@ Before using this CLI, the user **MUST** have completed:
 The CLI is already installed and configured in this project.
 
 ## ⌨️ Command Syntax
-All interactions follow this structure:
+
+**Convention (hard rule):** commands are `4ge <namespace>:<command> [--params]` —
+a colon between namespace and command, **never a space**.
+
+| Correct | Wrong |
+|---|---|
+| `4ge epic:list` | ~~`4ge epic list`~~ |
+| `4ge project:pull --json` | ~~`4ge project pull --json`~~ |
+| `4ge flow:show --id <id>` | ~~`4ge flow show --id <id>`~~ |
+| `4ge auth:status` | ~~`4ge auth status`~~ |
+
+Nested commands chain with more colons: `4ge template:feature:list`.
+A few root commands take no colon (`4ge init`, `4ge whoami`, `4ge login`) —
+single words with no nested command.
+
+Full form:
 
 ```bash
 4ge <namespace>:<command> [options] --json
 ```
 
-- **Namespace:Command**: Colon-separated (e.g. `epic:list`, `story:show`, `auth:status`).
-- **Required flag**: `--json` is **mandatory** in agent mode for machine-readable output.
-- **Positional arguments**: A few commands take a direct arg without a flag (e.g. `idea:show <ID>`).
+- **`--json` is mandatory** in agent mode for machine-readable output.
+- **Positional arguments**: a few commands take a direct arg without a flag
+  (e.g. `4ge idea:show <ID>`).
 
 ## 🛠 Usage Guidelines