@forgehive/forge-cli 0.3.18 → 0.5.1

package/dist/tasks/task/describe.d.ts

@@ -2,7 +2,7 @@ import { type ForgeConf } from '../types';
 export declare const describe: import("@forgehive/task").TaskInstanceType<(argv: {
     descriptorName: string;
 }, boundaries: import("@forgehive/task").WrappedBoundaries<{
-    loadConf: (args: {}) => Promise<Promise<ForgeConf>>;
+    loadConf: (args: Record<string, unknown>) => Promise<Promise<ForgeConf>>;
     bundleCreate: (args: {
         entryPoint: string;
         outputFile: string;
@@ -21,7 +21,7 @@ export declare const describe: import("@forgehive/task").TaskInstanceType<(argv:
     schema: any;
     boundaries: string[];
 }>, {
-    loadConf: (args: {}) => Promise<Promise<ForgeConf>>;
+    loadConf: (args: Record<string, unknown>) => Promise<Promise<ForgeConf>>;
     bundleCreate: (args: {
         entryPoint: string;
         outputFile: string;

package/dist/tasks/task/describe.js

@@ -17,7 +17,7 @@ const load_1 = require("../bundle/load");
 const load_2 = require("../conf/load");
 const description = 'Describe a task with detailed information about its schema, boundaries and configuration';
 const schema = new schema_1.Schema({
-    descriptorName: schema_1.Schema.string()
+    descriptorName: schema_1.Schema.string().describe('The task descriptor name to describe (e.g. domain:taskName)')
 });
 const boundaries = {
     loadConf: load_2.load.asBoundary(),

package/dist/tasks/task/download.d.ts

@@ -3,9 +3,9 @@ export declare const download: import("@forgehive/task").TaskInstanceType<(argv:
     descriptorName: string;
     uuid: string;
 }, boundaries: import("@forgehive/task").WrappedBoundaries<{
-    loadCurrentProfile: (args: {}) => Promise<Promise<Profile>>;
+    loadCurrentProfile: (args: Record<string, unknown>) => Promise<Promise<Profile>>;
     downloadTask: (uuid: string, profile: Profile) => Promise<any>;
-    loadConf: (args: {}) => Promise<Promise<ForgeConf>>;
+    loadConf: (args: Record<string, unknown>) => Promise<Promise<ForgeConf>>;
     getCwd: () => Promise<string>;
     parseTaskName: (taskDescriptor: string) => Promise<{
         descriptor: string;
@@ -40,9 +40,9 @@ export declare const download: import("@forgehive/task").TaskInstanceType<(argv:
     error?: undefined;
     message?: undefined;
 }>, {
-    loadCurrentProfile: (args: {}) => Promise<Promise<Profile>>;
+    loadCurrentProfile: (args: Record<string, unknown>) => Promise<Promise<Profile>>;
     downloadTask: (uuid: string, profile: Profile) => Promise<any>;
-    loadConf: (args: {}) => Promise<Promise<ForgeConf>>;
+    loadConf: (args: Record<string, unknown>) => Promise<Promise<ForgeConf>>;
     getCwd: () => Promise<string>;
     parseTaskName: (taskDescriptor: string) => Promise<{
         descriptor: string;

package/dist/tasks/task/download.js

@@ -16,8 +16,8 @@ const camelCase_1 = require("../../utils/camelCase");
 const load_1 = require("../conf/load");
 const loadCurrent_1 = require("../auth/loadCurrent");
 const schema = new schema_1.Schema({
-    descriptorName: schema_1.Schema.string(),
-    uuid: schema_1.Schema.string()
+    descriptorName: schema_1.Schema.string().describe('The task descriptor name (e.g. domain:taskName)'),
+    uuid: schema_1.Schema.string().describe('The UUID of the task version to download')
 });
 const boundaries = {
     loadCurrentProfile: loadCurrent_1.loadCurrent.asBoundary(),

package/dist/tasks/task/fingerprint.d.ts

@@ -2,7 +2,7 @@ export declare const fingerprint: import("@forgehive/task").TaskInstanceType<(ar
     descriptorName: string;
 }, boundaries: import("@forgehive/task").WrappedBoundaries<{
     getCwd: () => Promise<string>;
-    loadConf: (args: {}) => Promise<Promise<import("../types").ForgeConf>>;
+    loadConf: (args: Record<string, unknown>) => Promise<Promise<import("../types").ForgeConf>>;
     bundleFingerprint: (args: {
         descriptorName: string;
         filePath?: string | undefined;
@@ -40,7 +40,7 @@ export declare const fingerprint: import("@forgehive/task").TaskInstanceType<(ar
     };
 }>, {
     getCwd: () => Promise<string>;
-    loadConf: (args: {}) => Promise<Promise<import("../types").ForgeConf>>;
+    loadConf: (args: Record<string, unknown>) => Promise<Promise<import("../types").ForgeConf>>;
     bundleFingerprint: (args: {
         descriptorName: string;
         filePath?: string | undefined;

package/dist/tasks/task/fingerprint.js

@@ -14,7 +14,7 @@ const load_1 = require("../conf/load");
 const fingerprint_1 = require("../bundle/fingerprint");
 const description = 'Analyze a specific task and generate detailed fingerprint without bundling';
 const schema = new schema_1.Schema({
-    descriptorName: schema_1.Schema.string()
+    descriptorName: schema_1.Schema.string().describe('The task descriptor name to fingerprint (e.g. domain:taskName)')
 });
 const boundaries = {
     getCwd: async () => {

package/dist/tasks/task/invoke.d.ts

@@ -4,13 +4,13 @@ export declare const invoke: import("@forgehive/task").TaskInstanceType<(argv: {
     descriptorName: string;
     json: string;
 }, boundaries: import("@forgehive/task").WrappedBoundaries<{
-    loadConf: (args: {}) => Promise<Promise<ForgeConf>>;
-    loadCurrentProfile: (args: {}) => Promise<Promise<Profile>>;
+    loadConf: (args: Record<string, unknown>) => Promise<Promise<ForgeConf>>;
+    loadCurrentProfile: (args: Record<string, unknown>) => Promise<Promise<Profile>>;
     parseJSON: (jsonString: string) => Promise<unknown>;
     invokeTask: (projectUuid: string, taskUuid: string, profile: Profile, taskName: string, payload: unknown) => Promise<InvokeResult | null>;
 }>) => Promise<unknown>, {
-    loadConf: (args: {}) => Promise<Promise<ForgeConf>>;
-    loadCurrentProfile: (args: {}) => Promise<Promise<Profile>>;
+    loadConf: (args: Record<string, unknown>) => Promise<Promise<ForgeConf>>;
+    loadCurrentProfile: (args: Record<string, unknown>) => Promise<Promise<Profile>>;
     parseJSON: (jsonString: string) => Promise<unknown>;
     invokeTask: (projectUuid: string, taskUuid: string, profile: Profile, taskName: string, payload: unknown) => Promise<InvokeResult | null>;
 }>;

package/dist/tasks/task/invoke.js

@@ -12,8 +12,8 @@ const loadCurrent_1 = require("../auth/loadCurrent");
 const name = 'task:invoke';
 const description = 'Invoke a deployed task remotely using the Hive API';
 const schema = new schema_1.Schema({
-    descriptorName: schema_1.Schema.string(),
-    json: schema_1.Schema.string()
+    descriptorName: schema_1.Schema.string().describe('The task descriptor name (e.g. domain:taskName)'),
+    json: schema_1.Schema.string().describe('JSON string of arguments to pass to the task')
 });
 const boundaries = {
     loadConf: load_1.load.asBoundary(),

package/dist/tasks/task/list.d.ts

@@ -1,6 +1,6 @@
 import { type ForgeConf } from '../types';
-export declare const list: import("@forgehive/task").TaskInstanceType<(argv: {}, boundaries: import("@forgehive/task").WrappedBoundaries<{
-    loadConf: (args: {}) => Promise<Promise<ForgeConf>>;
+export declare const list: import("@forgehive/task").TaskInstanceType<(argv: Record<string, unknown>, boundaries: import("@forgehive/task").WrappedBoundaries<{
+    loadConf: (args: Record<string, unknown>) => Promise<Promise<ForgeConf>>;
 }>) => Promise<{
     taskCount: number;
     tasks: never[];
@@ -8,5 +8,5 @@ export declare const list: import("@forgehive/task").TaskInstanceType<(argv: {},
     taskCount: number;
     tasks?: undefined;
 }>, {
-    loadConf: (args: {}) => Promise<Promise<ForgeConf>>;
+    loadConf: (args: Record<string, unknown>) => Promise<Promise<ForgeConf>>;
 }>;

package/dist/tasks/task/publish.d.ts

@@ -4,8 +4,8 @@ export declare const publish: import("@forgehive/task").TaskInstanceType<(argv:
     descriptorName: string;
 }, boundaries: import("@forgehive/task").WrappedBoundaries<{
     getCwd: () => Promise<string>;
-    loadConf: (args: {}) => Promise<Promise<import("../types").ForgeConf>>;
-    loadCurrentProfile: (args: {}) => Promise<Promise<Profile>>;
+    loadConf: (args: Record<string, unknown>) => Promise<Promise<import("../types").ForgeConf>>;
+    loadCurrentProfile: (args: Record<string, unknown>) => Promise<Promise<Profile>>;
     bundleCreate: (args: {
         entryPoint: string;
         outputFile: string;
@@ -59,8 +59,8 @@ export declare const publish: import("@forgehive/task").TaskInstanceType<(argv:
     fingerprint: boolean;
 }>, {
     getCwd: () => Promise<string>;
-    loadConf: (args: {}) => Promise<Promise<import("../types").ForgeConf>>;
-    loadCurrentProfile: (args: {}) => Promise<Promise<Profile>>;
+    loadConf: (args: Record<string, unknown>) => Promise<Promise<import("../types").ForgeConf>>;
+    loadCurrentProfile: (args: Record<string, unknown>) => Promise<Promise<Profile>>;
     bundleCreate: (args: {
         entryPoint: string;
         outputFile: string;

package/dist/tasks/task/publish.js

@@ -20,7 +20,7 @@ const zip_1 = require("../bundle/zip");
 const fingerprint_1 = require("../bundle/fingerprint");
 const loadCurrent_1 = require("../auth/loadCurrent");
 const schema = new schema_1.Schema({
-    descriptorName: schema_1.Schema.string()
+    descriptorName: schema_1.Schema.string().describe('The task descriptor name to publish (e.g. domain:taskName)')
 });
 const boundaries = {
     getCwd: async () => {

package/dist/tasks/task/remove.d.ts

@@ -2,14 +2,14 @@ import { type ForgeConf } from '../types';
 export declare const remove: import("@forgehive/task").TaskInstanceType<(argv: {
     descriptorName: string;
 }, boundaries: import("@forgehive/task").WrappedBoundaries<{
-    loadConf: (args: {}) => Promise<Promise<ForgeConf>>;
+    loadConf: (args: Record<string, unknown>) => Promise<Promise<ForgeConf>>;
     persistConf: (forge: ForgeConf) => Promise<void>;
     deleteFile: (filePath: string) => Promise<void>;
 }>) => Promise<{
     status: string;
     message: string;
 }>, {
-    loadConf: (args: {}) => Promise<Promise<ForgeConf>>;
+    loadConf: (args: Record<string, unknown>) => Promise<Promise<ForgeConf>>;
     persistConf: (forge: ForgeConf) => Promise<void>;
     deleteFile: (filePath: string) => Promise<void>;
 }>;

package/dist/tasks/task/remove.js

@@ -13,7 +13,7 @@ const path_1 = __importDefault(require("path"));
 const promises_1 = __importDefault(require("fs/promises"));
 const load_1 = require("../conf/load");
 const schema = new schema_1.Schema({
-    descriptorName: schema_1.Schema.string()
+    descriptorName: schema_1.Schema.string().describe('The task descriptor name to remove (e.g. domain:taskName)')
 });
 const boundaries = {
     loadConf: load_1.load.asBoundary(),

package/dist/tasks/task/replay.d.ts

@@ -11,13 +11,13 @@ interface Fixture {
     context: Record<string, unknown>;
 }
 export declare const replay: import("@forgehive/task").TaskInstanceType<(argv: {
-    path: string;
     descriptorName: string;
+    path: string;
     cache?: string | undefined;
 }, boundaries: import("@forgehive/task").WrappedBoundaries<{
     readFixture: (filePath: string) => Promise<Fixture>;
-    loadConf: (args: {}) => Promise<Promise<ForgeConf>>;
-    loadCurrentProfile: (args: {}) => Promise<Promise<Profile>>;
+    loadConf: (args: Record<string, unknown>) => Promise<Promise<ForgeConf>>;
+    loadCurrentProfile: (args: Record<string, unknown>) => Promise<Promise<Profile>>;
     bundleCreate: (args: {
         entryPoint: string;
         outputFile: string;
@@ -35,8 +35,8 @@ export declare const replay: import("@forgehive/task").TaskInstanceType<(argv: {
     }>;
 }>) => Promise<any>, {
     readFixture: (filePath: string) => Promise<Fixture>;
-    loadConf: (args: {}) => Promise<Promise<ForgeConf>>;
-    loadCurrentProfile: (args: {}) => Promise<Promise<Profile>>;
+    loadConf: (args: Record<string, unknown>) => Promise<Promise<ForgeConf>>;
+    loadCurrentProfile: (args: Record<string, unknown>) => Promise<Promise<Profile>>;
     bundleCreate: (args: {
         entryPoint: string;
         outputFile: string;

package/dist/tasks/task/replay.js

@@ -19,9 +19,9 @@ const load_2 = require("../conf/load");
 const loadCurrent_1 = require("../auth/loadCurrent");
 const description = 'Replay a task execution from a specified path';
 const schema = new schema_1.Schema({
-    descriptorName: schema_1.Schema.string(),
-    path: schema_1.Schema.string(),
-    cache: schema_1.Schema.string().optional()
+    descriptorName: schema_1.Schema.string().describe('The task descriptor name to replay (e.g. domain:taskName)'),
+    path: schema_1.Schema.string().describe('Path to the execution log fixture to replay'),
+    cache: schema_1.Schema.string().describe('Cache mode for boundaries during replay').optional()
 });
 const boundaries = {
     readFixture: async (filePath) => {

package/dist/tasks/task/run.d.ts

@@ -4,8 +4,8 @@ export declare const run: import("@forgehive/task").TaskInstanceType<(argv: {
     descriptorName: string;
     args: Record<string, string | number | boolean>;
 }, boundaries: import("@forgehive/task").WrappedBoundaries<{
-    loadConf: (args: {}) => Promise<Promise<ForgeConf>>;
-    loadCurrentProfile: (args: {}) => Promise<Promise<Profile>>;
+    loadConf: (args: Record<string, unknown>) => Promise<Promise<ForgeConf>>;
+    loadCurrentProfile: (args: Record<string, unknown>) => Promise<Promise<Profile>>;
     bundleCreate: (args: {
         entryPoint: string;
         outputFile: string;
@@ -24,8 +24,8 @@ export declare const run: import("@forgehive/task").TaskInstanceType<(argv: {
         skipRemoteLog?: boolean;
     }>;
 }>) => Promise<any>, {
-    loadConf: (args: {}) => Promise<Promise<ForgeConf>>;
-    loadCurrentProfile: (args: {}) => Promise<Promise<Profile>>;
+    loadConf: (args: Record<string, unknown>) => Promise<Promise<ForgeConf>>;
+    loadCurrentProfile: (args: Record<string, unknown>) => Promise<Promise<Profile>>;
     bundleCreate: (args: {
         entryPoint: string;
         outputFile: string;

package/dist/tasks/task/run.js

@@ -22,8 +22,8 @@ const loadCurrent_1 = require("../auth/loadCurrent");
 // For now, we'll use a simple schema without the record type
 // TODO: Use Schema.record once it's properly built and available
 const schema = new schema_1.Schema({
-    descriptorName: schema_1.Schema.string(),
-    args: schema_1.Schema.mixedRecord()
+    descriptorName: schema_1.Schema.string().describe('The task descriptor name to run (e.g. domain:taskName)'),
+    args: schema_1.Schema.mixedRecord().describe('Arguments to pass to the task')
     // args will be passed directly without schema validation for now
 });
 const boundaries = {

package/dist/test/tasks/create.test.js

@@ -19,8 +19,9 @@ const name = 'sample:newTask'
 const description = 'Add task description here'
 
 const schema = new Schema({
-  // Add your schema definitions here
-  // example: myParam: Schema.string()
+  // Add your schema definitions here.
+  // Use .describe() so the field shows up in \`forge sample:newTask --help\`.
+  // example: myParam: Schema.string().describe('What this parameter is for')
 })
 
 const boundaries = {

package/dist/utils/taskAnalysis.d.ts

@@ -1,13 +1,19 @@
 interface SchemaProperty {
     name?: string;
     type: string;
+    format?: string;
+    description?: string;
     optional?: boolean;
     default?: string;
     properties?: Record<string, SchemaProperty>;
+    additionalProperties?: SchemaProperty | {
+        anyOf: SchemaProperty[];
+    };
 }
 interface InputSchema {
     type: string;
     properties: Record<string, SchemaProperty>;
+    required?: string[];
 }
 interface OutputType {
     type: string;

package/dist/utils/taskAnalysis.js

@@ -502,64 +502,105 @@ function analyzeSchemaArg(node, sourceFile) {
         const arg = node.arguments?.[0];
         if (arg && ts.isObjectLiteralExpression(arg)) {
             const properties = {};
+            const required = [];
             arg.properties.forEach(prop => {
                 if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
                     const propName = prop.name.text;
                     const propValue = analyzeSchemaProp(prop.initializer, sourceFile);
+                    // Optionality is expressed by absence from `required` (JSON Schema)
+                    const isOptional = propValue.optional === true;
+                    delete propValue.optional;
                     properties[propName] = propValue;
+                    if (!isOptional) {
+                        required.push(propName);
+                    }
                 }
             });
-            return { type: 'object', properties };
+            const result = { type: 'object', properties };
+            if (required.length > 0) {
+                result.required = required;
+            }
+            return result;
         }
     }
     return { type: 'object', properties: {} };
 }
-// Enhanced schema property analysis
-function analyzeSchemaProp(node, sourceFile) {
-    // Analyze Schema.string(), Schema.number(), etc.
-    if (ts.isCallExpression(node)) {
-        if (ts.isPropertyAccessExpression(node.expression) &&
-            ts.isIdentifier(node.expression.expression) &&
-            node.expression.expression.text === 'Schema') {
-            const methodName = node.expression.name.text;
-            const baseType = { type: getSchemaTypeFromMethod(methodName) };
-            return baseType;
-        }
-    }
-    // Handle chained calls like Schema.number().optional()
-    if (ts.isCallExpression(node)) {
-        if (ts.isPropertyAccessExpression(node.expression)) {
-            const chainedMethod = node.expression.name.text;
-            if (chainedMethod === 'optional') {
-                // This is a .optional() call, get the base type
-                const baseCall = node.expression.expression;
-                if (ts.isCallExpression(baseCall)) {
-                    const baseType = analyzeSchemaProp(baseCall, sourceFile);
-                    return { ...baseType, optional: true };
-                }
+// Analyze a single schema field, unwrapping the call chain
+// (e.g. Schema.string().describe('...').optional()) into a JSON Schema property.
+function analyzeSchemaProp(node, _sourceFile) {
+    let optional = false;
+    let description;
+    let defaultValue;
+    let current = node;
+    while (ts.isCallExpression(current) && ts.isPropertyAccessExpression(current.expression)) {
+        const methodName = current.expression.name.text;
+        const inner = current.expression.expression;
+        // Base call: Schema.<type>(...)
+        if (ts.isIdentifier(inner) && inner.text === 'Schema') {
+            const prop = mapSchemaMethod(methodName);
+            if (description !== undefined) {
+                prop.description = description;
             }
-            else if (chainedMethod === 'default') {
-                // This is a .default() call, get the base type
-                const baseCall = node.expression.expression;
-                if (ts.isCallExpression(baseCall)) {
-                    const baseType = analyzeSchemaProp(baseCall, sourceFile);
-                    const defaultValue = node.arguments[0]?.getText() || 'undefined';
-                    return { ...baseType, default: defaultValue };
-                }
+            if (defaultValue !== undefined) {
+                prop.default = defaultValue;
+            }
+            if (optional) {
+                prop.optional = true;
             }
+            return prop;
         }
+        // Chained modifiers
+        if (methodName === 'optional') {
+            optional = true;
+        }
+        else if (methodName === 'describe') {
+            const arg = current.arguments[0];
+            if (arg && ts.isStringLiteral(arg)) {
+                description = arg.text;
+            }
+        }
+        else if (methodName === 'default') {
+            defaultValue = current.arguments[0]?.getText() ?? 'undefined';
+        }
+        // Other modifiers (min/max/regex/...) don't change the JSON Schema type, so
+        // we keep unwrapping until we reach the base Schema.<type>() call.
+        current = inner;
     }
     return { type: 'unknown' };
 }
-function getSchemaTypeFromMethod(methodName) {
-    const typeMap = {
-        string: 'string',
-        number: 'number',
-        boolean: 'boolean',
-        array: 'array',
-        object: 'object'
-    };
-    return typeMap[methodName] || 'unknown';
+// Map a Schema.* helper name to its JSON Schema representation, matching what
+// Schema.describe() emits at runtime.
+function mapSchemaMethod(methodName) {
+    switch (methodName) {
+        case 'string':
+            return { type: 'string' };
+        case 'number':
+            return { type: 'number' };
+        case 'boolean':
+            return { type: 'boolean' };
+        case 'date':
+            return { type: 'string', format: 'date-time' };
+        case 'email':
+            return { type: 'string', format: 'email' };
+        case 'uuid':
+            return { type: 'string', format: 'uuid' };
+        case 'url':
+            return { type: 'string', format: 'uri' };
+        case 'array':
+            return { type: 'array' };
+        case 'object':
+            return { type: 'object' };
+        case 'stringRecord':
+            return { type: 'object', additionalProperties: { type: 'string' } };
+        case 'numberRecord':
+            return { type: 'object', additionalProperties: { type: 'number' } };
+        case 'booleanRecord':
+            return { type: 'object', additionalProperties: { type: 'boolean' } };
+        case 'mixedRecord':
+            return { type: 'object', additionalProperties: { anyOf: [{ type: 'string' }, { type: 'number' }, { type: 'boolean' }] } };
+        default:
+            return { type: 'unknown' };
+    }
 }
 // Enhanced boundary analysis that extracts detailed boundary information
 function analyzeBoundariesWithTypes(node, sourceFile) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgehive/forge-cli",
-  "version": "0.3.18",
+  "version": "0.5.1",
   "description": "TypeScript CLI application",
   "license": "MIT",
   "main": "dist/index.js",
@@ -10,11 +10,11 @@
   "publishConfig": {
     "access": "public",
     "dependencies": {
-      "@forgehive/hive-sdk": "^0.2.0",
-      "@forgehive/record-tape": "^0.2.7",
-      "@forgehive/runner": "^0.2.7",
-      "@forgehive/schema": "^0.1.4",
-      "@forgehive/task": "^0.2.7",
+      "@forgehive/hive-sdk": "^0.3.0",
+      "@forgehive/record-tape": "^0.3.0",
+      "@forgehive/runner": "^0.3.0",
+      "@forgehive/schema": "^0.2.0",
+      "@forgehive/task": "^0.3.0",
       "esbuild": "^0.25.0",
       "handlebars": "^4.7.8",
       "minimist": "^1.2.8",
@@ -30,11 +30,11 @@
     "minimist": "^1.2.8",
     "typescript": "^5.3.3",
     "uuid": "^11.1.0",
-    "@forgehive/record-tape": "0.2.7",
-    "@forgehive/task": "0.2.7",
-    "@forgehive/hive-sdk": "0.2.0",
-    "@forgehive/schema": "0.1.4",
-    "@forgehive/runner": "0.2.7"
+    "@forgehive/hive-sdk": "0.3.0",
+    "@forgehive/record-tape": "0.3.0",
+    "@forgehive/task": "0.3.0",
+    "@forgehive/schema": "0.2.0",
+    "@forgehive/runner": "0.3.0"
   },
   "devDependencies": {
     "@types/archiver": "^6.0.3",

package/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+overrides:
+  '@forgehive/forge-cli': 'link:'

package/src/runner.ts

@@ -93,11 +93,88 @@ runner.load('project:link', linkProject)
 runner.load('project:unlink', unlinkProject)
 runner.load('project:sync', syncProject)
 
+function printAllHelp(): void {
+  const tasks = runner.describe()
+  console.log('Usage: forge <command> [options]')
+  console.log('')
+  console.log('Commands:')
+
+  const groups: Record<string, string[]> = {}
+  for (const name of Object.keys(tasks).sort()) {
+    const group = name.includes(':') ? name.split(':')[0] : name
+    if (!groups[group]) {
+      groups[group] = []
+    }
+    groups[group].push(name)
+  }
+
+  for (const [group, commands] of Object.entries(groups)) {
+    console.log(`\n  ${group}:`)
+    for (const cmd of commands) {
+      const desc = tasks[cmd].description || ''
+      console.log(`    ${cmd.padEnd(26)} ${desc}`)
+    }
+  }
+
+  console.log('')
+  console.log('Run "forge <command> --help" for more information on a specific command.')
+}
+
+function printTaskHelp(taskName: string): void {
+  const task = runner.getTask(taskName)
+  if (!task) {
+    return
+  }
+
+  // `describe()` returns JSON Schema: fields live under `properties`, optionality
+  // is the absence from `required`, and `description` carries the help text.
+  const schema = task.describe()
+  const properties = (schema.properties ?? {}) as Record<string, { type?: string; format?: string; description?: string }>
+  const required = new Set((schema.required ?? []) as string[])
+  const keys = Object.keys(properties)
+
+  console.log(`Usage: forge ${taskName}${keys.length > 0 ? ' [options]' : ''}`)
+  console.log('')
+
+  const desc = task.getDescription()
+  if (desc) {
+    console.log(desc)
+    console.log('')
+  }
+
+  if (keys.length > 0) {
+    console.log('Options:')
+    for (const key of keys) {
+      const field = properties[key]
+      const type = field.format ?? field.type ?? 'unknown'
+      const optional = required.has(key) ? '' : ' (optional)'
+      const description = field.description ? ` - ${field.description}` : ''
+      console.log(`  --${key.padEnd(20)} ${`${type}${optional}`.padEnd(20)}${description}`)
+    }
+    console.log('')
+  } else {
+    console.log('This command takes no options.')
+    console.log('')
+  }
+}
+
 // Set handler
 runner.setHandler(async (data: ParsedArgs): Promise<unknown> => {
   const parsedArgs = runner.parseArguments(data)
   const { taskName, action, args } = parsedArgs
 
+  const helpRequested = (args as Record<string, unknown>)?.help === true
+
+  if (helpRequested || taskName === 'undefined' || !taskName) {
+    if (helpRequested && runner.getTask(taskName)) {
+      printTaskHelp(taskName)
+    } else {
+      printAllHelp()
+    }
+    setTimeout(() => { process.exit(0) }, 100)
+    return { silent: true, outcome: 'Success', taskName, result: null }
+  }
+
   console.log('===============================================')
   console.log(`Running: ${taskName} ${action ? action : ''} ${JSON.stringify(args)}`)
   console.log('===============================================')

package/src/tasks/auth/add.ts

@@ -12,10 +12,10 @@ import { load as loadProfiles } from './load'
 import { type Profiles } from '../types'
 
 const schema = new Schema({
-  name: Schema.string(),
-  apiKey: Schema.string(),
-  apiSecret: Schema.string(),
-  url: Schema.string()
+  name: Schema.string().describe('The name of the profile'),
+  apiKey: Schema.string().describe('The API key for the profile'),
+  apiSecret: Schema.string().describe('The API secret for the profile'),
+  url: Schema.string().describe('The URL for the profile')
 })
 
 const boundaries = {

package/src/tasks/auth/remove.ts

@@ -12,7 +12,7 @@ import { load as loadProfiles } from './load'
 import { type Profiles } from '../types'
 
 const schema = new Schema({
-  profileName: Schema.string()
+  profileName: Schema.string().describe('The name of the auth profile to remove')
 })
 
 const boundaries = {

package/src/tasks/auth/switch.ts

@@ -12,7 +12,7 @@ import { load as loadProfiles } from './load'
 import { type Profiles } from '../types'
 
 const schema = new Schema({
-  profileName: Schema.string()
+  profileName: Schema.string().describe('The name of the auth profile to switch to')
 })
 
 const boundaries = {