@output.ai/cli 0.5.3 → 0.5.5

package/README.md

@@ -11,14 +11,31 @@ Command-line interface for creating and running Output Framework workflows.
 
 ```bash
 # Create a new project
-output init my-project
-cd my-project
+npx @output.ai/cli init
+cd <project-name>
 
 # Start development services
-output dev
+npx output dev
 
 # Run a workflow
-output workflow run simple --input '{"question": "who is ada lovelace?"}'
+npx output workflow run simple --input '{"question": "who is ada lovelace?"}'
+```
+
+## Environment Configuration
+
+By default, the CLI loads environment variables from `.env` in the current directory.
+
+To use a different env file, set the `OUTPUT_CLI_ENV` environment variable:
+
+```bash
+# Use production environment
+OUTPUT_CLI_ENV=.env.prod npx output workflow list
+
+# Use staging environment
+OUTPUT_CLI_ENV=.env.staging npx output workflow run my-workflow
+
+# Absolute path
+OUTPUT_CLI_ENV=/etc/output/production.env npx output workflow status wf-123
 ```
 
 ## Command Reference
@@ -47,7 +64,7 @@ Running `output dev` starts:
 |---------|-----|-------------|
 | Temporal UI | http://localhost:8080 | Monitor and debug workflows |
 | API Server | http://localhost:3001 | REST API for workflow execution |
-| Worker | — | Processes workflows with auto-reload |
+| Worker | - | Processes workflows with auto-reload |
 
 ## Documentation
 

package/dist/api/generated/api.d.ts

@@ -54,6 +54,60 @@ export interface TraceInfo {
     /** File destinations for trace data */
     destinations?: TraceInfoDestinations;
 }
+/**
+ * The workflow input
+ */
+export type TraceDataInput = {
+    [key: string]: unknown;
+};
+/**
+ * The workflow output
+ */
+export type TraceDataOutput = {
+    [key: string]: unknown;
+};
+export type TraceDataStepsItem = {
+    [key: string]: unknown;
+};
+/**
+ * Trace data containing workflow execution details
+ */
+export interface TraceData {
+    /** The workflow execution ID */
+    workflowId?: string;
+    /** The workflow input */
+    input?: TraceDataInput;
+    /** The workflow output */
+    output?: TraceDataOutput;
+    /** The workflow execution steps */
+    steps?: TraceDataStepsItem[];
+    [key: string]: unknown;
+}
+/**
+ * Indicates trace was fetched from remote storage
+ */
+export type TraceLogRemoteResponseSource = typeof TraceLogRemoteResponseSource[keyof typeof TraceLogRemoteResponseSource];
+export declare const TraceLogRemoteResponseSource: {
+    readonly remote: "remote";
+};
+export interface TraceLogRemoteResponse {
+    /** Indicates trace was fetched from remote storage */
+    source: TraceLogRemoteResponseSource;
+    data: TraceData;
+}
+/**
+ * Indicates trace is available locally
+ */
+export type TraceLogLocalResponseSource = typeof TraceLogLocalResponseSource[keyof typeof TraceLogLocalResponseSource];
+export declare const TraceLogLocalResponseSource: {
+    readonly local: "local";
+};
+export interface TraceLogLocalResponse {
+    /** Indicates trace is available locally */
+    source: TraceLogLocalResponseSource;
+    /** Absolute path to local trace file */
+    localPath: string;
+}
 /**
  * Current run status
  */
@@ -149,6 +203,13 @@ export type GetWorkflowIdResult200 = {
     output?: unknown;
     trace?: TraceInfo;
 };
+export type GetWorkflowIdTraceLog200 = TraceLogRemoteResponse | TraceLogLocalResponse;
+export type GetWorkflowIdTraceLog404 = {
+    error?: string;
+};
+export type GetWorkflowIdTraceLog500 = {
+    error?: string;
+};
 export type GetWorkflowCatalogId200 = {
     /** Each workflow available in this catalog */
     workflows?: Workflow[];
@@ -273,6 +334,31 @@ export type getWorkflowIdResultResponseError = (getWorkflowIdResultResponse404)
 export type getWorkflowIdResultResponse = (getWorkflowIdResultResponseSuccess | getWorkflowIdResultResponseError);
 export declare const getGetWorkflowIdResultUrl: (id: string) => string;
 export declare const getWorkflowIdResult: (id: string, options?: ApiRequestOptions) => Promise<getWorkflowIdResultResponse>;
+/**
+ * Returns trace data for a completed workflow. If trace is stored remotely (S3), fetches and returns the data inline. If trace is local only, returns the local path.
+ * @summary Get workflow trace log data
+ */
+export type getWorkflowIdTraceLogResponse200 = {
+    data: GetWorkflowIdTraceLog200;
+    status: 200;
+};
+export type getWorkflowIdTraceLogResponse404 = {
+    data: GetWorkflowIdTraceLog404;
+    status: 404;
+};
+export type getWorkflowIdTraceLogResponse500 = {
+    data: GetWorkflowIdTraceLog500;
+    status: 500;
+};
+export type getWorkflowIdTraceLogResponseSuccess = (getWorkflowIdTraceLogResponse200) & {
+    headers: Headers;
+};
+export type getWorkflowIdTraceLogResponseError = (getWorkflowIdTraceLogResponse404 | getWorkflowIdTraceLogResponse500) & {
+    headers: Headers;
+};
+export type getWorkflowIdTraceLogResponse = (getWorkflowIdTraceLogResponseSuccess | getWorkflowIdTraceLogResponseError);
+export declare const getGetWorkflowIdTraceLogUrl: (id: string) => string;
+export declare const getWorkflowIdTraceLog: (id: string, options?: ApiRequestOptions) => Promise<getWorkflowIdTraceLogResponse>;
 /**
  * @summary Get a specific workflow catalog by ID
  */

package/dist/api/generated/api.js

@@ -7,6 +7,14 @@
  */
 import { customFetchInstance } from '../http_client.js';
 // eslint-disable-next-line @typescript-eslint/no-redeclare
+export const TraceLogRemoteResponseSource = {
+    remote: 'remote',
+};
+// eslint-disable-next-line @typescript-eslint/no-redeclare
+export const TraceLogLocalResponseSource = {
+    local: 'local',
+};
+// eslint-disable-next-line @typescript-eslint/no-redeclare
 export const WorkflowRunInfoStatus = {
     running: 'running',
     completed: 'completed',
@@ -88,6 +96,15 @@ export const getWorkflowIdResult = async (id, options) => {
         method: 'GET'
     });
 };
+export const getGetWorkflowIdTraceLogUrl = (id) => {
+    return `/workflow/${id}/trace-log`;
+};
+export const getWorkflowIdTraceLog = async (id, options) => {
+    return customFetchInstance(getGetWorkflowIdTraceLogUrl(id), {
+        ...options,
+        method: 'GET'
+    });
+};
 ;
 export const getGetWorkflowCatalogIdUrl = (id) => {
     return `/workflow/catalog/${id}`;

package/dist/api/http_client.js

@@ -9,8 +9,9 @@ const api = ky.create({
     retry: {
         limit: 2,
         methods: ['get', 'put', 'head', 'delete', 'options', 'trace'],
-        statusCodes: [408, 413, 429, 500, 502, 503, 504]
+        statusCodes: [408, 413, 429, 502, 503, 504]
     },
+    throwHttpErrors: false,
     hooks: {
         beforeRequest: [
             request => {

package/dist/assets/docker/docker-compose-dev.yml

@@ -82,11 +82,15 @@ services:
     image: growthxteam/output-api:latest
     networks:
       - main
+    env_file: ./.env
     environment:
       - PORT=3001
-      - CATALOG_ID=main
+      - CATALOG_ID=${CATALOG_ID:-main}
       - TEMPORAL_ADDRESS=temporal:7233
       - NODE_ENV=development
+      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID:-}
+      - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY:-}
+      - AWS_REGION=${AWS_REGION:-us-west-1}
     ports:
       - '3001:3001'
 
@@ -97,14 +101,19 @@ services:
     image: node:24.3-slim
     networks:
       - main
-    env_file: './.env'
+    env_file: ./.env
     environment:
-      - CATALOG_ID=main
-      - LOG_HTTP_VERBOSE=true
+      - CATALOG_ID=${CATALOG_ID:-main}
+      - LOG_HTTP_VERBOSE=${LOG_HTTP_VERBOSE:-true}
       - REDIS_URL=redis://redis:6379
       - TEMPORAL_ADDRESS=temporal:7233
-      - TRACE_LOCAL_ON=true
+      - TRACE_LOCAL_ON=${TRACE_LOCAL_ON:-true}
+      - TRACE_REMOTE_ON=${TRACE_REMOTE_ON:-}
+      - TRACE_REMOTE_S3_BUCKET=${TRACE_REMOTE_S3_BUCKET:-}
       - HOST_TRACE_PATH=${PWD}/logs
+      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID:-}
+      - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY:-}
+      - AWS_REGION=${AWS_REGION:-us-west-1}
     command: >
       sh -c "
         npm run output:worker:install &&

package/dist/commands/dev/index.js

@@ -1,6 +1,7 @@
 import { Command, Flags } from '@oclif/core';
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import logUpdate from 'log-update';
 import { validateDockerEnvironment, startDockerCompose, stopDockerCompose, getServiceStatus, DockerComposeConfigNotFoundError, getDefaultDockerComposePath, SERVICE_HEALTH, SERVICE_STATE } from '#services/docker.js';
 import { getErrorMessage } from '#utils/error_utils.js';
 import { getDevSuccessMessage } from '#services/messages.js';
@@ -109,7 +110,6 @@ export default class Dev extends Command {
         }
     }
     async pollServiceStatus(dockerComposePath) {
-        const state = { lastLineCount: 0 };
         const outputServiceStatus = async () => {
             try {
                 const services = await getServiceStatus(dockerComposePath);
@@ -122,11 +122,7 @@ export default class Dev extends Command {
                     '',
                     `${ANSI.DIM}Press Ctrl+C to stop services${ANSI.RESET}`
                 ];
-                if (state.lastLineCount > 0) {
-                    process.stdout.write(`\x1b[${state.lastLineCount}A\x1b[J`);
-                }
-                process.stdout.write(lines.join('\n') + '\n');
-                state.lastLineCount = lines.length;
+                logUpdate(lines.join('\n'));
             }
             catch {
                 // silent retry on next poll

package/dist/commands/workflow/debug.d.ts

@@ -9,6 +9,7 @@ export default class WorkflowDebug extends Command {
         format: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
+    private conditionalLog;
     private outputJson;
     private displayTextTrace;
     catch(error: Error): Promise<void>;

package/dist/commands/workflow/debug.js

@@ -27,18 +27,21 @@ export default class WorkflowDebug extends Command {
     async run() {
         const { args, flags } = await this.parse(WorkflowDebug);
         const isJsonFormat = flags.format === OUTPUT_FORMAT.JSON;
-        if (!isJsonFormat) {
-            this.log(`Fetching debug information for workflow: ${args.workflowId}...`);
-        }
-        const traceData = await getTrace(args.workflowId);
-        // Output based on format
+        this.conditionalLog(`Fetching debug information for workflow: ${args.workflowId}...`, isJsonFormat);
+        const { data: traceData, location } = await getTrace(args.workflowId);
+        const source = location.isRemote ? 'remote' : 'local';
+        this.conditionalLog(`Trace source: ${source}${!location.isRemote ? ` (${location.path})` : ''}`, isJsonFormat);
         if (isJsonFormat) {
             this.outputJson(traceData);
             return;
         }
-        // Display text format
         this.displayTextTrace(traceData);
     }
+    conditionalLog(message, disabled) {
+        if (!disabled) {
+            this.log(message);
+        }
+    }
     outputJson(data) {
         this.log(JSON.stringify(data, null, 2));
     }

package/dist/commands/workflow/debug.spec.js

@@ -1,8 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 // Mock the TraceReader service
 vi.mock('../../services/trace_reader.js', () => ({
-    findTraceFile: vi.fn(),
-    readTraceFile: vi.fn(),
     getTrace: vi.fn()
 }));
 // Mock the utilities

package/dist/services/docker.js

@@ -2,6 +2,7 @@ import { execFileSync, execSync, spawn } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { ux } from '@oclif/core';
+import logUpdate from 'log-update';
 const DEFAULT_COMPOSE_PATH = '../assets/docker/docker-compose-dev.yml';
 export const SERVICE_HEALTH = {
     HEALTHY: 'healthy',
@@ -108,16 +109,16 @@ export async function waitForServicesHealthy(dockerComposePath, timeoutMs = 1200
         const services = await getServiceStatus(dockerComposePath);
         const allHealthy = services.every(s => s.health === SERVICE_HEALTH.HEALTHY || s.health === SERVICE_HEALTH.NONE);
         if (services.length > 0) {
-            const lineCount = services.length + 1;
-            process.stdout.write(`\x1b[${lineCount}A\x1b[J`);
-            ux.stdout('⏳ Waiting for services to become healthy...\n');
-            ux.stdout(formatServiceStatus(services) + '\n');
+            const statusLines = formatServiceStatus(services);
+            logUpdate(`⏳ Waiting for services to become healthy...\n${statusLines}`);
         }
         if (allHealthy && services.length > 0) {
+            logUpdate.done();
             return;
         }
         await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
     }
+    logUpdate.done();
     throw new Error('Timeout waiting for services to become healthy');
 }
 export async function startDockerCompose(dockerComposePath, enableWatch = false) {

package/dist/services/docker.spec.js

@@ -6,6 +6,11 @@ vi.mock('node:child_process', () => ({
     execFileSync: vi.fn(),
     spawn: vi.fn()
 }));
+vi.mock('log-update', () => {
+    const fn = vi.fn();
+    fn.done = vi.fn();
+    return { default: fn };
+});
 describe('docker service', () => {
     beforeEach(() => {
         vi.clearAllMocks();

package/dist/services/messages.js

@@ -173,11 +173,11 @@ export const getProjectSuccessMessage = (folderName, installSuccess, envConfigur
     }
     steps.push({
         step: 'Start development services',
-        command: 'output dev',
+        command: 'npx output dev',
         note: 'Launches Temporal, Redis, PostgreSQL, API, Worker, and UI'
     }, {
         step: 'Run example workflow',
-        command: 'output workflow run simple --input src/simple/scenarios/question_ada_lovelace.json',
+        command: 'npx output workflow run simple --input src/simple/scenarios/question_ada_lovelace.json',
         note: 'Execute in a new terminal after services are running'
     }, {
         step: 'Monitor workflows',
@@ -219,14 +219,14 @@ ${divider}
 
 ${createSectionHeader('QUICK START COMMANDS', '⚡')}
 
-  ${bulletPoint} ${ux.colorize('white', 'Plan a workflow:')}     ${formatCommand('output workflow plan')}
-  ${bulletPoint} ${ux.colorize('white', 'Generate from plan:')} ${formatCommand('output workflow generate')}
-  ${bulletPoint} ${ux.colorize('white', 'List workflows:')}      ${formatCommand('output workflow list')}
-  ${bulletPoint} ${ux.colorize('white', 'View help:')}           ${formatCommand('output --help')}
+  ${bulletPoint} ${ux.colorize('white', 'Plan a workflow:')}     ${formatCommand('npx output workflow plan')}
+  ${bulletPoint} ${ux.colorize('white', 'Generate from plan:')} ${formatCommand('npx output workflow generate')}
+  ${bulletPoint} ${ux.colorize('white', 'List workflows:')}      ${formatCommand('npx output workflow list')}
+  ${bulletPoint} ${ux.colorize('white', 'View help:')}           ${formatCommand('npx output --help')}
 
 ${divider}
 
-${ux.colorize('dim', '💡 Tip: Use ')}${formatCommand('output workflow plan')}${ux.colorize('dim', ' to design your first custom workflow')}
+${ux.colorize('dim', '💡 Tip: Use ')}${formatCommand('npx output workflow plan')}${ux.colorize('dim', ' to design your first custom workflow')}
 ${ux.colorize('dim', '         with AI assistance.')}
 
 ${ux.colorize('green', ux.colorize('bold', 'Happy building with Output SDK! 🚀'))}
@@ -321,7 +321,7 @@ ${createSectionHeader('RUN A WORKFLOW', '🚀')}
 
   ${ux.colorize('white', 'In a new terminal, execute:')}
 
-    ${formatCommand('output workflow run simple --input \'{"question": "Hello!"}\'')}
+    ${formatCommand('npx output workflow run simple --input \'{"question": "Hello!"}\'')}
 
 ${divider}
 

package/dist/services/trace_reader.d.ts

@@ -1,14 +1,16 @@
 import type { TraceData } from '#types/trace.js';
 export type { TraceData };
+export interface TraceLocation {
+    path: string;
+    isRemote: boolean;
+}
+export interface TraceResult {
+    data: TraceData;
+    location: TraceLocation;
+}
 /**
- * Find trace file from workflow metadata
+ * Get trace data from workflow ID using the API
+ * The API handles S3 fetching - CLI only needs to read local files when necessary
+ * @returns Both the trace data and the location it was fetched from
  */
-export declare function findTraceFile(workflowId: string): Promise<string>;
-/**
- * Read and parse trace file
- */
-export declare function readTraceFile(path: string): Promise<TraceData>;
-/**
- * Get trace data from workflow ID
- */
-export declare function getTrace(workflowId: string): Promise<TraceData>;
+export declare function getTrace(workflowId: string): Promise<TraceResult>;

package/dist/services/trace_reader.js

@@ -1,49 +1,10 @@
-import { readFile, stat } from 'node:fs/promises';
-import { getWorkflowIdResult } from '#api/generated/api.js';
+import { readFile } from 'node:fs/promises';
+import { getWorkflowIdTraceLog } from '#api/generated/api.js';
 import { getErrorCode } from '#utils/error_utils.js';
 /**
- * Check if a file exists with detailed error information
+ * Read and parse trace file from local path
  */
-async function fileExists(path) {
-    try {
-        await stat(path);
-        return { exists: true };
-    }
-    catch (error) {
-        const code = getErrorCode(error);
-        if (code === 'ENOENT') {
-            return { exists: false };
-        }
-        if (code === 'EACCES') {
-            return { exists: false, error: `Permission denied: ${path}` };
-        }
-        return { exists: false, error: `Cannot access file: ${path}` };
-    }
-}
-/**
- * Find trace file from workflow metadata
- */
-export async function findTraceFile(workflowId) {
-    const response = await getWorkflowIdResult(workflowId);
-    // Check if we got a successful response
-    if (response.status !== 200) {
-        throw new Error(`Failed to get workflow result for ${workflowId}`);
-    }
-    const tracePath = response.data.trace?.destinations?.local;
-    if (!tracePath) {
-        throw new Error(`No trace file path found for workflow ${workflowId}`);
-    }
-    const fileCheck = await fileExists(tracePath);
-    if (!fileCheck.exists) {
-        const errorDetail = fileCheck.error || `Trace file not found at path: ${tracePath}`;
-        throw new Error(errorDetail);
-    }
-    return tracePath;
-}
-/**
- * Read and parse trace file
- */
-export async function readTraceFile(path) {
+async function readLocalTraceFile(path) {
     try {
         const content = await readFile(path, 'utf-8');
         return JSON.parse(content);
@@ -59,9 +20,38 @@ export async function readTraceFile(path) {
     }
 }
 /**
- * Get trace data from workflow ID
+ * Get trace data from workflow ID using the API
+ * The API handles S3 fetching - CLI only needs to read local files when necessary
+ * @returns Both the trace data and the location it was fetched from
  */
 export async function getTrace(workflowId) {
-    const tracePath = await findTraceFile(workflowId);
-    return readTraceFile(tracePath);
+    const response = await getWorkflowIdTraceLog(workflowId);
+    if (response.status === 404) {
+        throw new Error(`Workflow not found or no trace available: ${workflowId}`);
+    }
+    if (response.status === 500) {
+        const errorData = response.data;
+        const errorMessage = errorData?.error || 'Failed to fetch trace from API';
+        throw new Error(`API error (500): ${errorMessage}`);
+    }
+    if (response.status !== 200) {
+        const errorResponse = response;
+        throw new Error(`Unexpected API response status: ${errorResponse.status}`);
+    }
+    const data = response.data;
+    if (data.source === 'remote') {
+        return {
+            data: data.data,
+            location: { path: 'remote', isRemote: true }
+        };
+    }
+    if (data.source === 'local') {
+        const localPath = data.localPath;
+        const traceData = await readLocalTraceFile(localPath);
+        return {
+            data: traceData,
+            location: { path: localPath, isRemote: false }
+        };
+    }
+    throw new Error('Invalid trace log response format');
 }

package/dist/services/trace_reader.spec.js

@@ -1,164 +1,78 @@
-import { describe, it, expect, vi, afterEach } from 'vitest';
-import { findTraceFile, readTraceFile } from './trace_reader.js';
-// Mock file system operations
-vi.mock('node:fs/promises', () => ({
-    readFile: vi.fn(),
-    stat: vi.fn()
+import { describe, it, expect, vi, afterEach, beforeEach } from 'vitest';
+const mockGetWorkflowIdTraceLog = vi.fn();
+vi.mock('#api/generated/api.js', () => ({
+    getWorkflowIdTraceLog: (...args) => mockGetWorkflowIdTraceLog(...args)
 }));
-// Mock API
-vi.mock('../api/generated/api.js', () => ({
-    getWorkflowIdResult: vi.fn()
+const mockReadFile = vi.fn();
+vi.mock('node:fs/promises', () => ({
+    readFile: (...args) => mockReadFile(...args)
 }));
-describe('TraceReader', () => {
-    const getMocks = async () => {
-        const fsModule = await import('node:fs/promises');
-        const apiModule = await import('../api/generated/api.js');
-        return {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            mockReadFile: fsModule.readFile,
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            mockStat: fsModule.stat,
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            mockGetWorkflowIdResult: apiModule.getWorkflowIdResult
-        };
-    };
+describe('trace_reader', () => {
+    beforeEach(() => {
+        mockGetWorkflowIdTraceLog.mockReset();
+        mockReadFile.mockReset();
+    });
     afterEach(() => {
         vi.clearAllMocks();
     });
-    describe('findTraceFile', () => {
-        it('should find trace file from workflow output metadata', async () => {
-            const { mockGetWorkflowIdResult, mockStat } = await getMocks();
-            const workflowId = 'test-workflow-123';
-            const expectedPath = '/app/logs/runs/test/2024-01-01_test-workflow-123.json';
-            mockGetWorkflowIdResult.mockResolvedValue({
-                status: 200,
-                data: {
-                    workflowId,
-                    output: { result: 'test result' },
-                    trace: {
-                        destinations: {
-                            local: expectedPath,
-                            remote: null
-                        }
-                    }
-                }
-            });
-            mockStat.mockResolvedValue({ isFile: () => true });
-            const result = await findTraceFile(workflowId);
-            expect(result).toBe(expectedPath);
-            expect(mockGetWorkflowIdResult).toHaveBeenCalledWith(workflowId);
-            expect(mockStat).toHaveBeenCalledWith(expectedPath);
-        });
-        it('should throw error when no trace path in metadata', async () => {
-            const { mockGetWorkflowIdResult } = await getMocks();
-            const workflowId = 'test-workflow-456';
-            mockGetWorkflowIdResult.mockResolvedValue({
-                status: 200,
-                data: {
-                    workflowId,
-                    output: { result: 'test result' },
-                    trace: {
-                        destinations: {
-                            local: null,
-                            remote: null
-                        }
-                    }
-                }
-            });
-            await expect(findTraceFile(workflowId))
-                .rejects.toThrow(`No trace file path found for workflow ${workflowId}`);
-        });
-        it('should throw error when trace file not on disk', async () => {
-            const { mockGetWorkflowIdResult, mockStat } = await getMocks();
-            const workflowId = 'test-workflow-789';
-            const expectedPath = '/app/logs/runs/test/2024-01-01_test-workflow-789.json';
-            mockGetWorkflowIdResult.mockResolvedValue({
+    describe('getTrace', () => {
+        it('should return trace data directly for remote source', async () => {
+            const mockTraceData = {
+                root: { workflowName: 'test', workflowId: 'wf-123', startTime: Date.now() },
+                children: []
+            };
+            mockGetWorkflowIdTraceLog.mockResolvedValue({
                 status: 200,
                 data: {
-                    workflowId,
-                    output: { result: 'test result' },
-                    trace: {
-                        destinations: {
-                            local: expectedPath,
-                            remote: null
-                        }
-                    }
+                    source: 'remote',
+                    data: mockTraceData
                 }
             });
-            const enoentError = Object.assign(new Error('ENOENT: no such file or directory'), { code: 'ENOENT' });
-            mockStat.mockRejectedValue(enoentError);
-            await expect(findTraceFile(workflowId))
-                .rejects.toThrow(`Trace file not found at path: ${expectedPath}`);
+            const { getTrace } = await import('./trace_reader.js');
+            const result = await getTrace('wf-123');
+            expect(result.data).toEqual(mockTraceData);
+            expect(result.location.isRemote).toBe(true);
+            expect(mockReadFile).not.toHaveBeenCalled();
         });
-        it('should throw error when API call fails', async () => {
-            const { mockGetWorkflowIdResult } = await getMocks();
-            const workflowId = 'non-existent';
-            mockGetWorkflowIdResult.mockRejectedValue(new Error('Workflow not found'));
-            await expect(findTraceFile(workflowId))
-                .rejects.toThrow('Workflow not found');
-        });
-        it('should handle missing trace property gracefully', async () => {
-            const { mockGetWorkflowIdResult } = await getMocks();
-            const workflowId = 'test-workflow-no-trace';
-            mockGetWorkflowIdResult.mockResolvedValue({
+        it('should read local file for local source', async () => {
+            const mockTraceData = {
+                root: { workflowName: 'test', workflowId: 'wf-123', startTime: Date.now() },
+                children: []
+            };
+            mockGetWorkflowIdTraceLog.mockResolvedValue({
                 status: 200,
                 data: {
-                    workflowId,
-                    output: { result: 'test result' }
-                    // No trace property at all
+                    source: 'local',
+                    localPath: '/path/to/trace.json'
                 }
             });
-            await expect(findTraceFile(workflowId))
-                .rejects.toThrow(`No trace file path found for workflow ${workflowId}`);
+            mockReadFile.mockResolvedValue(JSON.stringify(mockTraceData));
+            const { getTrace } = await import('./trace_reader.js');
+            const result = await getTrace('wf-123');
+            expect(result.data).toEqual(mockTraceData);
+            expect(result.location.isRemote).toBe(false);
+            expect(result.location.path).toBe('/path/to/trace.json');
+            expect(mockReadFile).toHaveBeenCalledWith('/path/to/trace.json', 'utf-8');
         });
-        it('should throw error when workflow not found (404)', async () => {
-            const { mockGetWorkflowIdResult } = await getMocks();
-            const workflowId = 'non-existent-workflow';
-            mockGetWorkflowIdResult.mockResolvedValue({
+        it('should throw error when API returns 404', async () => {
+            mockGetWorkflowIdTraceLog.mockResolvedValue({
                 status: 404,
-                data: void 0
+                data: { error: 'Not found' }
             });
-            await expect(findTraceFile(workflowId))
-                .rejects.toThrow(`Failed to get workflow result for ${workflowId}`);
+            const { getTrace } = await import('./trace_reader.js');
+            await expect(getTrace('wf-123'))
+                .rejects
+                .toThrow('Workflow not found or no trace available: wf-123');
         });
-    });
-    describe('readTraceFile', () => {
-        it('should read and parse JSON file successfully', async () => {
-            const { mockReadFile } = await getMocks();
-            const path = '/logs/test.json';
-            const traceData = {
-                root: { workflowName: 'test' },
-                events: []
-            };
-            mockReadFile.mockResolvedValue(JSON.stringify(traceData));
-            const result = await readTraceFile(path);
-            expect(result).toEqual(traceData);
-            expect(mockReadFile).toHaveBeenCalledWith(path, 'utf-8');
-        });
-        it('should throw error for non-existent file', async () => {
-            const { mockReadFile } = await getMocks();
-            const path = '/logs/missing.json';
-            const error = new Error('ENOENT');
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            error.code = 'ENOENT';
-            mockReadFile.mockRejectedValue(error);
-            await expect(readTraceFile(path))
-                .rejects.toThrow(`Trace file not found at path: ${path}`);
-        });
-        it('should throw error for invalid JSON', async () => {
-            const { mockReadFile } = await getMocks();
-            const path = '/logs/invalid.json';
-            mockReadFile.mockResolvedValue('invalid json {');
-            await expect(readTraceFile(path))
-                .rejects.toThrow(`Invalid JSON in trace file: ${path}`);
-        });
-        it('should rethrow other errors', async () => {
-            const { mockReadFile } = await getMocks();
-            const path = '/logs/test.json';
-            const error = new Error('Permission denied');
-            mockReadFile.mockRejectedValue(error);
-            await expect(readTraceFile(path))
-                .rejects.toThrow('Permission denied');
+        it('should throw error when API returns 500', async () => {
+            mockGetWorkflowIdTraceLog.mockResolvedValue({
+                status: 500,
+                data: { error: 'S3 access denied' }
+            });
+            const { getTrace } = await import('./trace_reader.js');
+            await expect(getTrace('wf-123'))
+                .rejects
+                .toThrow('S3 access denied');
         });
     });
 });

package/dist/utils/env_loader.d.ts

@@ -1,6 +1 @@
-/**
- * Load environment variables from .env files in the current working directory
- * Loads in order: .env, then .env.local (if exists)
- * .env.local overrides values from .env
- */
 export declare function loadEnvironment(): void;

package/dist/utils/env_loader.js

@@ -1,43 +1,19 @@
 /**
  * Environment loader utility
- * Loads .env files from the current working directory
+ * Loads .env file from the current working directory
+ * Set OUTPUT_CLI_ENV to specify a custom env file path
  */
-import * as fs from 'node:fs';
-import * as path from 'node:path';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
 import * as dotenv from 'dotenv';
-/**
- * Load environment variables from .env files in the current working directory
- * Loads in order: .env, then .env.local (if exists)
- * .env.local overrides values from .env
- */
 export function loadEnvironment() {
     const cwd = process.cwd();
-    // Load .env file
-    const envPath = path.join(cwd, '.env');
-    if (fs.existsSync(envPath)) {
-        try {
-            const result = dotenv.config({ path: envPath });
-            if (result.error) {
-                // Log warning but don't fail - malformed .env shouldn't break the CLI
-                console.warn(`Warning: Error parsing .env file: ${result.error.message}`);
-            }
-        }
-        catch (error) {
-            // Silent failure - .env loading is optional
-            console.warn(`Warning: Could not load .env file: ${error}`);
-        }
-    }
-    // Load .env.local file (overrides .env)
-    const envLocalPath = path.join(cwd, '.env.local');
-    if (fs.existsSync(envLocalPath)) {
-        try {
-            const result = dotenv.config({ path: envLocalPath });
-            if (result.error) {
-                console.warn(`Warning: Error parsing .env.local file: ${result.error.message}`);
-            }
-        }
-        catch (error) {
-            console.warn(`Warning: Could not load .env.local file: ${error}`);
-        }
+    const envFile = process.env.OUTPUT_CLI_ENV || '.env';
+    const envPath = resolve(cwd, envFile);
+    if (!existsSync(envPath)) {
+        console.warn(`Warning: Env file not found: ${envPath}`);
+        return;
     }
+    console.log(`Loading env from: ${envPath}`);
+    dotenv.config({ path: envPath });
 }

package/dist/utils/env_loader.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/env_loader.spec.js

@@ -0,0 +1,63 @@
+/**
+ * Tests for the env loader utility
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import * as dotenv from 'dotenv';
+vi.mock('node:fs');
+vi.mock('dotenv');
+describe('loadEnvironment', () => {
+    const originalEnv = { ...process.env };
+    const mockCwd = '/mock/project';
+    beforeEach(() => {
+        vi.resetModules();
+        vi.clearAllMocks();
+        vi.spyOn(process, 'cwd').mockReturnValue(mockCwd);
+        vi.spyOn(console, 'log').mockImplementation(() => { });
+        vi.spyOn(console, 'warn').mockImplementation(() => { });
+    });
+    afterEach(() => {
+        process.env = { ...originalEnv };
+        vi.restoreAllMocks();
+    });
+    it('should load from OUTPUT_CLI_ENV when set and file exists', async () => {
+        process.env.OUTPUT_CLI_ENV = '.env.prod';
+        const expectedPath = resolve(mockCwd, '.env.prod');
+        vi.mocked(existsSync).mockReturnValue(true);
+        vi.mocked(dotenv.config).mockReturnValue({ parsed: { API_URL: 'https://prod.api.com' } });
+        const { loadEnvironment } = await import('./env_loader.js');
+        loadEnvironment();
+        expect(console.log).toHaveBeenCalledWith(`Loading env from: ${expectedPath}`);
+        expect(dotenv.config).toHaveBeenCalledWith({ path: expectedPath });
+    });
+    it('should warn when OUTPUT_CLI_ENV file does not exist', async () => {
+        process.env.OUTPUT_CLI_ENV = '.env.missing';
+        const expectedPath = resolve(mockCwd, '.env.missing');
+        vi.mocked(existsSync).mockReturnValue(false);
+        const { loadEnvironment } = await import('./env_loader.js');
+        loadEnvironment();
+        expect(console.warn).toHaveBeenCalledWith(`Warning: Env file not found: ${expectedPath}`);
+        expect(dotenv.config).not.toHaveBeenCalled();
+    });
+    it('should load .env by default and log', async () => {
+        delete process.env.OUTPUT_CLI_ENV;
+        const envPath = resolve(mockCwd, '.env');
+        vi.mocked(existsSync).mockImplementation(p => p === envPath);
+        vi.mocked(dotenv.config).mockReturnValue({ parsed: {} });
+        const { loadEnvironment } = await import('./env_loader.js');
+        loadEnvironment();
+        expect(console.log).toHaveBeenCalledWith(`Loading env from: ${envPath}`);
+        expect(dotenv.config).toHaveBeenCalledTimes(1);
+        expect(dotenv.config).toHaveBeenCalledWith({ path: envPath });
+    });
+    it('should warn when default .env does not exist', async () => {
+        delete process.env.OUTPUT_CLI_ENV;
+        const envPath = resolve(mockCwd, '.env');
+        vi.mocked(existsSync).mockReturnValue(false);
+        const { loadEnvironment } = await import('./env_loader.js');
+        loadEnvironment();
+        expect(console.warn).toHaveBeenCalledWith(`Warning: Env file not found: ${envPath}`);
+        expect(dotenv.config).not.toHaveBeenCalled();
+    });
+});

package/dist/utils/error_handler.js

@@ -5,21 +5,45 @@ const DEFAULT_MESSAGES = {
     404: 'Resource not found.',
     UNKNOWN: 'An unknown error occurred.'
 };
+/**
+ * Extract detailed error information from fetch errors and their causes
+ */
+function getDetailedErrorMessage(error) {
+    const apiError = error;
+    const parts = [];
+    if (apiError.message) {
+        parts.push(apiError.message);
+    }
+    if (apiError.cause) {
+        const cause = apiError.cause;
+        if (cause.message && cause.message !== apiError.message) {
+            parts.push(`Cause: ${cause.message}`);
+        }
+        if (cause.code) {
+            parts.push(`Code: ${cause.code}`);
+        }
+        if (cause.hostname) {
+            parts.push(`Host: ${cause.hostname}${cause.port ? ':' + cause.port : ''}`);
+        }
+    }
+    if (apiError.response?.status) {
+        parts.push(`HTTP Status: ${apiError.response.status}`);
+    }
+    return parts.length > 0 ? parts.join(' | ') : 'Unknown error';
+}
 export function handleApiError(error, errorFn, overrides = {}) {
     const apiError = error;
     const errorMessages = { ...DEFAULT_MESSAGES, ...overrides };
-    if (apiError.code === 'ECONNREFUSED') {
-        return errorFn(errorMessages.ECONNREFUSED, { exit: 1 });
+    if (apiError.code === 'ECONNREFUSED' || apiError.cause?.code === 'ECONNREFUSED') {
+        errorFn(errorMessages.ECONNREFUSED, { exit: 1 });
     }
     if (apiError.response?.status) {
         const status = apiError.response.status;
         const message = errorMessages[status];
         if (message) {
-            return errorFn(message, { exit: 1 });
+            errorFn(message, { exit: 1 });
         }
     }
-    if (apiError.message) {
-        return errorFn(apiError.message, { exit: 1 });
-    }
-    return errorFn(errorMessages.UNKNOWN, { exit: 1 });
+    const detailedMessage = getDetailedErrorMessage(error);
+    errorFn(detailedMessage, { exit: 1 });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@output.ai/cli",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "CLI for Output.ai workflow generation",
   "type": "module",
   "main": "dist/index.js",
@@ -35,6 +35,7 @@
     "handlebars": "4.7.8",
     "json-schema-library": "10.3.0",
     "ky": "1.12.0",
+    "log-update": "7.0.2",
     "validator": "13.15.22"
   },
   "devDependencies": {