@papercraneai/cli 1.1.0 → 1.3.0

package/bin/papercrane.js

@@ -3,68 +3,121 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
 import readline from 'readline';
-import { setApiKey, clearConfig, isLoggedIn } from '../lib/config.js';
+import fs from 'fs/promises';
+import { setApiKey, clearConfig, isLoggedIn, setDefaultWorkspace, getDefaultWorkspace } from '../lib/config.js';
 import { validateApiKey } from '../lib/cloud-client.js';
 import { listFunctions, getFunction, runFunction, formatDescribe, formatDescribeRoot, formatFlat, formatResult, formatUnconnected } from '../lib/function-client.js';
+import { listWorkspaces, resolveWorkspaceId, getFileTree, readFile, writeFile, editFile, deleteFile, getLocalWorkspacePath, pullWorkspace, pushWorkspace } from '../lib/environment-client.js';
 
 const program = new Command();
 
 program
   .name('papercrane')
-  .description('CLI for discovering and calling endpoints.\n\nRun "papercrane" with no arguments to list connected modules and endpoints.')
+  .description('CLI for discovering APIs and building dashboards in cloud workspaces.\n\nRun "papercrane" with no arguments to list connected modules and endpoints.')
   .version('1.0.0');
 
 program
   .command('login')
-  .description('Login to cloud credential storage with API key')
-  .option('--api-key <key>', 'API key for cloud storage')
-  .option('--url <url>', 'API base URL (default: https://fly.papercrane.ai)')
+  .description('Login to Papercrane. Opens browser for authentication, or use --api-key for direct login.')
+  .option('--api-key <key>', 'API key for direct login (skips browser)')
+  .option('--url <url>', 'API base URL (saves to config)')
   .action(async (options) => {
     try {
-      let apiKey = options.apiKey;
+      const { getApiBaseUrl, setApiBaseUrl } = await import('../lib/config.js');
 
-      // If no API key provided via option, prompt for it
-      if (!apiKey) {
-        const rl = readline.createInterface({
-          input: process.stdin,
-          output: process.stdout
-        });
+      // Resolve API base URL: --url flag > config > default
+      let baseUrl;
+      if (options.url) {
+        baseUrl = options.url.replace(/\/+$/, ''); // Strip trailing slash
+        await setApiBaseUrl(baseUrl);
+        console.log(chalk.dim(`Using API URL: ${baseUrl}`));
+      } else {
+        baseUrl = await getApiBaseUrl();
+      }
+
+      // If --api-key provided, use direct login flow
+      if (options.apiKey) {
+        await setApiKey(options.apiKey);
 
-        apiKey = await new Promise((resolve) => {
-          rl.question(chalk.cyan('Enter your API key: '), (answer) => {
-            rl.close();
-            resolve(answer.trim());
-          });
-        });
+        console.log(chalk.cyan('Validating API key...'));
+        const isValid = await validateApiKey();
+
+        if (isValid) {
+          console.log(chalk.green('✓ Successfully logged in\n'));
+        } else {
+          console.log(chalk.yellow('⚠️  API key saved, but validation failed.'));
+          console.log(chalk.yellow('   The key may be invalid or the service may be unavailable.\n'));
+        }
+        return;
       }
 
-      if (!apiKey) {
-        console.error(chalk.red('Error: API key is required'));
-        process.exit(1);
+      // Browser-based login flow (polling)
+      const { generateState } = await import('../lib/auth-server.js');
+      const open = (await import('open')).default;
+
+      const session = generateState();
+
+      // Initialize session on server
+      const initRes = await fetch(`${baseUrl}/api/cli-auth/init`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ session })
+      });
+
+      if (!initRes.ok) {
+        throw new Error('Failed to initialize login session');
       }
 
-      // Save the API key
-      await setApiKey(apiKey);
+      const authUrl = `${baseUrl}/cli-auth?session=${session}`;
 
-      // Save custom URL if provided
-      if (options.url) {
-        const { setApiBaseUrl } = await import('../lib/config.js');
-        await setApiBaseUrl(options.url);
-        console.log(chalk.dim(`Using API URL: ${options.url}`));
+      console.log(chalk.cyan('\nOpen this URL to authenticate:\n'));
+      console.log(`  ${authUrl}\n`);
+
+      // Try to open browser automatically
+      try {
+        await open(authUrl);
+        console.log(chalk.dim('(Browser opened automatically)'));
+      } catch {
+        console.log(chalk.yellow('Could not open browser automatically. Please click or copy the URL above.'));
       }
 
-      // Validate it
-      console.log(chalk.cyan('\nValidating API key...'));
-      const isValid = await validateApiKey();
+      console.log(chalk.dim('\nWaiting for authorization... (press Ctrl+C to cancel)\n'));
 
-      if (isValid) {
-        console.log(chalk.green('✓ Successfully logged in to cloud credential storage\n'));
-      } else {
-        console.log(chalk.yellow('⚠️  API key saved, but validation failed.'));
-        console.log(chalk.yellow('   The key may be invalid or the service may be unavailable.\n'));
+      // Poll for authorization
+      const pollInterval = 2000; // 2 seconds
+      const timeout = 120000; // 2 minutes
+      const startTime = Date.now();
+
+      while (Date.now() - startTime < timeout) {
+        const statusRes = await fetch(`${baseUrl}/api/cli-auth/status?session=${encodeURIComponent(session)}`);
+
+        if (statusRes.ok) {
+          const data = await statusRes.json();
+
+          if (data.status === 'authorized') {
+            // Save the API key
+            await setApiKey(data.key);
+            await setApiBaseUrl(baseUrl);
+
+            console.log(chalk.green(`✓ Logged in as ${data.email}`));
+            console.log(chalk.dim(`  API key saved to ~/.papercrane/config.json\n`));
+            return;
+          }
+        } else if (statusRes.status === 404) {
+          throw new Error('Session expired. Please try again.');
+        }
+
+        // Wait before next poll
+        await new Promise(resolve => setTimeout(resolve, pollInterval));
       }
+
+      throw new Error('Authentication timed out');
     } catch (error) {
-      console.error(chalk.red('Error:'), error.message);
+      if (error.message.includes('timed out')) {
+        console.error(chalk.red('\nAuthentication timed out. Please try again.'));
+      } else {
+        console.error(chalk.red('Error:'), error.message);
+      }
       process.exit(1);
     }
   });
@@ -189,6 +242,517 @@ program
     }
   });
 
+// ============================================================================
+// DASHBOARD GUIDE COMMAND
+// ============================================================================
+
+program
+  .command('dashboard-guide')
+  .description('Show how to build dashboards in cloud workspaces')
+  .action(async () => {
+    console.log(chalk.bold('\n📊 Building Dashboards in Papercrane Workspaces\n'));
+    console.log(chalk.dim('Workspaces are Next.js environments. Files you write become live routes.\n'));
+
+    console.log(chalk.bold('FILE STRUCTURE'));
+    console.log(chalk.dim('─'.repeat(60)));
+    console.log(`
+Create two files for each dashboard page:
+
+  app/(dashboard)/my-dashboard/
+  ├── action.ts    # Server-side data fetching
+  └── page.tsx     # Client component with charts
+`);
+
+    console.log(chalk.bold('1. action.ts - Server Action Pattern'));
+    console.log(chalk.dim('─'.repeat(60)));
+    console.log(`
+${chalk.cyan(`'use server'
+
+import { authFetch } from '@/lib/papercrane'
+
+export async function getData() {
+  // authFetch takes function path (dots, not slashes) and flat params
+  // Returns parsed result directly - no .json() needed
+  const result = await authFetch('integration.endpoint', { limit: 100 })
+  return result
+
+  // Example with Google Analytics:
+  // return authFetch('google-analytics.data.runReport', {
+  //   property: '12345',
+  //   startDate: '30daysAgo',
+  //   endDate: 'today',
+  //   metrics: ['activeUsers', 'sessions'],
+  //   dimensions: ['date']
+  // })
+}`)}
+`);
+
+    console.log(chalk.bold('2. page.tsx - Client Component Pattern'));
+    console.log(chalk.dim('─'.repeat(60)));
+    console.log(`
+${chalk.cyan(`'use client'
+
+import { useEffect, useState } from 'react'
+import * as actions from './action'
+import { Card, CardHeader, CardTitle, CardContent } from '@/components/ui/card'
+import { ChartContainer, ChartTooltip, ChartTooltipContent, type ChartConfig } from '@/components/ui/chart'
+import { BarChart, Bar, XAxis, YAxis } from 'recharts'
+
+// Use semantic chart colors: var(--chart-1) through var(--chart-5)
+const chartConfig = {
+  value: { label: 'Value', color: 'var(--chart-1)' },
+} satisfies ChartConfig
+
+export default function MyDashboard() {
+  const [data, setData] = useState<any[]>([])
+  const [loading, setLoading] = useState(true)
+
+  useEffect(() => {
+    actions.getData()
+      .then(setData)
+      .finally(() => setLoading(false))
+  }, [])
+
+  if (loading) return <div className="p-8 bg-background text-foreground">Loading...</div>
+
+  return (
+    <div className="min-h-screen p-6 bg-background text-foreground">
+      <h1 className="text-2xl font-bold mb-6">My Dashboard</h1>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Chart Title</CardTitle>
+        </CardHeader>
+        <CardContent>
+          <ChartContainer config={chartConfig} className="h-[300px] w-full">
+            <BarChart data={data}>
+              <XAxis dataKey="name" stroke="var(--muted-foreground)" />
+              <YAxis stroke="var(--muted-foreground)" />
+              <ChartTooltip content={<ChartTooltipContent />} />
+              <Bar dataKey="value" fill="var(--color-value)" />
+            </BarChart>
+          </ChartContainer>
+        </CardContent>
+      </Card>
+    </div>
+  )
+}`)}
+`);
+
+    console.log(chalk.bold('SEMANTIC COLOR CLASSES'));
+    console.log(chalk.dim('─'.repeat(60)));
+    console.log(`
+Use these Tailwind classes for theme-aware colors:
+
+  ${chalk.green('Backgrounds:')}   bg-background, bg-card, bg-muted, bg-primary, bg-secondary
+  ${chalk.green('Text:')}          text-foreground, text-muted-foreground, text-primary, text-secondary
+  ${chalk.green('Borders:')}       border-border, border-input
+  ${chalk.green('Charts:')}        var(--chart-1) through var(--chart-5) in ChartConfig
+  ${chalk.green('Axis/Labels:')}   var(--muted-foreground) for XAxis/YAxis stroke
+`);
+
+    console.log(chalk.bold('AVAILABLE COMPONENTS'));
+    console.log(chalk.dim('─'.repeat(60)));
+    console.log(`
+  ${chalk.green('UI Components:')}
+    Card, CardHeader, CardTitle, CardContent, CardDescription
+    Button, Input, Select, Table, Badge, Tabs
+
+  ${chalk.green('Chart Components:')}
+    ChartContainer, ChartTooltip, ChartTooltipContent (from @/components/ui/chart)
+    BarChart, LineChart, AreaChart, PieChart (from recharts)
+    XAxis, YAxis, Bar, Line, Area, Pie, Cell
+`);
+
+    console.log(chalk.bold('QUICK START'));
+    console.log(chalk.dim('─'.repeat(60)));
+    console.log(`
+  1. ${chalk.cyan('papercrane')}                    # List available integrations
+  2. ${chalk.cyan('papercrane describe <path>')}    # Explore endpoints
+  3. ${chalk.cyan('papercrane call <path> \'{}\'')}  # Test data fetching
+  4. ${chalk.cyan('papercrane pull')}               # Pull workspace files locally
+  5. Edit files in ${chalk.cyan('~/.papercrane/workspaces/<id>/')}
+  6. ${chalk.cyan('papercrane push')}               # Push changes back
+
+  ${chalk.dim('The pull/push workflow is recommended - edit files locally, then sync.')}
+  ${chalk.dim('For single files, you can also use: papercrane files write <path> --json "..."')}
+`);
+    console.log();
+  });
+
+// ============================================================================
+// WORKSPACE COMMANDS
+// ============================================================================
+
+const workspacesCmd = program.command('workspaces').description('Manage workspaces');
+
+workspacesCmd
+  .command('list')
+  .description('List all workspaces')
+  .action(async () => {
+    try {
+      const loggedIn = await isLoggedIn();
+      if (!loggedIn) {
+        console.error(chalk.red('Error: Not logged in. Run: papercrane login'));
+        process.exit(1);
+      }
+
+      const workspaces = await listWorkspaces();
+      const defaultWs = await getDefaultWorkspace();
+
+      if (!workspaces || workspaces.length === 0) {
+        console.log(chalk.yellow('No workspaces found.'));
+        return;
+      }
+
+      console.log(chalk.bold('\nWorkspaces:\n'));
+      for (const ws of workspaces) {
+        const isDefault = ws.id === defaultWs;
+        const status = ws.status === 'ready' ? chalk.green('ready') : chalk.yellow(ws.status);
+        const defaultMarker = isDefault ? chalk.cyan(' (default)') : '';
+        const typeLabel = ws.type === 'external' ? chalk.dim('external') : chalk.dim('managed');
+        const createdDate = ws.createdAt ? new Date(ws.createdAt).toLocaleDateString() : '';
+        console.log(`  ${chalk.bold(ws.id)}  ${ws.name || '(unnamed)'}  ${typeLabel}  ${status}  ${chalk.dim(createdDate)}${defaultMarker}`);
+      }
+      console.log();
+    } catch (error) {
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+workspacesCmd
+  .command('use <id>')
+  .description('Set the default workspace')
+  .action(async (id) => {
+    try {
+      const loggedIn = await isLoggedIn();
+      if (!loggedIn) {
+        console.error(chalk.red('Error: Not logged in. Run: papercrane login'));
+        process.exit(1);
+      }
+
+      const wsId = parseInt(id, 10);
+      if (isNaN(wsId)) {
+        console.error(chalk.red('Error: Invalid workspace ID'));
+        process.exit(1);
+      }
+
+      await setDefaultWorkspace(wsId);
+      console.log(chalk.green(`✓ Default workspace set to ${wsId}\n`));
+    } catch (error) {
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// FILE COMMANDS
+// ============================================================================
+
+const filesCmd = program.command('files').description('Build dashboards by reading/writing files in cloud workspaces.\n\nWorkspaces are Next.js environments - files you write become live routes.\nRun "papercrane dashboard-guide" for the recommended dashboard pattern.');
+
+filesCmd
+  .command('list [path]')
+  .description('List files in a workspace')
+  .option('-w, --workspace <id>', 'Workspace ID (uses default if not specified)')
+  .action(async (path, options) => {
+    try {
+      const loggedIn = await isLoggedIn();
+      if (!loggedIn) {
+        console.error(chalk.red('Error: Not logged in. Run: papercrane login'));
+        process.exit(1);
+      }
+
+      const wsId = await resolveWorkspaceId(options.workspace);
+      const result = await getFileTree(wsId, path || '');
+
+      console.log(chalk.bold(`\nFiles in workspace ${wsId}${path ? ` (${path})` : ''}:\n`));
+      printFileTree(result.tree, '  ');
+      console.log();
+    } catch (error) {
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+filesCmd
+  .command('read <path>')
+  .description('Read file contents')
+  .option('-w, --workspace <id>', 'Workspace ID (uses default if not specified)')
+  .option('--raw', 'Output raw content without formatting')
+  .action(async (path, options) => {
+    try {
+      const loggedIn = await isLoggedIn();
+      if (!loggedIn) {
+        console.error(chalk.red('Error: Not logged in. Run: papercrane login'));
+        process.exit(1);
+      }
+
+      const wsId = await resolveWorkspaceId(options.workspace);
+      const result = await readFile(wsId, path);
+
+      if (options.raw) {
+        process.stdout.write(result.content);
+      } else {
+        console.log(chalk.dim(`# ${result.path} (${result.size} bytes)\n`));
+        console.log(result.content);
+      }
+    } catch (error) {
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+filesCmd
+  .command('write <path> [content]')
+  .description('Write content to a file. Use --json for reliable escaping:\n\npapercrane files write page.tsx --json \'"use client";\\nexport default function() {}"\'')
+  .option('-w, --workspace <id>', 'Workspace ID (uses default if not specified)')
+  .option('-f, --file <localPath>', 'Read content from a local file')
+  .option('--json <string>', 'Content as a JSON-encoded string (recommended for code)')
+  .option('--stdin', 'Read content from stdin')
+  .action(async (path, contentArg, options) => {
+    try {
+      const loggedIn = await isLoggedIn();
+      if (!loggedIn) {
+        console.error(chalk.red('Error: Not logged in. Run: papercrane login'));
+        process.exit(1);
+      }
+
+      let content;
+
+      if (options.json) {
+        // Parse JSON-encoded string
+        try {
+          content = JSON.parse(options.json);
+          if (typeof content !== 'string') {
+            console.error(chalk.red('Error: --json must be a JSON string, e.g., \'"hello\\nworld"\''));
+            process.exit(1);
+          }
+        } catch (e) {
+          console.error(chalk.red('Error: Invalid JSON string'));
+          console.error(chalk.dim('  Expected format: \'"line1\\nline2"\''));
+          process.exit(1);
+        }
+      } else if (options.file) {
+        // Read from local file
+        content = await fs.readFile(options.file, 'utf-8');
+      } else if (options.stdin) {
+        // Read from stdin
+        content = await readStdin();
+      } else if (contentArg) {
+        // Use positional argument
+        content = contentArg;
+      } else {
+        console.error(chalk.red('Error: Content required. Provide --json, --file, --stdin, or as argument'));
+        process.exit(1);
+      }
+
+      const wsId = await resolveWorkspaceId(options.workspace);
+      const result = await writeFile(wsId, path, content);
+
+      console.log(chalk.green(`✓ Written ${result.size} bytes to ${result.path}\n`));
+    } catch (error) {
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+filesCmd
+  .command('edit <path>')
+  .description('Edit a file with find/replace')
+  .option('-w, --workspace <id>', 'Workspace ID (uses default if not specified)')
+  .option('--old <string>', 'Text to find')
+  .option('--new <string>', 'Text to replace with')
+  .option('--replace-all', 'Replace all occurrences')
+  .option('-p, --params <json>', 'Parameters as JSON: {"old_string": "...", "new_string": "...", "replace_all": false}')
+  .option('--stdin', 'Read parameters as JSON from stdin')
+  .action(async (path, options) => {
+    try {
+      const loggedIn = await isLoggedIn();
+      if (!loggedIn) {
+        console.error(chalk.red('Error: Not logged in. Run: papercrane login'));
+        process.exit(1);
+      }
+
+      let oldString, newString, replaceAll = false;
+
+      if (options.stdin) {
+        // Read JSON from stdin
+        const input = await readStdin();
+        const params = JSON.parse(input);
+        oldString = params.old_string;
+        newString = params.new_string;
+        replaceAll = params.replace_all || false;
+      } else if (options.params) {
+        // Parse JSON params
+        const params = JSON.parse(options.params);
+        oldString = params.old_string;
+        newString = params.new_string;
+        replaceAll = params.replace_all || false;
+      } else if (options.old !== undefined && options.new !== undefined) {
+        // Use --old and --new flags
+        oldString = options.old;
+        newString = options.new;
+        replaceAll = options.replaceAll || false;
+      } else {
+        console.error(chalk.red('Error: Must provide --old and --new, or --params, or --stdin'));
+        process.exit(1);
+      }
+
+      const wsId = await resolveWorkspaceId(options.workspace);
+      const result = await editFile(wsId, path, oldString, newString, replaceAll);
+
+      console.log(chalk.green(`✓ Made ${result.replacements} replacement(s) in ${result.path}\n`));
+    } catch (error) {
+      if (error.response?.data?.error) {
+        console.error(chalk.red('Error:'), error.response.data.error);
+        if (error.response.data.occurrences) {
+          console.error(chalk.dim(`  Found ${error.response.data.occurrences} occurrences. Use --replace-all to replace all.`));
+        }
+      } else {
+        console.error(chalk.red('Error:'), error.message);
+      }
+      process.exit(1);
+    }
+  });
+
+filesCmd
+  .command('delete <path>')
+  .description('Delete a file')
+  .option('-w, --workspace <id>', 'Workspace ID (uses default if not specified)')
+  .action(async (path, options) => {
+    try {
+      const loggedIn = await isLoggedIn();
+      if (!loggedIn) {
+        console.error(chalk.red('Error: Not logged in. Run: papercrane login'));
+        process.exit(1);
+      }
+
+      const wsId = await resolveWorkspaceId(options.workspace);
+      const result = await deleteFile(wsId, path);
+
+      console.log(chalk.green(`✓ Deleted ${result.path}\n`));
+    } catch (error) {
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// PULL / PUSH COMMANDS
+// ============================================================================
+
+program
+  .command('pull')
+  .description('Pull workspace files to local ~/.papercrane/workspaces/<id>/ for editing')
+  .option('-w, --workspace <id>', 'Workspace ID (uses default if not specified)')
+  .action(async (options) => {
+    try {
+      const loggedIn = await isLoggedIn();
+      if (!loggedIn) {
+        console.error(chalk.red('Error: Not logged in. Run: papercrane login'));
+        process.exit(1);
+      }
+
+      const wsId = await resolveWorkspaceId(options.workspace);
+
+      console.log(chalk.cyan(`Pulling workspace ${wsId}...`));
+
+      const { localPath, files } = await pullWorkspace(wsId, (file, current, total) => {
+        process.stdout.write(`\r  ${chalk.dim(`[${current}/${total}]`)} ${file}`);
+      });
+
+      console.log('\n');
+      console.log(chalk.green(`✓ Pulled ${files.length} files to ${localPath}\n`));
+      console.log(chalk.dim('Edit files locally, then run: papercrane push'));
+    } catch (error) {
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('push')
+  .description('Push local files back to workspace')
+  .option('-w, --workspace <id>', 'Workspace ID (uses default if not specified)')
+  .option('-p, --path <path>', 'Only push files under this path (e.g., "verdata-vrisk")')
+  .action(async (options) => {
+    try {
+      const loggedIn = await isLoggedIn();
+      if (!loggedIn) {
+        console.error(chalk.red('Error: Not logged in. Run: papercrane login'));
+        process.exit(1);
+      }
+
+      const wsId = await resolveWorkspaceId(options.workspace);
+      const localPath = getLocalWorkspacePath(wsId);
+      const pathFilter = options.path;
+
+      console.log(chalk.cyan(`Pushing to workspace ${wsId}...`));
+
+      const { files } = await pushWorkspace(wsId, (file, current, total) => {
+        process.stdout.write(`\r  ${chalk.dim(`[${current}/${total}]`)} ${file}`);
+      }, pathFilter);
+
+      console.log('\n');
+      console.log(chalk.green(`✓ Pushed ${files.length} files from ${localPath}`));
+
+      // Print preview URL(s)
+      const { getApiBaseUrl } = await import('../lib/config.js');
+      const baseUrl = await getApiBaseUrl();
+
+      // Find unique dashboard directories that were pushed
+      const dashboards = [...new Set(files.map(f => f.split('/')[0]).filter(d => d && !d.includes('.')))];
+
+      if (dashboards.length > 0) {
+        console.log('');
+        console.log(chalk.dim('Preview:'));
+        for (const dashboard of dashboards) {
+          console.log(chalk.cyan(`  ${baseUrl}/environments/${wsId}/${dashboard}`));
+        }
+      }
+      console.log('');
+    } catch (error) {
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+// Helper to read from stdin
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', chunk => data += chunk);
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+// Helper to print file tree recursively
+function printFileTree(tree, indent = '') {
+  if (!tree || !Array.isArray(tree)) return;
+
+  // Sort: folders first, then files
+  const sorted = [...tree].sort((a, b) => {
+    if (a.type === 'folder' && b.type !== 'folder') return -1;
+    if (a.type !== 'folder' && b.type === 'folder') return 1;
+    return a.name.localeCompare(b.name);
+  });
+
+  for (const item of sorted) {
+    if (item.type === 'folder') {
+      console.log(`${indent}${chalk.blue(item.name + '/')}`);
+      if (item.children) {
+        printFileTree(item.children, indent + '  ');
+      }
+    } else {
+      console.log(`${indent}${item.name}`);
+    }
+  }
+}
+
 // Default action: show connected modules when no command is given
 program.action(async (_, cmd) => {
   // Reject unknown commands instead of silently falling through
@@ -197,12 +761,22 @@ program.action(async (_, cmd) => {
     console.error(chalk.red(`Unknown command: ${unknownArgs[0]}`));
     console.error();
     console.error('Available commands:');
-    console.error('  papercrane                    List connected integrations and endpoints');
-    console.error('  papercrane describe <path>    Describe a module or endpoint');
-    console.error('  papercrane call <path> [json] Call an endpoint');
-    console.error('  papercrane add                Add a new integration');
-    console.error('  papercrane login              Log in with API key');
-    console.error('  papercrane logout             Log out');
+    console.error('  papercrane                      List connected integrations and endpoints');
+    console.error('  papercrane describe <path>      Describe a module or endpoint');
+    console.error('  papercrane call <path> [json]   Call an endpoint');
+    console.error('  papercrane add                  Add a new integration');
+    console.error('  papercrane dashboard-guide      Show how to build dashboards');
+    console.error('  papercrane workspaces list      List workspaces');
+    console.error('  papercrane workspaces use <id>  Set default workspace');
+    console.error('  papercrane files list [path]    List files in workspace');
+    console.error('  papercrane files read <path>    Read file contents');
+    console.error('  papercrane files write <path>   Write file contents');
+    console.error('  papercrane files edit <path>    Edit file with find/replace');
+    console.error('  papercrane files delete <path>  Delete a file');
+    console.error('  papercrane pull                 Pull workspace files locally for editing');
+    console.error('  papercrane push                 Push local changes back to workspace');
+    console.error('  papercrane login                Log in with API key');
+    console.error('  papercrane logout               Log out');
     process.exit(1);
   }
 

package/lib/auth-server.js

@@ -0,0 +1,186 @@
+import http from 'http';
+import crypto from 'crypto';
+import { URL } from 'url';
+
+/**
+ * Generate a random state token for CSRF protection
+ * @returns {string}
+ */
+export function generateState() {
+  return crypto.randomBytes(16).toString('hex');
+}
+
+/**
+ * Find an available port
+ * @returns {Promise<number>}
+ */
+function findAvailablePort() {
+  return new Promise((resolve, reject) => {
+    const server = http.createServer();
+    server.listen(0, '127.0.0.1', () => {
+      const port = server.address().port;
+      server.close(() => resolve(port));
+    });
+    server.on('error', reject);
+  });
+}
+
+/**
+ * Generate HTML page with Papercrane styling
+ */
+function generateHtmlPage(baseUrl, { title, message, isError = false }) {
+  const iconColor = isError ? '#e53e3e' : '#228be6';
+  const icon = isError
+    ? `<svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 24 24" fill="none" stroke="${iconColor}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"></circle><line x1="15" y1="9" x2="9" y2="15"></line><line x1="9" y1="9" x2="15" y2="15"></line></svg>`
+    : `<svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 24 24" fill="none" stroke="${iconColor}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M22 11.08V12a10 10 0 1 1-5.93-9.14"></path><polyline points="22 4 12 14.01 9 11.01"></polyline></svg>`;
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${title} - Papercrane</title>
+  <style>
+    * {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      background-color: #f8f9fa;
+      min-height: 100vh;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      padding: 20px;
+    }
+    .card {
+      background: white;
+      border-radius: 8px;
+      box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1), 0 1px 2px rgba(0, 0, 0, 0.06);
+      border: 1px solid #e9ecef;
+      padding: 40px;
+      max-width: 400px;
+      width: 100%;
+      text-align: center;
+    }
+    .logo {
+      margin-bottom: 24px;
+    }
+    .logo img {
+      height: 36px;
+    }
+    .icon {
+      margin-bottom: 16px;
+    }
+    h1 {
+      font-size: 20px;
+      font-weight: 600;
+      color: #212529;
+      margin-bottom: 8px;
+    }
+    p {
+      color: #868e96;
+      font-size: 14px;
+      line-height: 1.5;
+    }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <div class="logo">
+      <img src="${baseUrl}/papercrane_and_logo.svg" alt="Papercrane" onerror="this.style.display='none'">
+    </div>
+    <div class="icon">${icon}</div>
+    <h1>${title}</h1>
+    <p>${message}</p>
+  </div>
+</body>
+</html>`;
+}
+
+/**
+ * Start auth server and return port immediately
+ * @param {string} expectedState - The state token to validate
+ * @param {string} baseUrl - The Papercrane base URL (for logo)
+ * @param {number} timeoutMs - Timeout in milliseconds
+ * @returns {Promise<{port: number, waitForAuth: () => Promise<{key: string, email: string}>}>}
+ */
+export async function createAuthServer(expectedState, baseUrl = '', timeoutMs = 120000) {
+  const port = await findAvailablePort();
+
+  let resolveAuth, rejectAuth;
+  const authPromise = new Promise((resolve, reject) => {
+    resolveAuth = resolve;
+    rejectAuth = reject;
+  });
+
+  const server = http.createServer((req, res) => {
+    const url = new URL(req.url, `http://localhost:${port}`);
+
+    if (url.pathname !== '/callback') {
+      res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+      res.end('Not Found');
+      return;
+    }
+
+    const key = url.searchParams.get('key');
+    const state = url.searchParams.get('state');
+    const email = url.searchParams.get('email');
+
+    if (state !== expectedState) {
+      res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+      res.end(generateHtmlPage(baseUrl, {
+        title: 'Authentication Failed',
+        message: 'Invalid state parameter. This could be a security issue. Please try again from your terminal.',
+        isError: true
+      }));
+      return;
+    }
+
+    if (!key) {
+      res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+      res.end(generateHtmlPage(baseUrl, {
+        title: 'Authentication Failed',
+        message: 'No API key received. Please try again from your terminal.',
+        isError: true
+      }));
+      return;
+    }
+
+    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+    res.end(generateHtmlPage(baseUrl, {
+      title: 'CLI Authenticated',
+      message: 'You can close this window and return to your terminal.'
+    }));
+
+    server.close();
+    resolveAuth({ key, email: email || 'unknown' });
+  });
+
+  const timeout = setTimeout(() => {
+    server.close();
+    rejectAuth(new Error('Authentication timed out. Please try again.'));
+  }, timeoutMs);
+
+  server.on('close', () => clearTimeout(timeout));
+  server.on('error', (err) => {
+    clearTimeout(timeout);
+    rejectAuth(err);
+  });
+
+  await new Promise((resolve, reject) => {
+    server.listen(port, '127.0.0.1', resolve);
+    server.on('error', reject);
+  });
+
+  return {
+    port,
+    waitForAuth: () => authPromise,
+    close: () => {
+      clearTimeout(timeout);
+      server.close();
+    }
+  };
+}

package/lib/config.js

@@ -95,3 +95,31 @@ export async function clearConfig() {
   await ensureConfigDir();
   await fs.writeFile(CONFIG_FILE, JSON.stringify({}, null, 2));
 }
+
+/**
+ * Get the default workspace ID from config
+ * @returns {Promise<number|null>}
+ */
+export async function getDefaultWorkspace() {
+  const config = await loadConfig();
+  return config.defaultWorkspaceId || null;
+}
+
+/**
+ * Set the default workspace ID in config
+ * @param {number} workspaceId - The workspace ID to set as default
+ */
+export async function setDefaultWorkspace(workspaceId) {
+  const config = await loadConfig();
+  config.defaultWorkspaceId = workspaceId;
+  await saveConfig(config);
+}
+
+/**
+ * Clear the default workspace from config
+ */
+export async function clearDefaultWorkspace() {
+  const config = await loadConfig();
+  delete config.defaultWorkspaceId;
+  await saveConfig(config);
+}

package/lib/environment-client.js

@@ -0,0 +1,327 @@
+import axios from 'axios';
+import { homedir } from 'os';
+import { join } from 'path';
+import { getApiKey, getApiBaseUrl, getDefaultWorkspace, setDefaultWorkspace } from './config.js';
+
+/**
+ * Get authorization headers
+ * @returns {Promise<Object>}
+ */
+async function getAuthHeaders() {
+  const apiKey = await getApiKey();
+  if (!apiKey) {
+    throw new Error('Not logged in. Run: papercrane login');
+  }
+  return {
+    'Authorization': `Bearer ${apiKey}`,
+    'Content-Type': 'application/json'
+  };
+}
+
+/**
+ * Resolve workspace ID from option or default.
+ * If no default is set and only one workspace exists, auto-selects it.
+ * @param {number|string|null} wsOption - Workspace ID from command option
+ * @returns {Promise<number>}
+ */
+export async function resolveWorkspaceId(wsOption) {
+  if (wsOption) {
+    return parseInt(wsOption, 10);
+  }
+
+  const defaultWs = await getDefaultWorkspace();
+  if (defaultWs) {
+    return defaultWs;
+  }
+
+  // No default set - check if there's only one workspace
+  const workspaces = await listWorkspaces();
+
+  if (workspaces.length === 0) {
+    throw new Error('No workspaces available. Create a workspace at https://papercrane.ai first.');
+  }
+
+  if (workspaces.length === 1) {
+    // Auto-select the only workspace
+    const wsId = workspaces[0].id;
+    await setDefaultWorkspace(wsId);
+    console.log(`Auto-selected workspace ${wsId} as default (only workspace available)`);
+    return wsId;
+  }
+
+  // Multiple workspaces - user must choose
+  const wsIds = workspaces.map(ws => `  ${ws.id}: ${ws.name || '(unnamed)'}`).join('\n');
+  throw new Error(`Multiple workspaces available. Use -w <id> or run: papercrane workspaces use <id>\n\nAvailable workspaces:\n${wsIds}`);
+}
+
+/**
+ * List all workspaces for the current user
+ * @returns {Promise<Array>}
+ */
+export async function listWorkspaces() {
+  const headers = await getAuthHeaders();
+  const baseUrl = await getApiBaseUrl();
+
+  const response = await axios.get(`${baseUrl}/sdk/workspaces`, { headers });
+  return response.data.workspaces;
+}
+
+/**
+ * Get file tree for a workspace
+ * @param {number} workspaceId
+ * @param {string} path - Subdirectory path (optional)
+ * @returns {Promise<Object>}
+ */
+export async function getFileTree(workspaceId, path = '') {
+  const headers = await getAuthHeaders();
+  const baseUrl = await getApiBaseUrl();
+
+  const url = path
+    ? `${baseUrl}/sdk/workspaces/${workspaceId}/files?path=${encodeURIComponent(path)}`
+    : `${baseUrl}/sdk/workspaces/${workspaceId}/files`;
+
+  const response = await axios.get(url, { headers });
+  return response.data;
+}
+
+/**
+ * Read file contents
+ * @param {number} workspaceId
+ * @param {string} path - File path
+ * @returns {Promise<Object>}
+ */
+export async function readFile(workspaceId, path) {
+  const headers = await getAuthHeaders();
+  const baseUrl = await getApiBaseUrl();
+
+  const response = await axios.get(
+    `${baseUrl}/sdk/workspaces/${workspaceId}/files/read?path=${encodeURIComponent(path)}`,
+    { headers }
+  );
+  return response.data;
+}
+
+/**
+ * Write file contents
+ * @param {number} workspaceId
+ * @param {string} path - File path
+ * @param {string} content - File content
+ * @returns {Promise<Object>}
+ */
+export async function writeFile(workspaceId, path, content) {
+  const headers = await getAuthHeaders();
+  const baseUrl = await getApiBaseUrl();
+
+  const response = await axios.post(
+    `${baseUrl}/sdk/workspaces/${workspaceId}/files/write`,
+    { path, content },
+    { headers }
+  );
+  return response.data;
+}
+
+/**
+ * Edit file with find/replace
+ * @param {number} workspaceId
+ * @param {string} path - File path
+ * @param {string} oldString - Text to find
+ * @param {string} newString - Text to replace with
+ * @param {boolean} replaceAll - Replace all occurrences
+ * @returns {Promise<Object>}
+ */
+export async function editFile(workspaceId, path, oldString, newString, replaceAll = false) {
+  const headers = await getAuthHeaders();
+  const baseUrl = await getApiBaseUrl();
+
+  const response = await axios.post(
+    `${baseUrl}/sdk/workspaces/${workspaceId}/files/edit`,
+    { path, old_string: oldString, new_string: newString, replace_all: replaceAll },
+    { headers }
+  );
+  return response.data;
+}
+
+/**
+ * Delete a file
+ * @param {number} workspaceId
+ * @param {string} path - File path
+ * @returns {Promise<Object>}
+ */
+export async function deleteFile(workspaceId, path) {
+  const headers = await getAuthHeaders();
+  const baseUrl = await getApiBaseUrl();
+
+  const response = await axios.delete(
+    `${baseUrl}/sdk/workspaces/${workspaceId}/files?path=${encodeURIComponent(path)}`,
+    { headers }
+  );
+  return response.data;
+}
+
+/**
+ * Get the local workspace directory path
+ * @param {number} workspaceId
+ * @returns {string}
+ */
+export function getLocalWorkspacePath(workspaceId) {
+  return join(homedir(), '.papercrane', 'workspaces', String(workspaceId));
+}
+
+/**
+ * Recursively collect all file paths from a file tree
+ * @param {Array} tree - File tree from getFileTree
+ * @param {string} prefix - Current path prefix
+ * @returns {string[]} - Array of file paths
+ */
+function collectFilePaths(tree, prefix = '') {
+  const paths = [];
+  for (const item of tree) {
+    const itemPath = prefix ? `${prefix}/${item.name}` : item.name;
+    if (item.type === 'folder' && item.children) {
+      paths.push(...collectFilePaths(item.children, itemPath));
+    } else if (item.type === 'file') {
+      paths.push(itemPath);
+    }
+  }
+  return paths;
+}
+
+/**
+ * Pull all files from workspace to local directory
+ * @param {number} workspaceId
+ * @param {function} onProgress - Callback for progress updates (path, index, total)
+ * @returns {Promise<{localPath: string, files: string[]}>}
+ */
+export async function pullWorkspace(workspaceId, onProgress = null) {
+  const { mkdir, writeFile: fsWriteFile } = await import('fs/promises');
+  const { dirname } = await import('path');
+
+  const localPath = getLocalWorkspacePath(workspaceId);
+
+  // Get file tree
+  const { tree } = await getFileTree(workspaceId);
+  const filePaths = collectFilePaths(tree);
+
+  // Create local directory
+  await mkdir(localPath, { recursive: true });
+
+  // Download each file
+  const downloaded = [];
+  for (let i = 0; i < filePaths.length; i++) {
+    const filePath = filePaths[i];
+    if (onProgress) onProgress(filePath, i + 1, filePaths.length);
+
+    try {
+      const { content } = await readFile(workspaceId, filePath);
+      const localFilePath = join(localPath, filePath);
+
+      // Ensure directory exists
+      await mkdir(dirname(localFilePath), { recursive: true });
+
+      // Write file
+      await fsWriteFile(localFilePath, content, 'utf-8');
+      downloaded.push(filePath);
+    } catch (error) {
+      // Skip files that can't be read (e.g., binary files)
+      console.warn(`Skipping ${filePath}: ${error.message}`);
+    }
+  }
+
+  return { localPath, files: downloaded };
+}
+
+// Binary file extensions to skip during push
+const BINARY_EXTENSIONS = new Set([
+  'ico', 'png', 'jpg', 'jpeg', 'gif', 'webp', 'svg', 'bmp',
+  'woff', 'woff2', 'ttf', 'eot', 'otf',
+  'pdf', 'zip', 'tar', 'gz', 'rar',
+  'mp3', 'mp4', 'wav', 'avi', 'mov',
+  'exe', 'dll', 'so', 'dylib'
+]);
+
+/**
+ * Check if a file is binary based on extension
+ * @param {string} filename
+ * @returns {boolean}
+ */
+function isBinaryFile(filename) {
+  const ext = filename.split('.').pop()?.toLowerCase();
+  return ext ? BINARY_EXTENSIONS.has(ext) : false;
+}
+
+/**
+ * Recursively collect all local files
+ * @param {string} dir - Directory to scan
+ * @param {string} prefix - Current path prefix
+ * @returns {Promise<string[]>}
+ */
+async function collectLocalFiles(dir, prefix = '') {
+  const { readdir, stat } = await import('fs/promises');
+  const paths = [];
+
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      // Skip hidden files and common non-source directories
+      if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+
+      const itemPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+      const fullPath = join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        paths.push(...await collectLocalFiles(fullPath, itemPath));
+      } else if (!isBinaryFile(entry.name)) {
+        // Skip binary files
+        paths.push(itemPath);
+      }
+    }
+  } catch (error) {
+    // Directory doesn't exist or can't be read
+  }
+
+  return paths;
+}
+
+/**
+ * Push local files to workspace
+ * @param {number} workspaceId
+ * @param {function} onProgress - Callback for progress updates (path, index, total)
+ * @param {string} pathFilter - Only push files under this path (optional)
+ * @returns {Promise<{files: string[]}>}
+ */
+export async function pushWorkspace(workspaceId, onProgress = null, pathFilter = null) {
+  const { readFile: fsReadFile } = await import('fs/promises');
+
+  const localPath = getLocalWorkspacePath(workspaceId);
+
+  // Collect local files
+  let filePaths = await collectLocalFiles(localPath);
+
+  // Apply path filter if specified
+  if (pathFilter) {
+    const normalizedFilter = pathFilter.replace(/^\/+|\/+$/g, ''); // Remove leading/trailing slashes
+    filePaths = filePaths.filter(p => p.startsWith(normalizedFilter + '/') || p === normalizedFilter);
+  }
+
+  if (filePaths.length === 0) {
+    const msg = pathFilter
+      ? `No files found matching '${pathFilter}' in ${localPath}`
+      : `No files found in ${localPath}. Run 'papercrane pull' first.`;
+    throw new Error(msg);
+  }
+
+  // Upload each file
+  const uploaded = [];
+  for (let i = 0; i < filePaths.length; i++) {
+    const filePath = filePaths[i];
+    if (onProgress) onProgress(filePath, i + 1, filePaths.length);
+
+    const localFilePath = join(localPath, filePath);
+    const content = await fsReadFile(localFilePath, 'utf-8');
+
+    await writeFile(workspaceId, filePath, content);
+    uploaded.push(filePath);
+  }
+
+  return { files: uploaded };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papercraneai/cli",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "CLI tool for managing OAuth credentials for LLM integrations",
   "main": "index.js",
   "type": "module",