@output.ai/cli 0.5.0 → 0.5.2

package/dist/services/env_configurator.d.ts

@@ -2,10 +2,14 @@
  * Interactively configures environment variables for a project by prompting the user
  * to provide values for empty variables or variables marked as secrets.
  *
- * @param projectPath - The absolute path to the project directory containing the .env file
+ * This function reads from .env.example and, when the user confirms configuration,
+ * copies it to .env before prompting for values. The .env.example file remains
+ * unchanged as a template for other developers.
+ *
+ * @param projectPath - The absolute path to the project directory containing the .env.example file
  * @param skipPrompt - If true, skips the configuration prompt and returns false immediately
  * @returns A promise that resolves to true if environment variables were successfully configured,
- *          false if configuration was skipped (no .env file, user declined, no variables to configure,
+ *          false if configuration was skipped (no .env.example file, user declined, no variables to configure,
  *          or an error occurred)
  */
 export declare function configureEnvironmentVariables(projectPath: string, skipPrompt?: boolean): Promise<boolean>;

package/dist/services/env_configurator.js

@@ -115,10 +115,14 @@ async function writeEnvFile(filePath, variables) {
  * Interactively configures environment variables for a project by prompting the user
  * to provide values for empty variables or variables marked as secrets.
  *
- * @param projectPath - The absolute path to the project directory containing the .env file
+ * This function reads from .env.example and, when the user confirms configuration,
+ * copies it to .env before prompting for values. The .env.example file remains
+ * unchanged as a template for other developers.
+ *
+ * @param projectPath - The absolute path to the project directory containing the .env.example file
  * @param skipPrompt - If true, skips the configuration prompt and returns false immediately
  * @returns A promise that resolves to true if environment variables were successfully configured,
- *          false if configuration was skipped (no .env file, user declined, no variables to configure,
+ *          false if configuration was skipped (no .env.example file, user declined, no variables to configure,
  *          or an error occurred)
  */
 export async function configureEnvironmentVariables(projectPath, skipPrompt = false) {
@@ -126,12 +130,13 @@ export async function configureEnvironmentVariables(projectPath, skipPrompt = fa
         return false;
     }
     ux.stdout('configuring environment variables...');
+    const envExamplePath = path.join(projectPath, '.env.example');
     const envPath = path.join(projectPath, '.env');
     try {
-        await fs.access(envPath);
+        await fs.access(envExamplePath);
     }
     catch {
-        ux.stdout(ux.colorize('red', '🔴 .env file does not exist, nothing to configure'));
+        ux.stdout(ux.colorize('red', '.env.example file does not exist, nothing to configure'));
         return false;
     }
     const shouldConfigure = await confirm({
@@ -142,6 +147,8 @@ export async function configureEnvironmentVariables(projectPath, skipPrompt = fa
         return false;
     }
     try {
+        // Copy .env.example to .env before configuring
+        await fs.copyFile(envExamplePath, envPath);
         const variables = await parseEnvFile(envPath);
         const variablesToConfigure = variables.filter(v => isEmpty(v.value) || v.isSecret);
         if (variablesToConfigure.length === 0) {

package/dist/services/env_configurator.spec.js

@@ -5,16 +5,18 @@ import { configureEnvironmentVariables } from './env_configurator.js';
 // Mock inquirer prompts
 vi.mock('@inquirer/prompts', () => ({
     input: vi.fn(),
-    confirm: vi.fn()
+    confirm: vi.fn(),
+    password: vi.fn()
 }));
 describe('configureEnvironmentVariables', () => {
-    const testState = { tempDir: '', envPath: '' };
+    const testState = { tempDir: '', envExamplePath: '', envPath: '' };
     beforeEach(async () => {
         // Clear all mocks before each test
         vi.clearAllMocks();
         // Create temporary directory for test files
         testState.tempDir = path.join('/tmp', `test-env-${Date.now()}`);
         await fs.mkdir(testState.tempDir, { recursive: true });
+        testState.envExamplePath = path.join(testState.tempDir, '.env.example');
         testState.envPath = path.join(testState.tempDir, '.env');
     });
     afterEach(async () => {
@@ -27,36 +29,74 @@ describe('configureEnvironmentVariables', () => {
         }
     });
     it('should return false if skipPrompt is true', async () => {
-        // Create a minimal .env file
-        await fs.writeFile(testState.envPath, 'KEY=value');
+        // Create a minimal .env.example file
+        await fs.writeFile(testState.envExamplePath, 'KEY=value');
         const result = await configureEnvironmentVariables(testState.tempDir, true);
         expect(result).toBe(false);
     });
-    it('should return false if .env file does not exist', async () => {
+    it('should return false if .env.example file does not exist', async () => {
         const result = await configureEnvironmentVariables(testState.tempDir, false);
         expect(result).toBe(false);
     });
     it('should return false if user declines configuration', async () => {
         const { confirm } = await import('@inquirer/prompts');
         vi.mocked(confirm).mockResolvedValue(false);
-        await fs.writeFile(testState.envPath, '# API key\nAPIKEY=');
+        await fs.writeFile(testState.envExamplePath, '# API key\nAPIKEY=');
         const result = await configureEnvironmentVariables(testState.tempDir, false);
         expect(result).toBe(false);
         expect(vi.mocked(confirm)).toHaveBeenCalled();
     });
+    it('should NOT create .env when user declines configuration', async () => {
+        const { confirm } = await import('@inquirer/prompts');
+        vi.mocked(confirm).mockResolvedValue(false);
+        await fs.writeFile(testState.envExamplePath, '# API key\nAPIKEY=');
+        await configureEnvironmentVariables(testState.tempDir, false);
+        // .env should NOT exist when user declines
+        await expect(fs.access(testState.envPath)).rejects.toThrow();
+        // .env.example should still exist
+        await expect(fs.access(testState.envExamplePath)).resolves.toBeUndefined();
+    });
     it('should return false if no empty variables exist', async () => {
         const { confirm } = await import('@inquirer/prompts');
         vi.mocked(confirm).mockResolvedValue(true);
-        await fs.writeFile(testState.envPath, 'APIKEY=my-secret-key');
+        await fs.writeFile(testState.envExamplePath, 'APIKEY=my-secret-key');
         const result = await configureEnvironmentVariables(testState.tempDir, false);
         expect(result).toBe(false);
     });
+    it('should copy .env.example to .env when user confirms configuration', async () => {
+        const { input, confirm } = await import('@inquirer/prompts');
+        vi.mocked(confirm).mockResolvedValue(true);
+        vi.mocked(input).mockResolvedValueOnce('sk-proj-123');
+        const originalContent = `# API key
+APIKEY=`;
+        await fs.writeFile(testState.envExamplePath, originalContent);
+        await configureEnvironmentVariables(testState.tempDir, false);
+        // Both files should exist
+        await expect(fs.access(testState.envExamplePath)).resolves.toBeUndefined();
+        await expect(fs.access(testState.envPath)).resolves.toBeUndefined();
+    });
+    it('should write configured values to .env while leaving .env.example unchanged', async () => {
+        const { input, confirm } = await import('@inquirer/prompts');
+        vi.mocked(confirm).mockResolvedValue(true);
+        vi.mocked(input).mockResolvedValueOnce('sk-proj-123');
+        const originalContent = `# API key
+APIKEY=`;
+        await fs.writeFile(testState.envExamplePath, originalContent);
+        const result = await configureEnvironmentVariables(testState.tempDir, false);
+        expect(result).toBe(true);
+        // .env should have the configured value
+        const envContent = await fs.readFile(testState.envPath, 'utf-8');
+        expect(envContent).toContain('APIKEY=sk-proj-123');
+        // .env.example should remain unchanged
+        const envExampleContent = await fs.readFile(testState.envExamplePath, 'utf-8');
+        expect(envExampleContent).toBe(originalContent);
+    });
     it('should prompt for empty variables and update .env', async () => {
         const { input, confirm } = await import('@inquirer/prompts');
         vi.mocked(confirm).mockResolvedValue(true);
         vi.mocked(input).mockResolvedValueOnce('sk-proj-123');
         vi.mocked(input).mockResolvedValueOnce('');
-        await fs.writeFile(testState.envPath, `# API key for Anthropic
+        await fs.writeFile(testState.envExamplePath, `# API key for Anthropic
 ANTHROPIC_API_KEY=
 
 # API key for OpenAI
@@ -78,7 +118,7 @@ APIKEY=
 
 # Another comment
 OTHER=value`;
-        await fs.writeFile(testState.envPath, originalContent);
+        await fs.writeFile(testState.envExamplePath, originalContent);
         await configureEnvironmentVariables(testState.tempDir, false);
         const content = await fs.readFile(testState.envPath, 'utf-8');
         expect(content).toContain('# This is a comment');
@@ -90,7 +130,7 @@ OTHER=value`;
         const { input, confirm } = await import('@inquirer/prompts');
         vi.mocked(confirm).mockResolvedValue(true);
         vi.mocked(input).mockResolvedValueOnce('new-key');
-        await fs.writeFile(testState.envPath, `APIKEY=your_api_key_here
+        await fs.writeFile(testState.envExamplePath, `APIKEY=your_api_key_here
 EMPTY_KEY=`);
         const result = await configureEnvironmentVariables(testState.tempDir, false);
         expect(result).toBe(true);
@@ -103,21 +143,54 @@ EMPTY_KEY=`);
         const { input, confirm } = await import('@inquirer/prompts');
         vi.mocked(confirm).mockResolvedValue(true);
         vi.mocked(input).mockResolvedValueOnce('new-key');
-        await fs.writeFile(testState.envPath, `EXISTING_KEY=existing-value
+        await fs.writeFile(testState.envExamplePath, `EXISTING_KEY=existing-value
 
 EMPTY_KEY=`);
         await configureEnvironmentVariables(testState.tempDir, false);
         // Should only prompt for EMPTY_KEY, not EXISTING_KEY
         expect(vi.mocked(input)).toHaveBeenCalledTimes(1);
     });
+    it('should handle case where .env already exists (overwrite with copy)', async () => {
+        const { input, confirm } = await import('@inquirer/prompts');
+        vi.mocked(confirm).mockResolvedValue(true);
+        vi.mocked(input).mockResolvedValueOnce('new-configured-value');
+        // Create existing .env with old content
+        await fs.writeFile(testState.envPath, 'OLD_KEY=old-value');
+        // Create .env.example with new content
+        await fs.writeFile(testState.envExamplePath, 'NEW_KEY=');
+        const result = await configureEnvironmentVariables(testState.tempDir, false);
+        expect(result).toBe(true);
+        // .env should be overwritten with .env.example content and configured values
+        const envContent = await fs.readFile(testState.envPath, 'utf-8');
+        expect(envContent).toContain('NEW_KEY=new-configured-value');
+        expect(envContent).not.toContain('OLD_KEY');
+    });
     it('should return false if an error occurs during parsing', async () => {
-        // This test verifies error handling by checking behavior when file operations fail
-        // The try-catch in configureEnvironmentVariables should handle it gracefully
-        await fs.writeFile(testState.envPath, 'KEY=');
-        // Delete the file to cause parsing error
-        await fs.rm(testState.envPath);
+        const { confirm } = await import('@inquirer/prompts');
+        vi.mocked(confirm).mockResolvedValue(true);
+        await fs.writeFile(testState.envExamplePath, 'KEY=');
+        // Delete the .env.example file after access check but before parsing would happen
+        // We simulate this by deleting during the copy operation
+        const originalCopyFile = fs.copyFile;
+        vi.spyOn(fs, 'copyFile').mockImplementation(async () => {
+            throw new Error('Copy failed');
+        });
         const result = await configureEnvironmentVariables(testState.tempDir, false);
         // Should return false when error occurs
         expect(result).toBe(false);
+        // Restore original function
+        vi.mocked(fs.copyFile).mockImplementation(originalCopyFile);
+    });
+    it('should prompt for SECRET marker values with password input', async () => {
+        const { password, confirm } = await import('@inquirer/prompts');
+        vi.mocked(confirm).mockResolvedValue(true);
+        vi.mocked(password).mockResolvedValueOnce('my-secret-api-key');
+        await fs.writeFile(testState.envExamplePath, `# API Key
+ANTHROPIC_API_KEY=<SECRET>`);
+        const result = await configureEnvironmentVariables(testState.tempDir, false);
+        expect(result).toBe(true);
+        expect(vi.mocked(password)).toHaveBeenCalledTimes(1);
+        const envContent = await fs.readFile(testState.envPath, 'utf-8');
+        expect(envContent).toContain('ANTHROPIC_API_KEY=my-secret-api-key');
     });
 });

package/dist/services/messages.js

@@ -166,8 +166,8 @@ export const getProjectSuccessMessage = (folderName, installSuccess, envConfigur
     if (!envConfigured) {
         steps.push({
             step: 'Configure environment variables',
-            command: 'Edit .env file',
-            note: 'Add your Anthropic/OpenAI API keys'
+            command: 'cp .env.example .env',
+            note: 'Copy .env.example to .env and add your API keys'
         });
     }
     steps.push({
@@ -248,8 +248,8 @@ export const getWorkflowGenerateSuccessMessage = (workflowName, targetDir, files
         },
         {
             step: 'Configure environment',
-            command: 'Edit .env file',
-            note: 'Add your LLM provider credentials (ANTHROPIC_API_KEY or OPENAI_API_KEY)'
+            command: 'cp .env.example .env',
+            note: 'Copy .env.example to .env and add your LLM provider credentials'
         },
         {
             step: 'Test with example scenario',

package/dist/services/workflow_generator.spec.js

@@ -65,7 +65,6 @@ describe('Workflow Generator', () => {
                 'workflow.ts',
                 'steps.ts',
                 'README.md',
-                '.env',
                 'prompts/prompt@v1.prompt',
                 'scenarios/test_input.json'
             ];

package/dist/templates/agent_instructions/AGENTS.md.template

@@ -40,17 +40,17 @@ src/workflows/{name}/
 ## Commands
 
 ```bash
-output dev                                      # Start dev (Temporal:8080, API:3001)
-output workflow list                            # List workflows
+npx output dev                                      # Start dev (Temporal:8080, API:3001)
+npx output workflow list                            # List workflows
 
 # Sync execution (waits for result)
-output workflow run <name> --input <JSON|JSON_FILE>      # Execute and wait
+npx output workflow run <name> --input <JSON|JSON_FILE>      # Execute and wait
 
 # Async execution
-output workflow start <name> --input <JSON|JSON_FILE>    # Start workflow, returns ID
-output workflow status <workflowId>             # Check execution status
-output workflow result <workflowId>             # Get result when complete
-output workflow stop <workflowId>               # Cancel running workflow
+npx output workflow start <name> --input <JSON|JSON_FILE>    # Start workflow, returns ID
+npx output workflow status <workflowId>             # Check execution status
+npx output workflow result <workflowId>             # Get result when complete
+npx output workflow stop <workflowId>               # Cancel running workflow
 ```
 
 ## Workflow Pattern

package/dist/templates/agent_instructions/agents/workflow_debugger.md.template

@@ -30,15 +30,15 @@ For detailed command usage, Claude will automatically invoke the relevant skill.
 
 | Command | Purpose |
 |---------|---------|
-| `output dev` | Start development services |
-| `output workflow list` | List available workflows |
-| `output workflow runs list` | List execution history |
-| `output workflow run` | Execute synchronously |
-| `output workflow start` | Start asynchronously |
-| `output workflow status` | Check execution status |
-| `output workflow result` | Get execution result |
-| `output workflow stop` | Stop running workflow |
-| `output workflow debug` | Analyze execution trace |
+| `npx output dev` | Start development services |
+| `npx output workflow list` | List available workflows |
+| `npx output workflow runs list` | List execution history |
+| `npx output workflow run` | Execute synchronously |
+| `npx output workflow start` | Start asynchronously |
+| `npx output workflow status` | Check execution status |
+| `npx output workflow result` | Get execution result |
+| `npx output workflow stop` | Stop running workflow |
+| `npx output workflow debug` | Analyze execution trace |
 
 ## Temporal UI
 
@@ -73,7 +73,7 @@ Match error symptoms to solutions and verify the fix.
 **Agent**: Let me help you debug this workflow. First, let's get the execution trace:
 
 ```bash
-output workflow debug abc123 --format json
+npx output workflow debug abc123 --format json
 ```
 
 This will show us exactly where the workflow failed and what error occurred. While I analyze the trace, you can also check the Temporal UI at http://localhost:8080 for a visual timeline of the execution.
@@ -92,7 +92,7 @@ To:
 import { z } from '@output.ai/core';
 ```
 
-After making this change, run the workflow again with `output workflow run <workflowName>` to verify the fix.
+After making this change, run the workflow again with `npx output workflow run <workflowName>` to verify the fix.
 
 ---
 *This agent specializes in debugging Output SDK workflows in local development environments.*

package/dist/templates/agent_instructions/commands/debug_workflow.md.template

@@ -47,7 +47,7 @@ curl -s http://localhost:8080 > /dev/null && echo "Temporal UI accessible" || ec
     RUN: docker compose up -d
     WAIT: for services to start (30-60 seconds)
   IF output_dev_not_running:
-    RUN: output dev
+    RUN: npx output dev
     WAIT: for services to initialize
   IF all_services_running:
     PROCEED: to step 2
@@ -69,16 +69,16 @@ Identify the failing workflow execution by listing recent runs. The `output-work
 <list_commands>
 ```bash
 # List all recent workflow runs
-output workflow runs list
+npx output workflow runs list
 
 # Filter by specific workflow type (if known)
-output workflow runs list <workflowName>
+npx output workflow runs list <workflowName>
 
 # Get detailed JSON output for analysis
-output workflow runs list --format json
+npx output workflow runs list --format json
 
 # Limit results to most recent
-output workflow runs list --limit 10
+npx output workflow runs list --limit 10
 ```
 </list_commands>
 
@@ -98,12 +98,12 @@ Look for:
     NOTE: workflow ID from output
     PROCEED: to step 3
   IF no_runs_found:
-    CHECK: workflow exists with `output workflow list`
+    CHECK: workflow exists with `npx output workflow list`
     IF workflow_not_found:
       REPORT: workflow doesn't exist
       SUGGEST: verify workflow name and location
     ELSE:
-      SUGGEST: run the workflow with `output workflow run <name>`
+      SUGGEST: run the workflow with `npx output workflow run <name>`
 </decision_tree>
 
 </step>
@@ -117,10 +117,10 @@ Retrieve and analyze the execution trace for the identified workflow. The `outpu
 <debug_commands>
 ```bash
 # Display execution trace (text format)
-output workflow debug <workflowId>
+npx output workflow debug <workflowId>
 
 # Display full untruncated trace (JSON format) - recommended for detailed analysis
-output workflow debug <workflowId> --format json
+npx output workflow debug <workflowId> --format json
 ```
 </debug_commands>
 
@@ -174,12 +174,12 @@ Based on the trace analysis, identify the error pattern and suggest targeted fix
 After applying fix:
 ```bash
 # Re-run the workflow to verify
-output workflow run <workflowName> <input>
+npx output workflow run <workflowName> <input>
 
 # Or start asynchronously and check result
-output workflow start <workflowName> <input>
-output workflow status <workflowId>
-output workflow result <workflowId>
+npx output workflow start <workflowName> <input>
+npx output workflow status <workflowId>
+npx output workflow result <workflowId>
 ```
 </verification>
 

package/dist/templates/agent_instructions/commands/plan_workflow.md.template

@@ -213,7 +213,7 @@ Design the testing strategy for the workflow.
 
 Generate the complete plan in markdown format.
 
-Note that every implementation should start with running the cli command `output workflow generate --skeleton` to create the workflow directory structure.
+Note that every implementation should start with running the cli command `npx output workflow generate --skeleton` to create the workflow directory structure.
 
 <file_template>
   <header>

package/dist/templates/agent_instructions/skills/output-error-direct-io/SKILL.md.template

@@ -230,8 +230,8 @@ Workflow functions should NOT contain:
 
 After moving I/O to steps:
 
-1. **Run the workflow**: `output workflow run <name> '<input>'`
-2. **Check the trace**: `output workflow debug <id> --format json`
+1. **Run the workflow**: `npx output workflow run <name> '<input>'`
+2. **Check the trace**: `npx output workflow debug <id> --format json`
 3. **Verify steps appear**: Look for your I/O steps in the trace
 4. **Confirm no errors**: No determinism warnings or hangs
 

package/dist/templates/agent_instructions/skills/output-error-http-client/SKILL.md.template

@@ -287,8 +287,8 @@ grep -rn "got\|node-fetch\|request\|superagent" src/
 
 After migrating to httpClient:
 
-1. **Run the workflow**: `output workflow run <name> '<input>'`
-2. **Check the trace**: `output workflow debug <id> --format json`
+1. **Run the workflow**: `npx output workflow run <name> '<input>'`
+2. **Check the trace**: `npx output workflow debug <id> --format json`
 3. **Verify tracing**: HTTP requests should appear in the step trace
 4. **Test retries**: Simulate failures to verify retry behavior
 

package/dist/templates/agent_instructions/skills/output-error-missing-schemas/SKILL.md.template

@@ -255,8 +255,8 @@ export const logEvent = step({
 
 After adding schemas:
 
-1. **TypeScript check**: `npm run build` should pass without type errors
-2. **Runtime test**: `output workflow run <name> '<input>'` should validate correctly
+1. **TypeScript check**: `npm run output:workflow:build` should pass without type errors
+2. **Runtime test**: `npx output workflow run <name> '<input>'` should validate correctly
 3. **Invalid input test**: Pass invalid data and verify validation errors appear
 
 ## Related Issues

package/dist/templates/agent_instructions/skills/output-error-nondeterminism/SKILL.md.template

@@ -216,7 +216,7 @@ Look at your workflow `fn` functions specifically. Non-deterministic code is onl
 ## Verification Steps
 
 1. **Fix the code** using solutions above
-2. **Run the workflow**: `output workflow run <name> '<input>'`
+2. **Run the workflow**: `npx output workflow run <name> '<input>'`
 3. **Run again with same input**: Result should be identical
 4. **Check for errors**: No "non-deterministic" messages
 
@@ -238,10 +238,10 @@ If unsure whether code is causing issues:
 
 ```bash
 # Run the workflow
-output workflow start my-workflow '{"input": "test"}'
+npx output workflow start my-workflow '{"input": "test"}'
 
 # Get the workflow ID and run debug to see replay behavior
-output workflow debug <workflowId> --format json
+npx output workflow debug <workflowId> --format json
 ```
 
 Look for errors or warnings about non-determinism in the trace.

package/dist/templates/agent_instructions/skills/output-error-try-catch/SKILL.md.template

@@ -216,9 +216,9 @@ Do NOT use FatalError to wrap other errors unless you're certain they shouldn't
 
 After removing try-catch:
 
-1. **Test normal operation**: `output workflow run <name> '<valid-input>'`
+1. **Test normal operation**: `npx output workflow run <name> '<valid-input>'`
 2. **Test failure scenarios**: Use input that causes step failures
-3. **Check retry behavior**: Look for retry attempts in `output workflow debug <id>`
+3. **Check retry behavior**: Look for retry attempts in `npx output workflow debug <id>`
 
 ## Related Issues
 

package/dist/templates/agent_instructions/skills/output-error-zod-import/SKILL.md.template

@@ -139,13 +139,13 @@ grep -r 'from "zod"' src/
 ### 2. Build the project
 
 ```bash
-npm run build
+npm run output:workflow:build
 ```
 
 ### 3. Run the workflow
 
 ```bash
-output workflow run <workflowName> '<input>'
+npx output workflow run <workflowName> '<input>'
 ```
 
 ## Prevention

package/dist/templates/agent_instructions/skills/output-services-check/SKILL.md.template

@@ -55,7 +55,7 @@ curl -s http://localhost:8080 > /dev/null && echo "Temporal UI accessible" || ec
 ### If services are not running:
 ```bash
 # Start all development services
-output dev
+npx output dev
 ```
 
 Wait 30-60 seconds for all services to initialize, then re-run the checks.
@@ -80,7 +80,7 @@ IF docker_not_running:
   WAIT: for Docker to initialize
 
 IF no_output_containers:
-  RUN: output dev
+  RUN: npx output dev
   WAIT: 30-60 seconds for services
 
 IF api_not_responding:
@@ -105,7 +105,7 @@ docker ps | grep output
 # Output: (empty - no containers)
 
 # Start services
-output dev
+npx output dev
 
 # Wait and verify
 sleep 60

package/dist/templates/agent_instructions/skills/output-workflow-list/SKILL.md.template

@@ -23,7 +23,7 @@ This skill helps you discover all available workflows in an Output SDK project.
 ### List All Workflows
 
 ```bash
-output workflow list
+npx output workflow list
 ```
 
 This command scans the project and displays all available workflows.
@@ -67,7 +67,7 @@ ls -la src/workflows/<workflowName>/
 **Scenario**: Discover available workflows in a project
 
 ```bash
-output workflow list
+npx output workflow list
 
 # Example output:
 # Name          Description                    Location
@@ -81,18 +81,18 @@ output workflow list
 
 ```bash
 # Check if "email-sender" workflow exists
-output workflow list | grep email-sender
+npx output workflow list | grep email-sender
 
 # If no output, the workflow doesn't exist
 # If found, proceed with running it
-output workflow run email-sender '{"to": "user@example.com"}'
+npx output workflow run email-sender '{"to": "user@example.com"}'
 ```
 
 **Scenario**: Explore workflow implementation
 
 ```bash
 # List workflows
-output workflow list
+npx output workflow list
 
 # Find the location and examine it
 cat src/workflows/simple/workflow.ts
@@ -108,10 +108,10 @@ cat src/workflows/simple/workflow.ts
 ### Workflow not showing
 - Check the file exports a valid workflow definition
 - Ensure the workflow file compiles without errors
-- Run `npm run build` to check for TypeScript errors
+- Run `npm run output:workflow:build` to check for TypeScript errors
 
 ## Related Commands
 
-- `output workflow run <name>` - Execute a workflow synchronously
-- `output workflow start <name>` - Start a workflow asynchronously
-- `output workflow runs list` - View execution history
+- `npx output workflow run <name>` - Execute a workflow synchronously
+- `npx output workflow start <name>` - Start a workflow asynchronously
+- `npx output workflow runs list` - View execution history