@constructive-io/graphql-codegen 4.8.1 → 4.12.2

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

@@ -1,8 +1,9 @@
 import { toKebabCase } from 'komoji';
-import { formatArgType, getEditableFields, getReadmeHeader, getReadmeFooter, gqlTypeToJsonSchemaType, buildSkillFile, buildSkillReference, } from '../docs-utils';
+import { flattenArgs, flattenedArgsToFlags, cleanTypeName, getEditableFields, getReadmeHeader, getReadmeFooter, gqlTypeToJsonSchemaType, buildSkillFile, buildSkillReference, } from '../docs-utils';
 import { getScalarFields, getTableNames, getPrimaryKeyInfo, } from '../utils';
+import { getFieldsWithDefaults } from './table-command-generator';
 export { resolveDocsConfig } from '../docs-utils';
-export function generateReadme(tables, customOperations, toolName) {
+export function generateReadme(tables, customOperations, toolName, registry) {
     const lines = [];
     lines.push(...getReadmeHeader(`${toolName} CLI`));
     lines.push('## Setup');
@@ -86,10 +87,21 @@ export 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}\` | ${cleanTypeName(f.type.gqlType)} |`);
             }
             lines.push('');
-            lines.push(`**Create fields:** ${editableFields.map((f) => `\`${f.name}\``).join(', ')}`);
+            const defaultFields = 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('');
         }
     }
@@ -98,18 +110,20 @@ export function generateReadme(tables, customOperations, toolName) {
         lines.push('');
         for (const op of customOperations) {
             const kebab = toKebabCase(op.name);
+            const flat = 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}\` | ${formatArgType(arg)} |`);
+                for (const a of flat) {
+                    const reqLabel = a.required ? ' (required)' : '';
+                    lines.push(`  | \`--${a.flag}\` | ${a.type}${reqLabel} |`);
                 }
             }
             else {
@@ -127,13 +141,21 @@ export 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(...getReadmeFooter());
     return {
         fileName: 'README.md',
         content: lines.join('\n'),
     };
 }
-export function generateAgentsDocs(tables, customOperations, toolName) {
+export function generateAgentsDocs(tables, customOperations, toolName, registry) {
     const lines = [];
     lines.push(`# ${toolName} CLI - Agent Reference`);
     lines.push('');
@@ -205,6 +227,13 @@ export function generateAgentsDocs(tables, customOperations, toolName) {
         const pk = getPrimaryKeyInfo(table)[0];
         const scalarFields = getScalarFields(table);
         const editableFields = getEditableFields(table);
+        const defaultFields = 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.`);
@@ -213,19 +242,20 @@ export 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}: ${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}: ${cleanTypeName(f.type.gqlType)}${optLabel}`);
         }
         lines.push('');
         lines.push('OUTPUT: JSON');
@@ -239,19 +269,21 @@ export function generateAgentsDocs(tables, customOperations, toolName) {
     }
     for (const op of customOperations) {
         const kebab = toKebabCase(op.name);
+        const flat = 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 = flattenedArgsToFlags(flat);
             lines.push(`USAGE: ${toolName} ${kebab} ${flags}`);
             lines.push('');
             lines.push('INPUT:');
-            for (const arg of op.args) {
-                lines.push(`  ${arg.name}: ${formatArgType(arg)}`);
+            for (const a of flat) {
+                const reqLabel = a.required ? ' (required)' : '';
+                lines.push(`  ${a.flag}: ${a.type}${reqLabel}`);
             }
         }
         else {
@@ -329,7 +361,7 @@ export function generateAgentsDocs(tables, customOperations, toolName) {
         content: lines.join('\n'),
     };
 }
-export function getCliMcpTools(tables, customOperations, toolName) {
+export function getCliMcpTools(tables, customOperations, toolName, registry) {
     const tools = [];
     tools.push({
         name: `${toolName}_context_create`,
@@ -402,6 +434,10 @@ export function getCliMcpTools(tables, customOperations, toolName) {
         const pk = getPrimaryKeyInfo(table)[0];
         const scalarFields = getScalarFields(table);
         const editableFields = getEditableFields(table);
+        const defaultFields = 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`,
@@ -424,7 +460,7 @@ export function getCliMcpTools(tables, customOperations, toolName) {
         const createProps = {};
         for (const f of editableFields) {
             createProps[f.name] = {
-                type: gqlTypeToJsonSchemaType(f.type.gqlType),
+                type: gqlTypeToJsonSchemaType(cleanTypeName(f.type.gqlType)),
                 description: `${table.name} ${f.name}`,
             };
         }
@@ -434,7 +470,7 @@ export function getCliMcpTools(tables, customOperations, toolName) {
             inputSchema: {
                 type: 'object',
                 properties: createProps,
-                required: editableFields.map((f) => f.name),
+                ...(requiredCreateFieldNames.length > 0 ? { required: requiredCreateFieldNames } : {}),
             },
         });
         const updateProps = {
@@ -445,7 +481,7 @@ export function getCliMcpTools(tables, customOperations, toolName) {
         };
         for (const f of editableFields) {
             updateProps[f.name] = {
-                type: gqlTypeToJsonSchemaType(f.type.gqlType),
+                type: gqlTypeToJsonSchemaType(cleanTypeName(f.type.gqlType)),
                 description: `${table.name} ${f.name}`,
             };
         }
@@ -479,7 +515,7 @@ export function getCliMcpTools(tables, customOperations, toolName) {
             _meta: {
                 fields: scalarFields.map((f) => ({
                     name: f.name,
-                    type: f.type.gqlType,
+                    type: cleanTypeName(f.type.gqlType),
                     editable: editableFields.some((ef) => ef.name === f.name),
                     primaryKey: f.name === pk.name,
                 })),
@@ -488,17 +524,16 @@ export function getCliMcpTools(tables, customOperations, toolName) {
     }
     for (const op of customOperations) {
         const kebab = toKebabCase(op.name);
+        const flat = 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: gqlTypeToJsonSchemaType(baseType.name ?? 'String'),
-                description: arg.description || arg.name,
+        for (const a of flat) {
+            props[a.flag] = {
+                type: gqlTypeToJsonSchemaType(a.type),
+                description: a.description || a.flag,
             };
-            if (isRequired) {
-                required.push(arg.name);
+            if (a.required) {
+                required.push(a.flag);
             }
         }
         tools.push({
@@ -513,7 +548,7 @@ export function getCliMcpTools(tables, customOperations, toolName) {
     }
     return tools;
 }
-export function generateSkills(tables, customOperations, toolName, targetName) {
+export function generateSkills(tables, customOperations, toolName, targetName, registry) {
     const files = [];
     const skillName = `cli-${targetName}`;
     const referenceNames = [];
@@ -576,6 +611,11 @@ export function generateSkills(tables, customOperations, toolName, targetName) {
         const kebab = toKebabCase(singularName);
         const pk = getPrimaryKeyInfo(table)[0];
         const editableFields = getEditableFields(table);
+        const defaultFields = 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`,
@@ -585,7 +625,7 @@ export 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>`,
                 ],
@@ -597,7 +637,7 @@ export 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}`,
                         ],
                     },
                     {
@@ -611,8 +651,9 @@ export function generateSkills(tables, customOperations, toolName, targetName) {
     // Custom operation references
     for (const op of customOperations) {
         const kebab = toKebabCase(op.name);
-        const usage = op.args.length > 0
-            ? `${toolName} ${kebab} ${op.args.map((a) => `--${a.name} <value>`).join(' ')}`
+        const flat = flattenArgs(op.args, registry);
+        const usage = flat.length > 0
+            ? `${toolName} ${kebab} ${flattenedArgsToFlags(flat)}`
             : `${toolName} ${kebab}`;
         referenceNames.push(kebab);
         files.push({
@@ -649,6 +690,9 @@ export 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: [
                 {
@@ -660,13 +704,19 @@ export 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;
 }
 export function generateMultiTargetReadme(input) {
-    const { toolName, builtinNames, targets } = input;
+    const { toolName, builtinNames, targets, registry } = input;
     const lines = [];
     lines.push(...getReadmeHeader(`${toolName} CLI`));
     lines.push('## Setup');
@@ -791,6 +841,7 @@ export function generateMultiTargetReadme(input) {
             const pk = getPrimaryKeyInfo(table)[0];
             const scalarFields = getScalarFields(table);
             const editableFields = getEditableFields(table);
+            const defaultFields = getFieldsWithDefaults(table, registry);
             lines.push(`### \`${tgt.name}:${kebab}\``);
             lines.push('');
             lines.push(`CRUD operations for ${table.name} records.`);
@@ -808,26 +859,38 @@ export 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}\` | ${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 = toKebabCase(op.name);
+            const flat = 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}\` | ${formatArgType(arg)} |`);
+                for (const a of flat) {
+                    const reqLabel = a.required ? ' (required)' : '';
+                    lines.push(`  | \`--${a.flag}\` | ${a.type}${reqLabel} |`);
                 }
             }
             else {
@@ -852,6 +915,18 @@ export 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 = toKebabCase(getTableNames(tgt.tables[0]).singularName);
+        lines.push(`${toolName} --no-tty ${tgt.name}:${kebab} create --name "Example"`);
+    }
+    lines.push('```');
+    lines.push('');
     lines.push(...getReadmeFooter());
     return {
         fileName: 'README.md',
@@ -859,7 +934,7 @@ export function generateMultiTargetReadme(input) {
     };
 }
 export function generateMultiTargetAgentsDocs(input) {
-    const { toolName, builtinNames, targets } = input;
+    const { toolName, builtinNames, targets, registry } = input;
     const lines = [];
     lines.push(`# ${toolName} CLI - Agent Reference`);
     lines.push('');
@@ -952,6 +1027,13 @@ export function generateMultiTargetAgentsDocs(input) {
             const pk = getPrimaryKeyInfo(table)[0];
             const scalarFields = getScalarFields(table);
             const editableFields = getEditableFields(table);
+            const defaultFields = 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).`);
@@ -960,19 +1042,20 @@ export 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}: ${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}: ${cleanTypeName(f.type.gqlType)}${optLabel}`);
             }
             lines.push('');
             lines.push('OUTPUT: JSON');
@@ -986,19 +1069,21 @@ export function generateMultiTargetAgentsDocs(input) {
         }
         for (const op of tgt.customOperations) {
             const kebab = toKebabCase(op.name);
+            const flat = 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 = 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}: ${formatArgType(arg)}`);
+                for (const a of flat) {
+                    const reqLabel = a.required ? ' (required)' : '';
+                    lines.push(`  ${a.flag}: ${a.type}${reqLabel}`);
                 }
             }
             else {
@@ -1087,7 +1172,7 @@ export function generateMultiTargetAgentsDocs(input) {
     };
 }
 export function getMultiTargetCliMcpTools(input) {
-    const { toolName, builtinNames, targets } = input;
+    const { toolName, builtinNames, targets, registry } = input;
     const tools = [];
     const contextEndpointProps = {
         name: { type: 'string', description: 'Context name' },
@@ -1167,6 +1252,10 @@ export function getMultiTargetCliMcpTools(input) {
             const pk = getPrimaryKeyInfo(table)[0];
             const scalarFields = getScalarFields(table);
             const editableFields = getEditableFields(table);
+            const defaultFields = 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`,
@@ -1190,7 +1279,7 @@ export function getMultiTargetCliMcpTools(input) {
             const createProps = {};
             for (const f of editableFields) {
                 createProps[f.name] = {
-                    type: gqlTypeToJsonSchemaType(f.type.gqlType),
+                    type: gqlTypeToJsonSchemaType(cleanTypeName(f.type.gqlType)),
                     description: `${table.name} ${f.name}`,
                 };
             }
@@ -1200,7 +1289,7 @@ export function getMultiTargetCliMcpTools(input) {
                 inputSchema: {
                     type: 'object',
                     properties: createProps,
-                    required: editableFields.map((f) => f.name),
+                    ...(requiredCreateFieldNames.length > 0 ? { required: requiredCreateFieldNames } : {}),
                 },
             });
             const updateProps = {
@@ -1211,7 +1300,7 @@ export function getMultiTargetCliMcpTools(input) {
             };
             for (const f of editableFields) {
                 updateProps[f.name] = {
-                    type: gqlTypeToJsonSchemaType(f.type.gqlType),
+                    type: gqlTypeToJsonSchemaType(cleanTypeName(f.type.gqlType)),
                     description: `${table.name} ${f.name}`,
                 };
             }
@@ -1245,7 +1334,7 @@ export function getMultiTargetCliMcpTools(input) {
                 _meta: {
                     fields: scalarFields.map((f) => ({
                         name: f.name,
-                        type: f.type.gqlType,
+                        type: cleanTypeName(f.type.gqlType),
                         editable: editableFields.some((ef) => ef.name === f.name),
                         primaryKey: f.name === pk.name,
                     })),
@@ -1254,17 +1343,16 @@ export function getMultiTargetCliMcpTools(input) {
         }
         for (const op of tgt.customOperations) {
             const kebab = toKebabCase(op.name);
+            const flat = 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: gqlTypeToJsonSchemaType(baseType.name ?? 'String'),
-                    description: arg.description || arg.name,
+            for (const a of flat) {
+                props[a.flag] = {
+                    type: 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') {
@@ -1287,7 +1375,7 @@ export function getMultiTargetCliMcpTools(input) {
     return tools;
 }
 export 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';
@@ -1387,6 +1475,11 @@ export function generateMultiTargetSkills(input) {
             const kebab = toKebabCase(singularName);
             const pk = getPrimaryKeyInfo(table)[0];
             const editableFields = getEditableFields(table);
+            const defaultFields = 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({
@@ -1397,7 +1490,7 @@ export 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>`,
                     ],
@@ -1409,7 +1502,7 @@ export function generateMultiTargetSkills(input) {
                         {
                             description: `Create a ${singularName}`,
                             code: [
-                                `${toolName} ${cmd} create ${editableFields.map((f) => `--${f.name} "value"`).join(' ')}`,
+                                `${toolName} ${cmd} create ${createFlags}`,
                             ],
                         },
                     ],
@@ -1419,8 +1512,9 @@ export function generateMultiTargetSkills(input) {
         for (const op of tgt.customOperations) {
             const kebab = 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 = flattenArgs(op.args, registry);
+            const baseUsage = flat.length > 0
+                ? `${toolName} ${cmd} ${flattenedArgsToFlags(flat)}`
                 : `${toolName} ${cmd}`;
             const usageLines = [baseUsage];
             if (tgt.isAuthTarget && op.kind === 'mutation') {
@@ -1456,12 +1550,21 @@ export 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/esm/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;