figmanage 1.2.9 → 1.3.1

package/README.md

@@ -49,23 +49,25 @@ figmanage runs as an MCP server for Claude, ChatGPT, Cursor, and other AI assist
 
 ```bash
 # Claude Code
-claude mcp add figmanage -- npx -y figmanage --mcp
+claude mcp add figmanage -- npx -y figmanage
 
-# Claude Desktop / Cowork
-# Add to claude_desktop_config.json:
+# Claude Desktop / Cursor / other clients
+# Add to your MCP config:
 {
   "mcpServers": {
     "figmanage": {
       "command": "npx",
-      "args": ["-y", "figmanage", "--mcp"]
+      "args": ["-y", "figmanage"]
     }
   }
 }
 ```
 
-Credentials are read from `~/.config/figmanage/` (set up via `figmanage login`). Env vars (`FIGMA_PAT`, `FIGMA_AUTH_COOKIE`, etc.) override the config file for backwards compatibility.
+On first run, figmanage walks you through setup right in the conversation -- extracts your Chrome session cookie, asks you to create a PAT, and stores credentials locally. No env vars, no JSON editing, no separate terminal step.
 
-MCP mode exposes all 85 tools to the AI assistant. HTTP transport available via `--mcp --http <port>`.
+If you prefer CLI setup or need to reconfigure: `npx figmanage login`.
+
+Env vars (`FIGMA_PAT`, `FIGMA_AUTH_COOKIE`, etc.) override the config file for backwards compatibility. HTTP transport available via `--mcp --http <port>`.
 
 ### toolset presets (MCP only)
 
@@ -87,9 +89,9 @@ figmanage uses two Figma API surfaces:
 | Internal API | Session cookie | Workspace management, search, permissions, org admin, seats, billing |
 | Public API | Personal Access Token | Comments, export, file reading, components, versions, webhooks, variables |
 
-Cookie auth unlocks all 85 tools. PAT-only gives ~30 (reading, comments, export, components). Both together is recommended.
+Both together give full access to all 85 tools. Cookie-only or PAT-only work but limit available tools.
 
-Auth resolution: env vars > config file > prompt to run `figmanage login`.
+Auth resolution: env vars > config file > interactive setup (MCP) or `figmanage login` (CLI).
 
 ## commands
 

package/dist/cli/analytics.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { libraryUsage, componentUsage } from '../operations/analytics.js';
 import { output, error } from './format.js';
+import { formatApiError } from '../helpers.js';
 import { requireCookie } from './helpers.js';
 export function analyticsCommand() {
     const analytics = new Command('analytics')
@@ -20,7 +21,7 @@ export function analyticsCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -39,7 +40,7 @@ export function analyticsCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });

package/dist/cli/branching.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { listBranches, createBranch, deleteBranch } from '../operations/branching.js';
 import { output, error } from './format.js';
+import { formatApiError } from '../helpers.js';
 import { requireAuth, requireCookie } from './helpers.js';
 export function branchingCommand() {
     const branching = new Command('branches')
@@ -16,7 +17,7 @@ export function branchingCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -32,7 +33,7 @@ export function branchingCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -43,11 +44,16 @@ export function branchingCommand() {
         .action(async (branchKey, options) => {
         try {
             const config = requireCookie();
+            const { confirmAction } = await import('./helpers.js');
+            if (!await confirmAction(`Delete branch ${branchKey}?`)) {
+                console.log('Cancelled.');
+                return;
+            }
             await deleteBranch(config, { branch_key: branchKey });
             output({ archived: branchKey }, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });

package/dist/cli/comments.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { listComments, formatCommentsAsMarkdown, postComment, deleteComment, listCommentReactions, } from '../operations/comments.js';
 import { output, error } from './format.js';
+import { formatApiError } from '../helpers.js';
 import { requirePat } from './helpers.js';
 export function commentsCommand() {
     const comments = new Command('comments')
@@ -21,7 +22,7 @@ export function commentsCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -44,7 +45,7 @@ export function commentsCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -55,11 +56,16 @@ export function commentsCommand() {
         .action(async (fileKey, commentId, options) => {
         try {
             const config = requirePat();
+            const { confirmAction } = await import('./helpers.js');
+            if (!await confirmAction(`Delete comment ${commentId}? For top-level comments, the entire thread is removed.`)) {
+                console.log('Cancelled.');
+                return;
+            }
             await deleteComment(config, { file_key: fileKey, comment_id: commentId });
             output({ deleted: commentId }, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -77,7 +83,7 @@ export function commentsCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });

package/dist/cli/components.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { listFileComponents, listFileStyles, listTeamComponents, listTeamStyles, } from '../operations/components.js';
 import { output, error } from './format.js';
+import { formatApiError } from '../helpers.js';
 import { requirePat } from './helpers.js';
 export function componentsCommand() {
     const components = new Command('components')
@@ -13,10 +14,14 @@ export function componentsCommand() {
         try {
             const config = requirePat();
             const result = await listFileComponents(config, { file_key: fileKey });
+            if (result.components.length === 0) {
+                console.log('No components found.');
+                return;
+            }
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -28,10 +33,14 @@ export function componentsCommand() {
         try {
             const config = requirePat();
             const result = await listFileStyles(config, { file_key: fileKey });
+            if (result.styles.length === 0) {
+                console.log('No styles found.');
+                return;
+            }
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -49,10 +58,14 @@ export function componentsCommand() {
                 page_size: options.pageSize ? parseInt(options.pageSize, 10) : undefined,
                 cursor: options.cursor,
             });
+            if (result.components.length === 0) {
+                console.log('No components found.');
+                return;
+            }
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -70,10 +83,14 @@ export function componentsCommand() {
                 page_size: options.pageSize ? parseInt(options.pageSize, 10) : undefined,
                 cursor: options.cursor,
             });
+            if (result.styles.length === 0) {
+                console.log('No styles found.');
+                return;
+            }
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });

package/dist/cli/compound-commands.js

@@ -2,6 +2,7 @@ import { Command } from 'commander';
 import { fileSummary, workspaceOverview, openComments, cleanupStaleFiles, organizeProject, setupProjectStructure, seatOptimization, permissionAudit, branchCleanup, } from '../operations/compound.js';
 import { offboardUser, onboardUser, quarterlyDesignOpsReport, } from '../operations/compound-manager.js';
 import { output, error } from './format.js';
+import { formatApiError } from '../helpers.js';
 import { requireAuth, requirePat, requireCookie, validateId, parsePositiveInt } from './helpers.js';
 // -- compound.ts tools --
 export function fileSummaryCommand() {
@@ -17,7 +18,7 @@ export function fileSummaryCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -33,7 +34,7 @@ export function workspaceOverviewCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -51,7 +52,7 @@ export function openCommentsCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -76,7 +77,7 @@ export function cleanupStaleFilesCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -100,7 +101,7 @@ export function organizeProjectCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -131,7 +132,7 @@ export function setupProjectStructureCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -153,7 +154,7 @@ export function seatOptimizationCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -181,7 +182,7 @@ export function permissionAuditCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -206,7 +207,7 @@ export function branchCleanupCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -230,7 +231,7 @@ export function offboardUserCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -265,7 +266,7 @@ export function onboardUserCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -283,7 +284,7 @@ export function quarterlyReportCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });

package/dist/cli/export.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { exportNodes, getImageFills } from '../operations/export.js';
 import { output, error } from './format.js';
+import { formatApiError } from '../helpers.js';
 import { requirePat } from './helpers.js';
 export function exportCommand() {
     const exp = new Command('export')
@@ -23,7 +24,7 @@ export function exportCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -42,7 +43,7 @@ export function exportCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });

package/dist/cli/files.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { createFile, renameFile, moveFiles, duplicateFile, trashFiles, restoreFiles, favoriteFile, setLinkAccess, } from '../operations/files.js';
 import { output, error } from './format.js';
+import { formatApiError } from '../helpers.js';
 import { requireCookie } from './helpers.js';
 export function filesCommand() {
     const files = new Command('files')
@@ -22,7 +23,7 @@ export function filesCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -38,7 +39,7 @@ export function filesCommand() {
             output({ renamed: fileKey, name: options.name }, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -58,7 +59,7 @@ export function filesCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -77,7 +78,7 @@ export function filesCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -89,11 +90,16 @@ export function filesCommand() {
         .action(async (options) => {
         try {
             const config = requireCookie();
+            const { confirmAction } = await import('./helpers.js');
+            if (!await confirmAction(`Trash ${options.fileKeys.length} file(s)?`)) {
+                console.log('Cancelled.');
+                return;
+            }
             const result = await trashFiles(config, { file_keys: options.fileKeys });
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -109,7 +115,7 @@ export function filesCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -128,7 +134,7 @@ export function filesCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -147,7 +153,7 @@ export function filesCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });

package/dist/cli/helpers.d.ts

@@ -4,4 +4,5 @@ export declare function parsePositiveInt(value: string, label: string, fallback:
 export declare function requireAuth(): AuthConfig;
 export declare function requirePat(): AuthConfig;
 export declare function requireCookie(): AuthConfig;
+export declare function confirmAction(message: string): Promise<boolean>;
 //# sourceMappingURL=helpers.d.ts.map

package/dist/cli/helpers.js

@@ -1,3 +1,4 @@
+import * as readline from 'node:readline';
 import { loadAuthConfig, hasPat, hasCookie } from '../auth/client.js';
 import { error } from './format.js';
 const ID_PATTERN = /^[\w.:-]+$/;
@@ -40,4 +41,13 @@ export function requireCookie() {
     }
     return config;
 }
+export async function confirmAction(message) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    return new Promise((resolve) => {
+        rl.question(`${message} [y/N] `, (answer) => {
+            rl.close();
+            resolve(answer.trim().toLowerCase() === 'y');
+        });
+    });
+}
 //# sourceMappingURL=helpers.js.map

package/dist/cli/libraries.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { listOrgLibraries } from '../operations/libraries.js';
 import { output, error } from './format.js';
+import { formatApiError } from '../helpers.js';
 import { requireCookie } from './helpers.js';
 export function librariesCommand() {
     const libraries = new Command('libraries')
@@ -17,7 +18,7 @@ export function librariesCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });

package/dist/cli/navigate.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { checkAuthStatus, listOrgs, switchOrg, listTeams, listProjects, listFiles, listRecentFiles, search, getFileInfo, listFavorites, } from '../operations/navigate.js';
 import { output, error } from './format.js';
+import { formatApiError } from '../helpers.js';
 import { requireAuth, requireCookie } from './helpers.js';
 export function navigateCommand() {
     const nav = new Command('navigate')
@@ -21,7 +22,7 @@ export function navigateCommand() {
             }
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -40,7 +41,7 @@ export function navigateCommand() {
             output(orgs, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -58,7 +59,7 @@ export function navigateCommand() {
             }, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -73,7 +74,7 @@ export function navigateCommand() {
             output(teams, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -88,7 +89,7 @@ export function navigateCommand() {
             output(projects, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -109,7 +110,7 @@ export function navigateCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -124,7 +125,7 @@ export function navigateCommand() {
             output(files, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -149,7 +150,7 @@ export function navigateCommand() {
             output(results, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -164,7 +165,7 @@ export function navigateCommand() {
             output(info, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -183,7 +184,7 @@ export function navigateCommand() {
             output(favorites, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });