@constructive-io/graphql-codegen 4.8.1 → 4.12.2

package/core/codegen/cli/docs-generator.js

@@ -12,9 +12,10 @@ exports.generateMultiTargetSkills = generateMultiTargetSkills;
 const komoji_1 = require("komoji");
 const docs_utils_1 = require("../docs-utils");
 const utils_1 = require("../utils");
+const table_command_generator_1 = require("./table-command-generator");
 var docs_utils_2 = require("../docs-utils");
 Object.defineProperty(exports, "resolveDocsConfig", { enumerable: true, get: function () { return docs_utils_2.resolveDocsConfig; } });
-function generateReadme(tables, customOperations, toolName) {
+function generateReadme(tables, customOperations, toolName, registry) {
     const lines = [];
     lines.push(...(0, docs_utils_1.getReadmeHeader)(`${toolName} CLI`));
     lines.push('## Setup');
@@ -98,10 +99,21 @@ function generateReadme(tables, customOperations, toolName) {
             lines.push('| Field | Type |');
             lines.push('|-------|------|');
             for (const f of scalarFields) {
-                lines.push(`| \`${f.name}\` | ${f.type.gqlType} |`);
+                lines.push(`| \`${f.name}\` | ${(0, docs_utils_1.cleanTypeName)(f.type.gqlType)} |`);
             }
             lines.push('');
-            lines.push(`**Create fields:** ${editableFields.map((f) => `\`${f.name}\``).join(', ')}`);
+            const defaultFields = (0, table_command_generator_1.getFieldsWithDefaults)(table, registry);
+            const requiredCreate = editableFields.filter((f) => !defaultFields.has(f.name));
+            const optionalCreate = editableFields.filter((f) => defaultFields.has(f.name));
+            if (requiredCreate.length > 0) {
+                lines.push(`**Required create fields:** ${requiredCreate.map((f) => `\`${f.name}\``).join(', ')}`);
+            }
+            if (optionalCreate.length > 0) {
+                lines.push(`**Optional create fields (backend defaults):** ${optionalCreate.map((f) => `\`${f.name}\``).join(', ')}`);
+            }
+            if (requiredCreate.length === 0 && optionalCreate.length === 0) {
+                lines.push(`**Create fields:** ${editableFields.map((f) => `\`${f.name}\``).join(', ')}`);
+            }
             lines.push('');
         }
     }
@@ -110,18 +122,20 @@ function generateReadme(tables, customOperations, toolName) {
         lines.push('');
         for (const op of customOperations) {
             const kebab = (0, komoji_1.toKebabCase)(op.name);
+            const flat = (0, docs_utils_1.flattenArgs)(op.args, registry);
             lines.push(`### \`${kebab}\``);
             lines.push('');
             lines.push(op.description || op.name);
             lines.push('');
             lines.push(`- **Type:** ${op.kind}`);
-            if (op.args.length > 0) {
+            if (flat.length > 0) {
                 lines.push('- **Arguments:**');
                 lines.push('');
                 lines.push('  | Argument | Type |');
                 lines.push('  |----------|------|');
-                for (const arg of op.args) {
-                    lines.push(`  | \`${arg.name}\` | ${(0, docs_utils_1.formatArgType)(arg)} |`);
+                for (const a of flat) {
+                    const reqLabel = a.required ? ' (required)' : '';
+                    lines.push(`  | \`--${a.flag}\` | ${a.type}${reqLabel} |`);
                 }
             }
             else {
@@ -139,13 +153,21 @@ function generateReadme(tables, customOperations, toolName) {
     lines.push(`${toolName} car get --id <uuid> | jq '.'`);
     lines.push('```');
     lines.push('');
+    lines.push('## Non-Interactive Mode');
+    lines.push('');
+    lines.push('Use `--no-tty` to skip all interactive prompts (useful for scripts and CI):');
+    lines.push('');
+    lines.push('```bash');
+    lines.push(`${toolName} --no-tty car create --name "Sedan" --year 2024`);
+    lines.push('```');
+    lines.push('');
     lines.push(...(0, docs_utils_1.getReadmeFooter)());
     return {
         fileName: 'README.md',
         content: lines.join('\n'),
     };
 }
-function generateAgentsDocs(tables, customOperations, toolName) {
+function generateAgentsDocs(tables, customOperations, toolName, registry) {
     const lines = [];
     lines.push(`# ${toolName} CLI - Agent Reference`);
     lines.push('');
@@ -217,6 +239,13 @@ function generateAgentsDocs(tables, customOperations, toolName) {
         const pk = (0, utils_1.getPrimaryKeyInfo)(table)[0];
         const scalarFields = (0, utils_1.getScalarFields)(table);
         const editableFields = (0, docs_utils_1.getEditableFields)(table);
+        const defaultFields = (0, table_command_generator_1.getFieldsWithDefaults)(table, registry);
+        const requiredCreateFields = editableFields.filter((f) => !defaultFields.has(f.name));
+        const optionalCreateFields = editableFields.filter((f) => defaultFields.has(f.name));
+        const createFlags = [
+            ...requiredCreateFields.map((f) => `--${f.name} <value>`),
+            ...optionalCreateFields.map((f) => `[--${f.name} <value>]`),
+        ].join(' ');
         lines.push(`### TOOL: ${kebab}`);
         lines.push('');
         lines.push(`CRUD operations for ${table.name} records.`);
@@ -225,19 +254,20 @@ function generateAgentsDocs(tables, customOperations, toolName) {
         lines.push('SUBCOMMANDS:');
         lines.push(`  ${toolName} ${kebab} list                               List all records`);
         lines.push(`  ${toolName} ${kebab} get --${pk.name} <value>              Get one record`);
-        lines.push(`  ${toolName} ${kebab} create ${editableFields.map((f) => `--${f.name} <value>`).join(' ')}`);
+        lines.push(`  ${toolName} ${kebab} create ${createFlags}`);
         lines.push(`  ${toolName} ${kebab} update --${pk.name} <value> ${editableFields.map((f) => `[--${f.name} <value>]`).join(' ')}`);
         lines.push(`  ${toolName} ${kebab} delete --${pk.name} <value>           Delete one record`);
         lines.push('');
         lines.push('INPUT FIELDS:');
         for (const f of scalarFields) {
             const isPk = f.name === pk.name;
-            lines.push(`  ${f.name}: ${f.type.gqlType}${isPk ? ' (primary key)' : ''}`);
+            lines.push(`  ${f.name}: ${(0, docs_utils_1.cleanTypeName)(f.type.gqlType)}${isPk ? ' (primary key)' : ''}`);
         }
         lines.push('');
         lines.push('EDITABLE FIELDS (for create/update):');
         for (const f of editableFields) {
-            lines.push(`  ${f.name}: ${f.type.gqlType}`);
+            const optLabel = defaultFields.has(f.name) ? ' (optional, has backend default)' : '';
+            lines.push(`  ${f.name}: ${(0, docs_utils_1.cleanTypeName)(f.type.gqlType)}${optLabel}`);
         }
         lines.push('');
         lines.push('OUTPUT: JSON');
@@ -251,19 +281,21 @@ function generateAgentsDocs(tables, customOperations, toolName) {
     }
     for (const op of customOperations) {
         const kebab = (0, komoji_1.toKebabCase)(op.name);
+        const flat = (0, docs_utils_1.flattenArgs)(op.args, registry);
         lines.push(`### TOOL: ${kebab}`);
         lines.push('');
         lines.push(op.description || op.name);
         lines.push('');
         lines.push('```');
         lines.push(`TYPE: ${op.kind}`);
-        if (op.args.length > 0) {
-            const flags = op.args.map((a) => `--${a.name} <value>`).join(' ');
+        if (flat.length > 0) {
+            const flags = (0, docs_utils_1.flattenedArgsToFlags)(flat);
             lines.push(`USAGE: ${toolName} ${kebab} ${flags}`);
             lines.push('');
             lines.push('INPUT:');
-            for (const arg of op.args) {
-                lines.push(`  ${arg.name}: ${(0, docs_utils_1.formatArgType)(arg)}`);
+            for (const a of flat) {
+                const reqLabel = a.required ? ' (required)' : '';
+                lines.push(`  ${a.flag}: ${a.type}${reqLabel}`);
             }
         }
         else {
@@ -341,7 +373,7 @@ function generateAgentsDocs(tables, customOperations, toolName) {
         content: lines.join('\n'),
     };
 }
-function getCliMcpTools(tables, customOperations, toolName) {
+function getCliMcpTools(tables, customOperations, toolName, registry) {
     const tools = [];
     tools.push({
         name: `${toolName}_context_create`,
@@ -414,6 +446,10 @@ function getCliMcpTools(tables, customOperations, toolName) {
         const pk = (0, utils_1.getPrimaryKeyInfo)(table)[0];
         const scalarFields = (0, utils_1.getScalarFields)(table);
         const editableFields = (0, docs_utils_1.getEditableFields)(table);
+        const defaultFields = (0, table_command_generator_1.getFieldsWithDefaults)(table, registry);
+        const requiredCreateFieldNames = editableFields
+            .filter((f) => !defaultFields.has(f.name))
+            .map((f) => f.name);
         tools.push({
             name: `${toolName}_${kebab}_list`,
             description: `List all ${table.name} records`,
@@ -436,7 +472,7 @@ function getCliMcpTools(tables, customOperations, toolName) {
         const createProps = {};
         for (const f of editableFields) {
             createProps[f.name] = {
-                type: (0, docs_utils_1.gqlTypeToJsonSchemaType)(f.type.gqlType),
+                type: (0, docs_utils_1.gqlTypeToJsonSchemaType)((0, docs_utils_1.cleanTypeName)(f.type.gqlType)),
                 description: `${table.name} ${f.name}`,
             };
         }
@@ -446,7 +482,7 @@ function getCliMcpTools(tables, customOperations, toolName) {
             inputSchema: {
                 type: 'object',
                 properties: createProps,
-                required: editableFields.map((f) => f.name),
+                ...(requiredCreateFieldNames.length > 0 ? { required: requiredCreateFieldNames } : {}),
             },
         });
         const updateProps = {
@@ -457,7 +493,7 @@ function getCliMcpTools(tables, customOperations, toolName) {
         };
         for (const f of editableFields) {
             updateProps[f.name] = {
-                type: (0, docs_utils_1.gqlTypeToJsonSchemaType)(f.type.gqlType),
+                type: (0, docs_utils_1.gqlTypeToJsonSchemaType)((0, docs_utils_1.cleanTypeName)(f.type.gqlType)),
                 description: `${table.name} ${f.name}`,
             };
         }
@@ -491,7 +527,7 @@ function getCliMcpTools(tables, customOperations, toolName) {
             _meta: {
                 fields: scalarFields.map((f) => ({
                     name: f.name,
-                    type: f.type.gqlType,
+                    type: (0, docs_utils_1.cleanTypeName)(f.type.gqlType),
                     editable: editableFields.some((ef) => ef.name === f.name),
                     primaryKey: f.name === pk.name,
                 })),
@@ -500,17 +536,16 @@ function getCliMcpTools(tables, customOperations, toolName) {
     }
     for (const op of customOperations) {
         const kebab = (0, komoji_1.toKebabCase)(op.name);
+        const flat = (0, docs_utils_1.flattenArgs)(op.args, registry);
         const props = {};
         const required = [];
-        for (const arg of op.args) {
-            const isRequired = arg.type.kind === 'NON_NULL';
-            const baseType = isRequired && arg.type.ofType ? arg.type.ofType : arg.type;
-            props[arg.name] = {
-                type: (0, docs_utils_1.gqlTypeToJsonSchemaType)(baseType.name ?? 'String'),
-                description: arg.description || arg.name,
+        for (const a of flat) {
+            props[a.flag] = {
+                type: (0, docs_utils_1.gqlTypeToJsonSchemaType)(a.type),
+                description: a.description || a.flag,
             };
-            if (isRequired) {
-                required.push(arg.name);
+            if (a.required) {
+                required.push(a.flag);
             }
         }
         tools.push({
@@ -525,7 +560,7 @@ function getCliMcpTools(tables, customOperations, toolName) {
     }
     return tools;
 }
-function generateSkills(tables, customOperations, toolName, targetName) {
+function generateSkills(tables, customOperations, toolName, targetName, registry) {
     const files = [];
     const skillName = `cli-${targetName}`;
     const referenceNames = [];
@@ -588,6 +623,11 @@ function generateSkills(tables, customOperations, toolName, targetName) {
         const kebab = (0, komoji_1.toKebabCase)(singularName);
         const pk = (0, utils_1.getPrimaryKeyInfo)(table)[0];
         const editableFields = (0, docs_utils_1.getEditableFields)(table);
+        const defaultFields = (0, table_command_generator_1.getFieldsWithDefaults)(table, registry);
+        const createFlags = [
+            ...editableFields.filter((f) => !defaultFields.has(f.name)).map((f) => `--${f.name} <value>`),
+            ...editableFields.filter((f) => defaultFields.has(f.name)).map((f) => `[--${f.name} <value>]`),
+        ].join(' ');
         referenceNames.push(kebab);
         files.push({
             fileName: `${skillName}/references/${kebab}.md`,
@@ -597,7 +637,7 @@ function generateSkills(tables, customOperations, toolName, targetName) {
                 usage: [
                     `${toolName} ${kebab} list`,
                     `${toolName} ${kebab} get --${pk.name} <value>`,
-                    `${toolName} ${kebab} create ${editableFields.map((f) => `--${f.name} <value>`).join(' ')}`,
+                    `${toolName} ${kebab} create ${createFlags}`,
                     `${toolName} ${kebab} update --${pk.name} <value> ${editableFields.map((f) => `[--${f.name} <value>]`).join(' ')}`,
                     `${toolName} ${kebab} delete --${pk.name} <value>`,
                 ],
@@ -609,7 +649,7 @@ function generateSkills(tables, customOperations, toolName, targetName) {
                     {
                         description: `Create a ${singularName}`,
                         code: [
-                            `${toolName} ${kebab} create ${editableFields.map((f) => `--${f.name} "value"`).join(' ')}`,
+                            `${toolName} ${kebab} create ${createFlags}`,
                         ],
                     },
                     {
@@ -623,8 +663,9 @@ function generateSkills(tables, customOperations, toolName, targetName) {
     // Custom operation references
     for (const op of customOperations) {
         const kebab = (0, komoji_1.toKebabCase)(op.name);
-        const usage = op.args.length > 0
-            ? `${toolName} ${kebab} ${op.args.map((a) => `--${a.name} <value>`).join(' ')}`
+        const flat = (0, docs_utils_1.flattenArgs)(op.args, registry);
+        const usage = flat.length > 0
+            ? `${toolName} ${kebab} ${(0, docs_utils_1.flattenedArgsToFlags)(flat)}`
             : `${toolName} ${kebab}`;
         referenceNames.push(kebab);
         files.push({
@@ -661,6 +702,9 @@ function generateSkills(tables, customOperations, toolName, targetName) {
                 `${toolName} ${tableKebabs[0] || 'model'} list`,
                 `${toolName} ${tableKebabs[0] || 'model'} get --id <value>`,
                 `${toolName} ${tableKebabs[0] || 'model'} create --<field> <value>`,
+                '',
+                `# Non-interactive mode (skip all prompts, use flags only)`,
+                `${toolName} --no-tty ${tableKebabs[0] || 'model'} list`,
             ],
             examples: [
                 {
@@ -672,13 +716,19 @@ function generateSkills(tables, customOperations, toolName, targetName) {
                         `${toolName} ${tableKebabs[0] || 'model'} list`,
                     ],
                 },
+                {
+                    description: 'Non-interactive mode (for scripts and CI)',
+                    code: [
+                        `${toolName} --no-tty ${tableKebabs[0] || 'model'} create --<field> <value>`,
+                    ],
+                },
             ],
         }, referenceNames),
     });
     return files;
 }
 function generateMultiTargetReadme(input) {
-    const { toolName, builtinNames, targets } = input;
+    const { toolName, builtinNames, targets, registry } = input;
     const lines = [];
     lines.push(...(0, docs_utils_1.getReadmeHeader)(`${toolName} CLI`));
     lines.push('## Setup');
@@ -803,6 +853,7 @@ function generateMultiTargetReadme(input) {
             const pk = (0, utils_1.getPrimaryKeyInfo)(table)[0];
             const scalarFields = (0, utils_1.getScalarFields)(table);
             const editableFields = (0, docs_utils_1.getEditableFields)(table);
+            const defaultFields = (0, table_command_generator_1.getFieldsWithDefaults)(table, registry);
             lines.push(`### \`${tgt.name}:${kebab}\``);
             lines.push('');
             lines.push(`CRUD operations for ${table.name} records.`);
@@ -820,26 +871,38 @@ function generateMultiTargetReadme(input) {
             lines.push('| Field | Type |');
             lines.push('|-------|------|');
             for (const f of scalarFields) {
-                lines.push(`| \`${f.name}\` | ${f.type.gqlType} |`);
+                lines.push(`| \`${f.name}\` | ${(0, docs_utils_1.cleanTypeName)(f.type.gqlType)} |`);
             }
             lines.push('');
-            lines.push(`**Create fields:** ${editableFields.map((f) => `\`${f.name}\``).join(', ')}`);
+            const requiredCreate = editableFields.filter((f) => !defaultFields.has(f.name));
+            const optionalCreate = editableFields.filter((f) => defaultFields.has(f.name));
+            if (requiredCreate.length > 0) {
+                lines.push(`**Required create fields:** ${requiredCreate.map((f) => `\`${f.name}\``).join(', ')}`);
+            }
+            if (optionalCreate.length > 0) {
+                lines.push(`**Optional create fields (backend defaults):** ${optionalCreate.map((f) => `\`${f.name}\``).join(', ')}`);
+            }
+            if (requiredCreate.length === 0 && optionalCreate.length === 0) {
+                lines.push(`**Create fields:** ${editableFields.map((f) => `\`${f.name}\``).join(', ')}`);
+            }
             lines.push('');
         }
         for (const op of tgt.customOperations) {
             const kebab = (0, komoji_1.toKebabCase)(op.name);
+            const flat = (0, docs_utils_1.flattenArgs)(op.args, registry);
             lines.push(`### \`${tgt.name}:${kebab}\``);
             lines.push('');
             lines.push(op.description || op.name);
             lines.push('');
             lines.push(`- **Type:** ${op.kind}`);
-            if (op.args.length > 0) {
+            if (flat.length > 0) {
                 lines.push('- **Arguments:**');
                 lines.push('');
                 lines.push('  | Argument | Type |');
                 lines.push('  |----------|------|');
-                for (const arg of op.args) {
-                    lines.push(`  | \`${arg.name}\` | ${(0, docs_utils_1.formatArgType)(arg)} |`);
+                for (const a of flat) {
+                    const reqLabel = a.required ? ' (required)' : '';
+                    lines.push(`  | \`--${a.flag}\` | ${a.type}${reqLabel} |`);
                 }
             }
             else {
@@ -864,6 +927,18 @@ function generateMultiTargetReadme(input) {
     }
     lines.push('```');
     lines.push('');
+    lines.push('## Non-Interactive Mode');
+    lines.push('');
+    lines.push('Use `--no-tty` to skip all interactive prompts (useful for scripts and CI):');
+    lines.push('');
+    lines.push('```bash');
+    if (targets.length > 0 && targets[0].tables.length > 0) {
+        const tgt = targets[0];
+        const kebab = (0, komoji_1.toKebabCase)((0, utils_1.getTableNames)(tgt.tables[0]).singularName);
+        lines.push(`${toolName} --no-tty ${tgt.name}:${kebab} create --name "Example"`);
+    }
+    lines.push('```');
+    lines.push('');
     lines.push(...(0, docs_utils_1.getReadmeFooter)());
     return {
         fileName: 'README.md',
@@ -871,7 +946,7 @@ function generateMultiTargetReadme(input) {
     };
 }
 function generateMultiTargetAgentsDocs(input) {
-    const { toolName, builtinNames, targets } = input;
+    const { toolName, builtinNames, targets, registry } = input;
     const lines = [];
     lines.push(`# ${toolName} CLI - Agent Reference`);
     lines.push('');
@@ -964,6 +1039,13 @@ function generateMultiTargetAgentsDocs(input) {
             const pk = (0, utils_1.getPrimaryKeyInfo)(table)[0];
             const scalarFields = (0, utils_1.getScalarFields)(table);
             const editableFields = (0, docs_utils_1.getEditableFields)(table);
+            const defaultFields = (0, table_command_generator_1.getFieldsWithDefaults)(table, registry);
+            const requiredCreateFields = editableFields.filter((f) => !defaultFields.has(f.name));
+            const optionalCreateFields = editableFields.filter((f) => defaultFields.has(f.name));
+            const createFlags = [
+                ...requiredCreateFields.map((f) => `--${f.name} <value>`),
+                ...optionalCreateFields.map((f) => `[--${f.name} <value>]`),
+            ].join(' ');
             lines.push(`### TOOL: ${tgt.name}:${kebab}`);
             lines.push('');
             lines.push(`CRUD operations for ${table.name} records (${tgt.name} target).`);
@@ -972,19 +1054,20 @@ function generateMultiTargetAgentsDocs(input) {
             lines.push('SUBCOMMANDS:');
             lines.push(`  ${toolName} ${tgt.name}:${kebab} list                               List all records`);
             lines.push(`  ${toolName} ${tgt.name}:${kebab} get --${pk.name} <value>              Get one record`);
-            lines.push(`  ${toolName} ${tgt.name}:${kebab} create ${editableFields.map((f) => `--${f.name} <value>`).join(' ')}`);
+            lines.push(`  ${toolName} ${tgt.name}:${kebab} create ${createFlags}`);
             lines.push(`  ${toolName} ${tgt.name}:${kebab} update --${pk.name} <value> ${editableFields.map((f) => `[--${f.name} <value>]`).join(' ')}`);
             lines.push(`  ${toolName} ${tgt.name}:${kebab} delete --${pk.name} <value>           Delete one record`);
             lines.push('');
             lines.push('INPUT FIELDS:');
             for (const f of scalarFields) {
                 const isPk = f.name === pk.name;
-                lines.push(`  ${f.name}: ${f.type.gqlType}${isPk ? ' (primary key)' : ''}`);
+                lines.push(`  ${f.name}: ${(0, docs_utils_1.cleanTypeName)(f.type.gqlType)}${isPk ? ' (primary key)' : ''}`);
             }
             lines.push('');
             lines.push('EDITABLE FIELDS (for create/update):');
             for (const f of editableFields) {
-                lines.push(`  ${f.name}: ${f.type.gqlType}`);
+                const optLabel = defaultFields.has(f.name) ? ' (optional, has backend default)' : '';
+                lines.push(`  ${f.name}: ${(0, docs_utils_1.cleanTypeName)(f.type.gqlType)}${optLabel}`);
             }
             lines.push('');
             lines.push('OUTPUT: JSON');
@@ -998,19 +1081,21 @@ function generateMultiTargetAgentsDocs(input) {
         }
         for (const op of tgt.customOperations) {
             const kebab = (0, komoji_1.toKebabCase)(op.name);
+            const flat = (0, docs_utils_1.flattenArgs)(op.args, registry);
             lines.push(`### TOOL: ${tgt.name}:${kebab}`);
             lines.push('');
             lines.push(op.description || op.name);
             lines.push('');
             lines.push('```');
             lines.push(`TYPE: ${op.kind}`);
-            if (op.args.length > 0) {
-                const flags = op.args.map((a) => `--${a.name} <value>`).join(' ');
+            if (flat.length > 0) {
+                const flags = (0, docs_utils_1.flattenedArgsToFlags)(flat);
                 lines.push(`USAGE: ${toolName} ${tgt.name}:${kebab} ${flags}`);
                 lines.push('');
                 lines.push('INPUT:');
-                for (const arg of op.args) {
-                    lines.push(`  ${arg.name}: ${(0, docs_utils_1.formatArgType)(arg)}`);
+                for (const a of flat) {
+                    const reqLabel = a.required ? ' (required)' : '';
+                    lines.push(`  ${a.flag}: ${a.type}${reqLabel}`);
                 }
             }
             else {
@@ -1099,7 +1184,7 @@ function generateMultiTargetAgentsDocs(input) {
     };
 }
 function getMultiTargetCliMcpTools(input) {
-    const { toolName, builtinNames, targets } = input;
+    const { toolName, builtinNames, targets, registry } = input;
     const tools = [];
     const contextEndpointProps = {
         name: { type: 'string', description: 'Context name' },
@@ -1179,6 +1264,10 @@ function getMultiTargetCliMcpTools(input) {
             const pk = (0, utils_1.getPrimaryKeyInfo)(table)[0];
             const scalarFields = (0, utils_1.getScalarFields)(table);
             const editableFields = (0, docs_utils_1.getEditableFields)(table);
+            const defaultFields = (0, table_command_generator_1.getFieldsWithDefaults)(table, registry);
+            const requiredCreateFieldNames = editableFields
+                .filter((f) => !defaultFields.has(f.name))
+                .map((f) => f.name);
             const prefix = `${toolName}_${tgt.name}_${kebab}`;
             tools.push({
                 name: `${prefix}_list`,
@@ -1202,7 +1291,7 @@ function getMultiTargetCliMcpTools(input) {
             const createProps = {};
             for (const f of editableFields) {
                 createProps[f.name] = {
-                    type: (0, docs_utils_1.gqlTypeToJsonSchemaType)(f.type.gqlType),
+                    type: (0, docs_utils_1.gqlTypeToJsonSchemaType)((0, docs_utils_1.cleanTypeName)(f.type.gqlType)),
                     description: `${table.name} ${f.name}`,
                 };
             }
@@ -1212,7 +1301,7 @@ function getMultiTargetCliMcpTools(input) {
                 inputSchema: {
                     type: 'object',
                     properties: createProps,
-                    required: editableFields.map((f) => f.name),
+                    ...(requiredCreateFieldNames.length > 0 ? { required: requiredCreateFieldNames } : {}),
                 },
             });
             const updateProps = {
@@ -1223,7 +1312,7 @@ function getMultiTargetCliMcpTools(input) {
             };
             for (const f of editableFields) {
                 updateProps[f.name] = {
-                    type: (0, docs_utils_1.gqlTypeToJsonSchemaType)(f.type.gqlType),
+                    type: (0, docs_utils_1.gqlTypeToJsonSchemaType)((0, docs_utils_1.cleanTypeName)(f.type.gqlType)),
                     description: `${table.name} ${f.name}`,
                 };
             }
@@ -1257,7 +1346,7 @@ function getMultiTargetCliMcpTools(input) {
                 _meta: {
                     fields: scalarFields.map((f) => ({
                         name: f.name,
-                        type: f.type.gqlType,
+                        type: (0, docs_utils_1.cleanTypeName)(f.type.gqlType),
                         editable: editableFields.some((ef) => ef.name === f.name),
                         primaryKey: f.name === pk.name,
                     })),
@@ -1266,17 +1355,16 @@ function getMultiTargetCliMcpTools(input) {
         }
         for (const op of tgt.customOperations) {
             const kebab = (0, komoji_1.toKebabCase)(op.name);
+            const flat = (0, docs_utils_1.flattenArgs)(op.args, registry);
             const props = {};
             const required = [];
-            for (const arg of op.args) {
-                const isRequired = arg.type.kind === 'NON_NULL';
-                const baseType = isRequired && arg.type.ofType ? arg.type.ofType : arg.type;
-                props[arg.name] = {
-                    type: (0, docs_utils_1.gqlTypeToJsonSchemaType)(baseType.name ?? 'String'),
-                    description: arg.description || arg.name,
+            for (const a of flat) {
+                props[a.flag] = {
+                    type: (0, docs_utils_1.gqlTypeToJsonSchemaType)(a.type),
+                    description: a.description || a.flag,
                 };
-                if (isRequired) {
-                    required.push(arg.name);
+                if (a.required) {
+                    required.push(a.flag);
                 }
             }
             if (tgt.isAuthTarget && op.kind === 'mutation') {
@@ -1299,7 +1387,7 @@ function getMultiTargetCliMcpTools(input) {
     return tools;
 }
 function generateMultiTargetSkills(input) {
-    const { toolName, builtinNames, targets } = input;
+    const { toolName, builtinNames, targets, registry } = input;
     const files = [];
     // Generate one skill per target, plus a shared cli-common skill for context/auth
     const commonSkillName = 'cli-common';
@@ -1399,6 +1487,11 @@ function generateMultiTargetSkills(input) {
             const kebab = (0, komoji_1.toKebabCase)(singularName);
             const pk = (0, utils_1.getPrimaryKeyInfo)(table)[0];
             const editableFields = (0, docs_utils_1.getEditableFields)(table);
+            const defaultFields = (0, table_command_generator_1.getFieldsWithDefaults)(table, registry);
+            const createFlags = [
+                ...editableFields.filter((f) => !defaultFields.has(f.name)).map((f) => `--${f.name} <value>`),
+                ...editableFields.filter((f) => defaultFields.has(f.name)).map((f) => `[--${f.name} <value>]`),
+            ].join(' ');
             const cmd = `${tgt.name}:${kebab}`;
             tgtReferenceNames.push(kebab);
             files.push({
@@ -1409,7 +1502,7 @@ function generateMultiTargetSkills(input) {
                     usage: [
                         `${toolName} ${cmd} list`,
                         `${toolName} ${cmd} get --${pk.name} <value>`,
-                        `${toolName} ${cmd} create ${editableFields.map((f) => `--${f.name} <value>`).join(' ')}`,
+                        `${toolName} ${cmd} create ${createFlags}`,
                         `${toolName} ${cmd} update --${pk.name} <value> ${editableFields.map((f) => `[--${f.name} <value>]`).join(' ')}`,
                         `${toolName} ${cmd} delete --${pk.name} <value>`,
                     ],
@@ -1421,7 +1514,7 @@ function generateMultiTargetSkills(input) {
                         {
                             description: `Create a ${singularName}`,
                             code: [
-                                `${toolName} ${cmd} create ${editableFields.map((f) => `--${f.name} "value"`).join(' ')}`,
+                                `${toolName} ${cmd} create ${createFlags}`,
                             ],
                         },
                     ],
@@ -1431,8 +1524,9 @@ function generateMultiTargetSkills(input) {
         for (const op of tgt.customOperations) {
             const kebab = (0, komoji_1.toKebabCase)(op.name);
             const cmd = `${tgt.name}:${kebab}`;
-            const baseUsage = op.args.length > 0
-                ? `${toolName} ${cmd} ${op.args.map((a) => `--${a.name} <value>`).join(' ')}`
+            const flat = (0, docs_utils_1.flattenArgs)(op.args, registry);
+            const baseUsage = flat.length > 0
+                ? `${toolName} ${cmd} ${(0, docs_utils_1.flattenedArgsToFlags)(flat)}`
                 : `${toolName} ${cmd}`;
             const usageLines = [baseUsage];
             if (tgt.isAuthTarget && op.kind === 'mutation') {
@@ -1468,12 +1562,21 @@ function generateMultiTargetSkills(input) {
                     `${toolName} ${tgt.name}:${firstKebab} list`,
                     `${toolName} ${tgt.name}:${firstKebab} get --id <value>`,
                     `${toolName} ${tgt.name}:${firstKebab} create --<field> <value>`,
+                    '',
+                    `# Non-interactive mode (skip all prompts, use flags only)`,
+                    `${toolName} --no-tty ${tgt.name}:${firstKebab} list`,
                 ],
                 examples: [
                     {
                         description: `Query ${tgt.name} records`,
                         code: [`${toolName} ${tgt.name}:${firstKebab} list`],
                     },
+                    {
+                        description: 'Non-interactive mode (for scripts and CI)',
+                        code: [
+                            `${toolName} --no-tty ${tgt.name}:${firstKebab} create --<field> <value>`,
+                        ],
+                    },
                 ],
             }, tgtReferenceNames),
         });

package/core/codegen/cli/table-command-generator.d.ts

@@ -1,5 +1,20 @@
 import type { CleanTable, TypeRegistry } from '../../../types/schema';
 import type { GeneratedFile } from './executor-generator';
+/**
+ * Get the set of field names that have defaults in the create input type.
+ * Looks up the CreateXInput -> inner input type (e.g. DatabaseInput) in the
+ * TypeRegistry and checks each field's defaultValue from introspection.
+ */
+/**
+ * Resolve the inner input type from a CreateXInput or UpdateXInput type.
+ * The CreateXInput has an inner field (e.g. "database" of type DatabaseInput)
+ * that contains the actual field definitions.
+ */
+export declare function resolveInnerInputType(inputTypeName: string, typeRegistry: TypeRegistry): {
+    name: string;
+    fields: Set<string>;
+} | null;
+export declare function getFieldsWithDefaults(table: CleanTable, typeRegistry?: TypeRegistry): Set<string>;
 export interface TableCommandOptions {
     targetName?: string;
     executorImportPath?: string;