@superdesign/cli 0.1.8 → 0.1.10

package/README.md

@@ -39,9 +39,9 @@ Use these to discover style direction, references, and brand context:
 - **Search prompt library** (style/components/pages)
 
   ```bash
-  superdesign search-prompts --keyword "<keyword>" --json
+  superdesign search-prompts --query "<query>" --json
   superdesign search-prompts --tags "style" --json
-  superdesign search-prompts --tags "style" --keyword "<style keyword>" --json
+  superdesign search-prompts --tags "style" --query "<style query>" --json
   ```
 
 - **Get full prompt details**
@@ -59,7 +59,7 @@ Use these to discover style direction, references, and brand context:
 
 Use design agent to generate high quality design drafts:
 
-- Create project (supports prompt / prompt file / HTML)
+- Create project (auto-detects `.superdesign/design-system.md` as prompt)
 - Create design draft
 - Iterate design draft (replace / branch)
 - Plan flow pages → execute flow pages
@@ -75,7 +75,7 @@ Use design agent to generate high quality design drafts:
 4. Ask user whether ready to design in superdesign OR implement UI directly
 5. If yes to superdesign
    5.1 Create/update a pixel perfect html replica of current UI of page that we will design on top of in `.superdesign/replica_html_template/<name>.html` (html should only contain & reflect how UI look now, the actual design should be handled by superdesign agent)
-   5.2 Create project with this replica html + design system guide
+   5.2 Create project with this replica html
    5.3 Start desigining by iterating & branching design draft based on designDraft ID returned from project
 
 ## Always-on rules
@@ -192,11 +192,11 @@ Then in the iterate command:
    ```bash
    superdesign create-project \
      --title "<feature>" \
-     --html-file .superdesign/replica_html_template/<file>.html \
-     --set-project-prompt-file .superdesign/design-system.md \
+     --template .superdesign/replica_html_template/<file>.html \
      --json
    ```
    → Note: `draftId` in response is the baseline draft
+   → Auto-detects `.superdesign/design-system.md` as project prompt
    3.4 Branch designs from baseline (use `draftId` from step 3.3)
    ```bash
    superdesign iterate-design-draft \
@@ -225,7 +225,7 @@ superdesign execute-flow-pages \
 #### Get HTML reference from a draft
 
 ```bash
-superdesign get-design --draft-id <draftId> --output ./design.html
+superdesign get-design --draft-id <draftId>
 ```
 
 ---
@@ -234,16 +234,14 @@ superdesign get-design --draft-id <draftId> --output ./design.html
 
 ```bash
 # Inspirations
-superdesign search-prompts --keyword "<keyword>" --json
+superdesign search-prompts --query "<query>" --json
 superdesign search-prompts --tags "style" --json
 superdesign get-prompts --slugs "<slug1,slug2>" --json
 superdesign extract-brand-guide --url https://example.com --json
 
-# Canvas - Create project
-# Options: -s/--set-project-prompt (inline), --set-project-prompt-file (from file)
-superdesign create-project --title "X" --set-project-prompt "..." --json
-superdesign create-project --title "X" --set-project-prompt-file .superdesign/design-system.md --json
-superdesign create-project --title "X" --html-file ./index.html --set-project-prompt-file .superdesign/design-system.md --json
+# Canvas - Create project (auto-detects .superdesign/design-system.md as prompt)
+superdesign create-project --title "X" --json
+superdesign create-project --title "X" --template ./index.html --json
 
 # Iterate: replace mode (single variation, updates in place)
 superdesign iterate-design-draft --draft-id <id> -p "..." --mode replace --json

package/dist/config/constants.d.ts

@@ -12,7 +12,7 @@ export declare const POLL_TIMEOUT_MS: number;
 export declare const AUTH_POLL_INTERVAL_MS = 2000;
 export declare const AUTH_POLL_TIMEOUT_MS: number;
 /** CLI version - should match package.json */
-export declare const CLI_VERSION = "0.1.8";
+export declare const CLI_VERSION = "0.1.9";
 /** PostHog analytics configuration */
 export declare const POSTHOG_KEY: string;
 export declare const POSTHOG_HOST: string;

package/dist/index.cjs

@@ -316,7 +316,7 @@ var __webpack_exports__ = {};
         try {
             startSpinner('Creating auth session...');
             const session = await createSession({
-                cliVersion: "0.1.8",
+                cliVersion: "0.1.9",
                 os: `${external_os_namespaceObject.platform()} ${external_os_namespaceObject.release()}`,
                 hostname: external_os_namespaceObject.hostname()
             });
@@ -724,23 +724,24 @@ superdesign --help
             process.exit(EXIT_CODES.VALIDATION_ERROR);
         }
     }
-    function readFileContent(filePath, inlineContent, fileType) {
-        if (filePath) {
-            if (!(0, external_fs_namespaceObject.existsSync)(filePath)) {
-                output_error(`${fileType} file not found: ${filePath}`);
-                process.exit(EXIT_CODES.VALIDATION_ERROR);
-            }
-            return (0, external_fs_namespaceObject.readFileSync)(filePath, 'utf-8');
+    function readFileIfExists(filePath) {
+        if ((0, external_fs_namespaceObject.existsSync)(filePath)) return (0, external_fs_namespaceObject.readFileSync)(filePath, 'utf-8');
+    }
+    function readFileOrError(filePath, fileType) {
+        if (!(0, external_fs_namespaceObject.existsSync)(filePath)) {
+            output_error(`${fileType} file not found: ${filePath}`);
+            process.exit(EXIT_CODES.VALIDATION_ERROR);
         }
-        return inlineContent;
+        return (0, external_fs_namespaceObject.readFileSync)(filePath, 'utf-8');
     }
     function createCreateProjectCommand() {
-        const command = new external_commander_namespaceObject.Command('create-project').description('Create a new SuperDesign project').requiredOption('--title <title>', 'Project title').option('--html <html>', 'Initial HTML content for first draft').option('--html-file <path>', 'Path to HTML file for first draft').option('-s, --set-project-prompt <prompt>', 'System prompt for the AI agent').option('--set-project-prompt-file <path>', 'Path to markdown file containing system prompt').option('--device <mode>', 'Device mode for draft (mobile, tablet, desktop)', 'desktop').option('--json', 'Output in JSON format').option('--no-open', 'Do not open project in browser after creation').action(async (options)=>{
+        const command = new external_commander_namespaceObject.Command('create-project').description('Create a new SuperDesign project').requiredOption('--title <title>', 'Project title').option('--template <path>', 'Path to HTML template file for first draft').option('--device <mode>', 'Device mode for html template (mobile, tablet, desktop)', 'desktop').option('--json', 'Output in JSON format').action(async (options)=>{
             if (options.json) setJsonMode(true);
             job_runner_requireAuth(manager_isAuthenticated);
             validateDeviceMode(options.device);
-            const htmlContent = readFileContent(options.htmlFile, options.html, 'HTML');
-            const promptContent = readFileContent(options.setProjectPromptFile, options.setProjectPrompt, 'Prompt');
+            const htmlContent = options.template ? readFileOrError(options.template, 'Template') : void 0;
+            const designSystemPath = '.superdesign/design-system.md';
+            const promptContent = readFileIfExists(designSystemPath);
             startSpinner('Creating project...');
             try {
                 const project = await createProject({
@@ -750,10 +751,8 @@ superdesign --help
                     deviceMode: options.device
                 });
                 succeedSpinner('Project created successfully!');
-                if (options.open) {
-                    const urlWithLive = `${project.projectUrl}?live=1`;
-                    await openBrowser(urlWithLive);
-                }
+                const urlWithLive = `${project.projectUrl}?live=1`;
+                await openBrowser(urlWithLive);
                 if (isJsonMode()) output({
                     projectId: project.projectId,
                     title: project.title,
@@ -801,7 +800,7 @@ superdesign --help
         return response.data;
     }
     function createCreateDesignDraftCommand() {
-        const command = new external_commander_namespaceObject.Command('create-design-draft').description('Create a design draft using AI generation').requiredOption('--project-id <id>', 'Project ID').requiredOption('--title <title>', 'Draft title').requiredOption('-p, --prompt <prompt>', 'Design prompt for AI generation').option('--device <mode>', 'Device mode (mobile, tablet, desktop)', 'desktop').option('--json', 'Output in JSON format').action(async (options)=>{
+        const command = new external_commander_namespaceObject.Command('create-design-draft').description('Create a design draft from scratch without any reference, Default dont use this, use iterate-design-draft instead').requiredOption('--project-id <id>', 'Project ID').requiredOption('--title <title>', 'Draft title').requiredOption('-p, --prompt <prompt>', 'Design prompt for AI generation').option('--device <mode>', 'Device mode (mobile, tablet, desktop)', 'desktop').option('--json', 'Output in JSON format').action(async (options)=>{
             if (options.json) setJsonMode(true);
             job_runner_requireAuth(manager_isAuthenticated);
             validateDeviceMode(options.device);
@@ -876,7 +875,17 @@ superdesign --help
         };
     }
     function createIterateDesignDraftCommand() {
-        const command = new external_commander_namespaceObject.Command('iterate-design-draft').description('Iterate on an existing draft using AI').requiredOption('--draft-id <id>', 'Draft ID to iterate on').requiredOption('-p, --prompt <prompt...>', 'Iteration prompt(s). Use multiple -p for specific prompts per variation.').requiredOption('--mode <mode>', 'Iteration mode (replace or branch)').option('--count <count>', 'Number of variations (1-4). Only used when single prompt provided.').option('--json', 'Output in JSON format').action(async (options)=>{
+        const command = new external_commander_namespaceObject.Command('iterate-design-draft').description(`Generate design based on existing draft or template, the main design exploration tool
+
+Usage Examples:
+  # Iterate: replace mode (single variation, updates in place)
+  superdesign iterate-design-draft --draft-id <id> -p "..." --mode replace --json
+
+  # Iterate: Explore multiple versions & variations (each prompt = one variation, prompt should be just directional, do not specify color, style, let superdesign design expert fill in details, you just give direction)
+  superdesign iterate-design-draft --draft-id <id> -p "dark theme" -p "minimal" -p "bold" --mode branch --json
+
+  # Iterate: Auto explore (only give exploration direction, and let Superdesign fill in details, e.g. explore different styles; Default do NOT use auto explore mode)
+  superdesign iterate-design-draft --draft-id <id> -p "..." --mode branch --count 3 --json`).requiredOption('--draft-id <id>', 'Draft ID to iterate on').requiredOption('-p, --prompt <prompt...>', 'Iteration prompt(s). Use multiple -p for specific prompts per variation.').requiredOption('--mode <mode>', 'Iteration mode (replace or branch)').option('--count <count>', 'Number of variations (1-4). Only used when single prompt provided.').option('--json', 'Output in JSON format').addOption(new external_commander_namespaceObject.Option('--project-id <id>').hideHelp()).action(async (options)=>{
             if (options.json) setJsonMode(true);
             job_runner_requireAuth(manager_isAuthenticated);
             const { prompts, count, mode } = validateOptions(options);
@@ -1111,7 +1120,7 @@ superdesign --help
         return response.data;
     }
     function createSearchPromptsCommand() {
-        const command = new external_commander_namespaceObject.Command('search-prompts').description('Search public prompts in the library').option('--keyword <text>', "Search keyword (searches title and description)").option('--tags <tags>', 'Comma-separated tags to filter by').option('--limit <n>', 'Maximum number of results (default: 20, max: 100)').option('--offset <n>', 'Number of results to skip (for pagination)').option('--json', 'Output in JSON format').action(async (options)=>{
+        const command = new external_commander_namespaceObject.Command('search-prompts').description('Search public prompts in the library').option('--query <text>', "Search query (searches title and description)").option('--tags <tags>', 'Comma-separated tags to filter by').option('--limit <n>', 'Maximum number of results (default: 20, max: 100)').option('--offset <n>', 'Number of results to skip (for pagination)').option('--json', 'Output in JSON format').action(async (options)=>{
             if (options.json) setJsonMode(true);
             job_runner_requireAuth(manager_isAuthenticated);
             const spinner = isJsonMode() ? null : external_ora_default()('Searching prompts...').start();
@@ -1120,7 +1129,7 @@ superdesign --help
                 const limit = options.limit ? parseInt(options.limit, 10) : 20;
                 const offset = options.offset ? parseInt(options.offset, 10) : 0;
                 const result = await searchPrompts({
-                    keyword: options.keyword,
+                    keyword: options.query,
                     tags,
                     limit,
                     offset
@@ -1306,7 +1315,7 @@ superdesign --help
             durationMs: opts.durationMs,
             errorCode: opts.errorCode,
             options: opts.options,
-            cliVersion: "0.1.8",
+            cliVersion: "0.1.9",
             os: `${external_os_default().platform()} ${external_os_default().release()}`
         };
         const posthog = getPostHog();
@@ -1343,7 +1352,7 @@ superdesign --help
     (0, external_dotenv_namespaceObject.config)();
     function createProgram() {
         const program = new external_commander_namespaceObject.Command();
-        program.name('superdesign').description('SuperDesign CLI - AI product designer for coding agents').version("0.1.8");
+        program.name('superdesign').description('SuperDesign CLI - AI product designer for coding agents').version("0.1.9");
         let startTime = 0;
         program.hook('preAction', ()=>{
             startTime = Date.now();
@@ -1361,15 +1370,17 @@ superdesign --help
         program.addCommand(createLogoutCommand());
         program.addCommand(createInitCommand());
         program.addCommand(createCreateProjectCommand());
-        program.addCommand(createCreateDesignDraftCommand());
         program.addCommand(createIterateDesignDraftCommand());
-        program.addCommand(createPlanFlowPagesCommand());
+        program.addCommand(createPlanFlowPagesCommand(), {
+            hidden: true
+        });
         program.addCommand(createExecuteFlowPagesCommand());
         program.addCommand(createExtractBrandGuideCommand());
         program.addCommand(createSearchPromptsCommand());
         program.addCommand(createGetPromptsCommand());
         program.addCommand(createFetchDesignNodesCommand());
         program.addCommand(createGetDesignCommand());
+        program.addCommand(createCreateDesignDraftCommand());
         return program;
     }
     async function run() {

package/dist/index.js

@@ -1,7 +1,7 @@
 import { config as external_dotenv_config } from "dotenv";
 import { fileURLToPath } from "url";
 import { dirname, join, resolve as external_path_resolve } from "path";
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import { appendFileSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
 import os, { homedir, hostname, platform, release } from "os";
 import axios from "axios";
@@ -226,7 +226,7 @@ async function runAuthFlow(options = {}) {
     try {
         startSpinner('Creating auth session...');
         const session = await createSession({
-            cliVersion: "0.1.8",
+            cliVersion: "0.1.9",
             os: `${platform()} ${release()}`,
             hostname: hostname()
         });
@@ -634,23 +634,24 @@ function validateDeviceMode(device) {
         process.exit(EXIT_CODES.VALIDATION_ERROR);
     }
 }
-function readFileContent(filePath, inlineContent, fileType) {
-    if (filePath) {
-        if (!existsSync(filePath)) {
-            output_error(`${fileType} file not found: ${filePath}`);
-            process.exit(EXIT_CODES.VALIDATION_ERROR);
-        }
-        return readFileSync(filePath, 'utf-8');
+function readFileIfExists(filePath) {
+    if (existsSync(filePath)) return readFileSync(filePath, 'utf-8');
+}
+function readFileOrError(filePath, fileType) {
+    if (!existsSync(filePath)) {
+        output_error(`${fileType} file not found: ${filePath}`);
+        process.exit(EXIT_CODES.VALIDATION_ERROR);
     }
-    return inlineContent;
+    return readFileSync(filePath, 'utf-8');
 }
 function createCreateProjectCommand() {
-    const command = new Command('create-project').description('Create a new SuperDesign project').requiredOption('--title <title>', 'Project title').option('--html <html>', 'Initial HTML content for first draft').option('--html-file <path>', 'Path to HTML file for first draft').option('-s, --set-project-prompt <prompt>', 'System prompt for the AI agent').option('--set-project-prompt-file <path>', 'Path to markdown file containing system prompt').option('--device <mode>', 'Device mode for draft (mobile, tablet, desktop)', 'desktop').option('--json', 'Output in JSON format').option('--no-open', 'Do not open project in browser after creation').action(async (options)=>{
+    const command = new Command('create-project').description('Create a new SuperDesign project').requiredOption('--title <title>', 'Project title').option('--template <path>', 'Path to HTML template file for first draft').option('--device <mode>', 'Device mode for html template (mobile, tablet, desktop)', 'desktop').option('--json', 'Output in JSON format').action(async (options)=>{
         if (options.json) setJsonMode(true);
         job_runner_requireAuth(manager_isAuthenticated);
         validateDeviceMode(options.device);
-        const htmlContent = readFileContent(options.htmlFile, options.html, 'HTML');
-        const promptContent = readFileContent(options.setProjectPromptFile, options.setProjectPrompt, 'Prompt');
+        const htmlContent = options.template ? readFileOrError(options.template, 'Template') : void 0;
+        const designSystemPath = '.superdesign/design-system.md';
+        const promptContent = readFileIfExists(designSystemPath);
         startSpinner('Creating project...');
         try {
             const project = await createProject({
@@ -660,10 +661,8 @@ function createCreateProjectCommand() {
                 deviceMode: options.device
             });
             succeedSpinner('Project created successfully!');
-            if (options.open) {
-                const urlWithLive = `${project.projectUrl}?live=1`;
-                await openBrowser(urlWithLive);
-            }
+            const urlWithLive = `${project.projectUrl}?live=1`;
+            await openBrowser(urlWithLive);
             if (isJsonMode()) output({
                 projectId: project.projectId,
                 title: project.title,
@@ -711,7 +710,7 @@ async function executeFlowPages(draftId, data) {
     return response.data;
 }
 function createCreateDesignDraftCommand() {
-    const command = new Command('create-design-draft').description('Create a design draft using AI generation').requiredOption('--project-id <id>', 'Project ID').requiredOption('--title <title>', 'Draft title').requiredOption('-p, --prompt <prompt>', 'Design prompt for AI generation').option('--device <mode>', 'Device mode (mobile, tablet, desktop)', 'desktop').option('--json', 'Output in JSON format').action(async (options)=>{
+    const command = new Command('create-design-draft').description('Create a design draft from scratch without any reference, Default dont use this, use iterate-design-draft instead').requiredOption('--project-id <id>', 'Project ID').requiredOption('--title <title>', 'Draft title').requiredOption('-p, --prompt <prompt>', 'Design prompt for AI generation').option('--device <mode>', 'Device mode (mobile, tablet, desktop)', 'desktop').option('--json', 'Output in JSON format').action(async (options)=>{
         if (options.json) setJsonMode(true);
         job_runner_requireAuth(manager_isAuthenticated);
         validateDeviceMode(options.device);
@@ -786,7 +785,17 @@ function validateOptions(options) {
     };
 }
 function createIterateDesignDraftCommand() {
-    const command = new Command('iterate-design-draft').description('Iterate on an existing draft using AI').requiredOption('--draft-id <id>', 'Draft ID to iterate on').requiredOption('-p, --prompt <prompt...>', 'Iteration prompt(s). Use multiple -p for specific prompts per variation.').requiredOption('--mode <mode>', 'Iteration mode (replace or branch)').option('--count <count>', 'Number of variations (1-4). Only used when single prompt provided.').option('--json', 'Output in JSON format').action(async (options)=>{
+    const command = new Command('iterate-design-draft').description(`Generate design based on existing draft or template, the main design exploration tool
+
+Usage Examples:
+  # Iterate: replace mode (single variation, updates in place)
+  superdesign iterate-design-draft --draft-id <id> -p "..." --mode replace --json
+
+  # Iterate: Explore multiple versions & variations (each prompt = one variation, prompt should be just directional, do not specify color, style, let superdesign design expert fill in details, you just give direction)
+  superdesign iterate-design-draft --draft-id <id> -p "dark theme" -p "minimal" -p "bold" --mode branch --json
+
+  # Iterate: Auto explore (only give exploration direction, and let Superdesign fill in details, e.g. explore different styles; Default do NOT use auto explore mode)
+  superdesign iterate-design-draft --draft-id <id> -p "..." --mode branch --count 3 --json`).requiredOption('--draft-id <id>', 'Draft ID to iterate on').requiredOption('-p, --prompt <prompt...>', 'Iteration prompt(s). Use multiple -p for specific prompts per variation.').requiredOption('--mode <mode>', 'Iteration mode (replace or branch)').option('--count <count>', 'Number of variations (1-4). Only used when single prompt provided.').option('--json', 'Output in JSON format').addOption(new Option('--project-id <id>').hideHelp()).action(async (options)=>{
         if (options.json) setJsonMode(true);
         job_runner_requireAuth(manager_isAuthenticated);
         const { prompts, count, mode } = validateOptions(options);
@@ -1021,7 +1030,7 @@ async function getPrompts(data) {
     return response.data;
 }
 function createSearchPromptsCommand() {
-    const command = new Command('search-prompts').description('Search public prompts in the library').option('--keyword <text>', "Search keyword (searches title and description)").option('--tags <tags>', 'Comma-separated tags to filter by').option('--limit <n>', 'Maximum number of results (default: 20, max: 100)').option('--offset <n>', 'Number of results to skip (for pagination)').option('--json', 'Output in JSON format').action(async (options)=>{
+    const command = new Command('search-prompts').description('Search public prompts in the library').option('--query <text>', "Search query (searches title and description)").option('--tags <tags>', 'Comma-separated tags to filter by').option('--limit <n>', 'Maximum number of results (default: 20, max: 100)').option('--offset <n>', 'Number of results to skip (for pagination)').option('--json', 'Output in JSON format').action(async (options)=>{
         if (options.json) setJsonMode(true);
         job_runner_requireAuth(manager_isAuthenticated);
         const spinner = isJsonMode() ? null : ora('Searching prompts...').start();
@@ -1030,7 +1039,7 @@ function createSearchPromptsCommand() {
             const limit = options.limit ? parseInt(options.limit, 10) : 20;
             const offset = options.offset ? parseInt(options.offset, 10) : 0;
             const result = await searchPrompts({
-                keyword: options.keyword,
+                keyword: options.query,
                 tags,
                 limit,
                 offset
@@ -1214,7 +1223,7 @@ async function trackCommand(opts) {
         durationMs: opts.durationMs,
         errorCode: opts.errorCode,
         options: opts.options,
-        cliVersion: "0.1.8",
+        cliVersion: "0.1.9",
         os: `${os.platform()} ${os.release()}`
     };
     const posthog = getPostHog();
@@ -1251,7 +1260,7 @@ external_dotenv_config({
 external_dotenv_config();
 function createProgram() {
     const program = new Command();
-    program.name('superdesign').description('SuperDesign CLI - AI product designer for coding agents').version("0.1.8");
+    program.name('superdesign').description('SuperDesign CLI - AI product designer for coding agents').version("0.1.9");
     let startTime = 0;
     program.hook('preAction', ()=>{
         startTime = Date.now();
@@ -1269,15 +1278,17 @@ function createProgram() {
     program.addCommand(createLogoutCommand());
     program.addCommand(createInitCommand());
     program.addCommand(createCreateProjectCommand());
-    program.addCommand(createCreateDesignDraftCommand());
     program.addCommand(createIterateDesignDraftCommand());
-    program.addCommand(createPlanFlowPagesCommand());
+    program.addCommand(createPlanFlowPagesCommand(), {
+        hidden: true
+    });
     program.addCommand(createExecuteFlowPagesCommand());
     program.addCommand(createExtractBrandGuideCommand());
     program.addCommand(createSearchPromptsCommand());
     program.addCommand(createGetPromptsCommand());
     program.addCommand(createFetchDesignNodesCommand());
     program.addCommand(createGetDesignCommand());
+    program.addCommand(createCreateDesignDraftCommand());
     return program;
 }
 async function run() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdesign/cli",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "CLI for SuperDesign Platform - agent skills for Claude Code",
   "type": "module",
   "main": "./dist/index.cjs",