figmanage 1.0.1 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # figmanage
 
-Figma workspace management from the command line. 85 commands for seats, teams, permissions, billing, onboarding, and org admin. Also works as an MCP server for AI assistants.
+Figma workspace management from the command line. 85 CLI commands and MCP tools for seats, teams, permissions, billing, onboarding, and org admin. Also works as an MCP server for AI assistants.
 
 ## install
 
@@ -23,22 +23,25 @@ figmanage logout    # clear credentials
 
 ## usage
 
+Commands use a noun-verb pattern: `figmanage <group> <action>`.
+
 ```bash
-figmanage seat-optimization                      # find inactive paid seats
-figmanage offboard sarah@co.com                  # audit what a user owns
-figmanage offboard sarah@co.com --execute \
-  --transfer-to jake@co.com                      # execute the offboarding
-figmanage onboard alex@co.com --teams 123,456 \
-  --role editor --seat full --confirm            # set up a new hire
-figmanage quarterly-report                       # org-wide design ops snapshot
-figmanage members --search danny                 # find org members
-figmanage teams                                  # list all teams
-figmanage permissions file abc123                # who has access to a file
-figmanage permission-audit --scope team --id 789 # audit a team's permissions
-figmanage branch-cleanup 573408414               # find stale branches
+figmanage org seat-optimization                    # find inactive paid seats
+figmanage org offboard sarah@co.com                # audit what a user owns
+figmanage org offboard sarah@co.com --execute \
+  --transfer-to jake@co.com                        # execute the offboarding
+figmanage org onboard alex@co.com --teams 123,456 \
+  --role editor --seat full --confirm              # set up a new hire
+figmanage org quarterly-report                     # org-wide design ops snapshot
+figmanage org members --search danny               # find org members
+figmanage navigate list-teams                      # list all teams
+figmanage permissions get file abc123              # who has access to a file
+figmanage permissions audit --scope team --id 789  # audit a team's permissions
+figmanage branches cleanup 573408414               # find stale branches
+figmanage files summary abc123                     # pages, components, styles overview
 ```
 
-All commands output JSON when piped or when `--json` is passed.
+Run `figmanage <group> --help` for available subcommands. All commands output JSON when piped or when `--json` is passed.
 
 ## AI integration (MCP)
 
@@ -90,6 +93,8 @@ Auth resolution: env vars > config file > prompt to run `figmanage login`.
 
 ## commands
 
+The tables below list all 85 commands. The Command column shows MCP tool names (snake_case). The CLI equivalent is the noun-verb form: `figmanage <group> <action>` where `<action>` is the kebab-case version of the tool name without the group prefix (e.g. `list_recent_files` becomes `figmanage navigate list-recent-files`).
+
 ### navigate (10)
 
 | Command | Auth | Description |
@@ -105,7 +110,7 @@ Auth resolution: env vars > config file > prompt to run `figmanage login`.
 | `get_file_info` | either | File metadata: name, project, team, link access |
 | `list_favorites` | cookie | Favorited files (broken -- Figma BigInt bug) |
 
-### files (8)
+### files (10)
 
 | Command | Auth | Description |
 |---------|------|-------------|
@@ -117,8 +122,10 @@ Auth resolution: env vars > config file > prompt to run `figmanage login`.
 | `restore_files` | cookie | Restore files from trash (batch) |
 | `favorite_file` | cookie | Add/remove from favorites |
 | `set_link_access` | cookie | Set link sharing level |
+| `file_summary` | pat | Pages, components, styles, comment counts |
+| `cleanup_stale_files` | either | Find old files, optionally trash (dry run default) |
 
-### projects (6)
+### projects (8)
 
 | Command | Auth | Description |
 |---------|------|-------------|
@@ -128,8 +135,10 @@ Auth resolution: env vars > config file > prompt to run `figmanage login`.
 | `trash_project` | cookie | Move a project to trash |
 | `restore_project` | cookie | Restore a project from trash |
 | `set_project_description` | cookie | Set or update project description |
+| `organize_project` | cookie | Batch-move files into a project |
+| `setup_project_structure` | cookie | Create multiple projects from a plan |
 
-### permissions (7)
+### permissions (8)
 
 | Command | Auth | Description |
 |---------|------|-------------|
@@ -140,22 +149,7 @@ Auth resolution: env vars > config file > prompt to run `figmanage login`.
 | `list_role_requests` | cookie | List pending access requests |
 | `approve_role_request` | cookie | Accept an access request |
 | `deny_role_request` | cookie | Decline an access request |
-
-### reading (2)
-
-| Command | Auth | Description |
-|---------|------|-------------|
-| `get_file` | pat | Read file as a node tree with depth control |
-| `get_nodes` | pat | Read specific nodes by ID |
-
-### components (4)
-
-| Command | Auth | Description |
-|---------|------|-------------|
-| `list_file_components` | pat | Components published from a file |
-| `list_file_styles` | pat | Styles in a file |
-| `list_team_components` | pat | Published components across a team |
-| `list_team_styles` | pat | Published styles across a team |
+| `permission_audit` | cookie | Team/project access audit with oversharing flags |
 
 ### versions (2)
 
@@ -164,15 +158,16 @@ Auth resolution: env vars > config file > prompt to run `figmanage login`.
 | `list_versions` | pat | Version history |
 | `create_version` | cookie | Create a named version checkpoint |
 
-### branching (3)
+### branches (4)
 
 | Command | Auth | Description |
 |---------|------|-------------|
 | `list_branches` | either | List branches of a file |
 | `create_branch` | cookie | Create a branch |
 | `delete_branch` | cookie | Archive a branch |
+| `branch_cleanup` | either | Stale branch detection with optional archival |
 
-### comments (4)
+### comments (5)
 
 | Command | Auth | Description |
 |---------|------|-------------|
@@ -180,6 +175,7 @@ Auth resolution: env vars > config file > prompt to run `figmanage login`.
 | `post_comment` | pat | Post a comment |
 | `delete_comment` | pat | Delete a comment |
 | `list_comment_reactions` | pat | Emoji reactions on a comment |
+| `open_comments` | pat | Unresolved comments across a project |
 
 ### export (2)
 
@@ -188,6 +184,22 @@ Auth resolution: env vars > config file > prompt to run `figmanage login`.
 | `export_nodes` | pat | Export as PNG, SVG, PDF, or JPG |
 | `get_image_fills` | pat | URLs for all images used as fills |
 
+### reading (2)
+
+| Command | Auth | Description |
+|---------|------|-------------|
+| `get_file` | pat | Read file as a node tree with depth control |
+| `get_nodes` | pat | Read specific nodes by ID |
+
+### components (4)
+
+| Command | Auth | Description |
+|---------|------|-------------|
+| `list_file_components` | pat | Components published from a file |
+| `list_file_styles` | pat | Styles in a file |
+| `list_team_components` | pat | Published components across a team |
+| `list_team_styles` | pat | Published styles across a team |
+
 ### webhooks (4)
 
 | Command | Auth | Description |
@@ -212,7 +224,7 @@ Auth resolution: env vars > config file > prompt to run `figmanage login`.
 | `library_usage` | cookie | Team-level library adoption metrics |
 | `component_usage` | cookie | Per-file component usage |
 
-### org (12)
+### org (17)
 
 | Command | Auth | Description |
 |---------|------|-------------|
@@ -228,14 +240,11 @@ Auth resolution: env vars > config file > prompt to run `figmanage login`.
 | `org_domains` | cookie | Domain config and SSO/SAML |
 | `ai_credit_usage` | cookie | AI credit usage summary |
 | `export_members` | cookie | Trigger CSV export of all members |
-
-### teams (3)
-
-| Command | Auth | Description |
-|---------|------|-------------|
-| `create_team` | cookie | Create a team |
-| `rename_team` | cookie | Rename a team |
-| `delete_team` | cookie | Delete a team |
+| `workspace_overview` | cookie | Org snapshot: teams, seats, billing |
+| `seat_optimization` | cookie | Inactive seat detection with cost analysis |
+| `offboard_user` | cookie | Audit + execute user departure |
+| `onboard_user` | cookie | Batch invite to teams, share files, set seat |
+| `quarterly_design_ops_report` | cookie | Seat utilization, billing, teams, library adoption |
 
 ### libraries (1)
 
@@ -243,24 +252,13 @@ Auth resolution: env vars > config file > prompt to run `figmanage login`.
 |---------|------|-------------|
 | `list_org_libraries` | cookie | Design system libraries with sharing info |
 
-### compound (12)
-
-Multi-step operations that aggregate data from several API calls.
+### teams (3)
 
 | Command | Auth | Description |
 |---------|------|-------------|
-| `file_summary` | pat | Pages, components, styles, comment counts |
-| `workspace_overview` | cookie | Org snapshot: teams, seats, billing |
-| `open_comments` | pat | Unresolved comments across a project |
-| `cleanup_stale_files` | either | Find old files, optionally trash (dry run default) |
-| `organize_project` | cookie | Batch-move files into a project |
-| `setup_project_structure` | cookie | Create multiple projects from a plan |
-| `seat_optimization` | cookie | Inactive seat detection with cost analysis |
-| `permission_audit` | cookie | Team/project access audit with oversharing flags |
-| `branch_cleanup` | either | Stale branch detection with optional archival |
-| `offboard_user` | cookie | Audit + execute user departure |
-| `onboard_user` | cookie | Batch invite to teams, share files, set seat |
-| `quarterly_design_ops_report` | cookie | Seat utilization, billing, teams, library adoption |
+| `create_team` | cookie | Create a team |
+| `rename_team` | cookie | Rename a team |
+| `delete_team` | cookie | Delete a team |
 
 ## security
 
@@ -285,6 +283,23 @@ npm run build
 npm test
 ```
 
+### architecture
+
+Three-layer design: shared operations power both the CLI and MCP server.
+
+```
+src/
+  index.ts            Entry: --setup, --mcp, or CLI mode
+  mcp.ts              MCP server setup, toolset presets
+  setup.ts            Cross-platform Chrome cookie extraction
+  auth/               AuthConfig from env vars and config file
+  clients/            Axios clients for internal (cookie) and public (PAT) APIs
+  operations/         Shared business logic (18 modules)
+  tools/              MCP tool wrappers (thin, call operations)
+  cli/                CLI Commander wrappers (thin, call operations)
+  types/figma.ts      Shared types including Toolset union
+```
+
 ## license
 
 MIT

package/dist/cli/analytics.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function analyticsCommand(): Command;
+//# sourceMappingURL=analytics.d.ts.map

package/dist/cli/analytics.js

@@ -0,0 +1,48 @@
+import { Command } from 'commander';
+import { libraryUsage, componentUsage } from '../operations/analytics.js';
+import { output, error } from './format.js';
+import { requireCookie } from './helpers.js';
+export function analyticsCommand() {
+    const analytics = new Command('analytics')
+        .description('Design system analytics');
+    analytics
+        .command('library-usage <library-file-key>')
+        .description('Team-level library adoption metrics')
+        .option('--days <n>', 'Lookback period in days (default: 30)')
+        .option('--json', 'Force JSON output')
+        .action(async (libraryFileKey, options) => {
+        try {
+            const config = requireCookie();
+            const result = await libraryUsage(config, {
+                library_file_key: libraryFileKey,
+                days: options.days ? parseInt(options.days, 10) : undefined,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    analytics
+        .command('component-usage <component-key>')
+        .description('Per-file component usage analytics')
+        .option('--org-id <id>', 'Org ID override (defaults to current workspace)')
+        .option('--json', 'Force JSON output')
+        .action(async (componentKey, options) => {
+        try {
+            const config = requireCookie();
+            const result = await componentUsage(config, {
+                component_key: componentKey,
+                org_id: options.orgId,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    return analytics;
+}
+//# sourceMappingURL=analytics.js.map

package/dist/cli/branching.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function branchingCommand(): Command;
+//# sourceMappingURL=branching.d.ts.map

package/dist/cli/branching.js

@@ -0,0 +1,56 @@
+import { Command } from 'commander';
+import { listBranches, createBranch, deleteBranch } from '../operations/branching.js';
+import { output, error } from './format.js';
+import { requireAuth, requireCookie } from './helpers.js';
+export function branchingCommand() {
+    const branching = new Command('branches')
+        .description('Manage file branches');
+    branching
+        .command('list <file-key>')
+        .description('List branches of a file')
+        .option('--json', 'Force JSON output')
+        .action(async (fileKey, options) => {
+        try {
+            const config = requireAuth();
+            const result = await listBranches(config, { file_key: fileKey });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    branching
+        .command('create <file-key>')
+        .description('Create a branch from a file')
+        .requiredOption('--name <name>', 'Branch name')
+        .option('--json', 'Force JSON output')
+        .action(async (fileKey, options) => {
+        try {
+            const config = requireCookie();
+            const result = await createBranch(config, { file_key: fileKey, name: options.name });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    branching
+        .command('delete <branch-key>')
+        .description('Archive (delete) a branch')
+        .option('--json', 'Force JSON output')
+        .action(async (branchKey, options) => {
+        try {
+            const config = requireCookie();
+            await deleteBranch(config, { branch_key: branchKey });
+            output({ archived: branchKey }, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    return branching;
+}
+//# sourceMappingURL=branching.js.map

package/dist/cli/comments.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function commentsCommand(): Command;
+//# sourceMappingURL=comments.d.ts.map

package/dist/cli/comments.js

@@ -0,0 +1,86 @@
+import { Command } from 'commander';
+import { listComments, formatCommentsAsMarkdown, postComment, deleteComment, listCommentReactions, } from '../operations/comments.js';
+import { output, error } from './format.js';
+import { requirePat } from './helpers.js';
+export function commentsCommand() {
+    const comments = new Command('comments')
+        .description('Manage file comments');
+    comments
+        .command('list <file-key>')
+        .description('List comments on a file')
+        .option('--md', 'Format as markdown threads')
+        .option('--json', 'Force JSON output')
+        .action(async (fileKey, options) => {
+        try {
+            const config = requirePat();
+            const result = await listComments(config, { file_key: fileKey });
+            if (options.md) {
+                console.log(formatCommentsAsMarkdown(result));
+                return;
+            }
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    comments
+        .command('post <file-key>')
+        .description('Post a comment on a file')
+        .requiredOption('--message <text>', 'Comment text')
+        .option('--reply-to <comment-id>', 'Parent comment ID to reply to')
+        .option('--node <node-id>', 'Node ID to pin the comment to')
+        .option('--json', 'Force JSON output')
+        .action(async (fileKey, options) => {
+        try {
+            const config = requirePat();
+            const result = await postComment(config, {
+                file_key: fileKey,
+                message: options.message,
+                comment_id: options.replyTo,
+                node_id: options.node,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    comments
+        .command('delete <file-key> <comment-id>')
+        .description('Delete a comment (removes entire thread if top-level)')
+        .option('--json', 'Force JSON output')
+        .action(async (fileKey, commentId, options) => {
+        try {
+            const config = requirePat();
+            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);
+            process.exit(1);
+        }
+    });
+    comments
+        .command('reactions <file-key> <comment-id>')
+        .description('List emoji reactions on a comment')
+        .option('--json', 'Force JSON output')
+        .action(async (fileKey, commentId, options) => {
+        try {
+            const config = requirePat();
+            const result = await listCommentReactions(config, {
+                file_key: fileKey,
+                comment_id: commentId,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    return comments;
+}
+//# sourceMappingURL=comments.js.map

package/dist/cli/components.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function componentsCommand(): Command;
+//# sourceMappingURL=components.d.ts.map

package/dist/cli/components.js

@@ -0,0 +1,82 @@
+import { Command } from 'commander';
+import { listFileComponents, listFileStyles, listTeamComponents, listTeamStyles, } from '../operations/components.js';
+import { output, error } from './format.js';
+import { requirePat } from './helpers.js';
+export function componentsCommand() {
+    const components = new Command('components')
+        .description('Manage components and styles');
+    components
+        .command('list-file-components <file-key>')
+        .description('List components published from a specific file')
+        .option('--json', 'Force JSON output')
+        .action(async (fileKey, options) => {
+        try {
+            const config = requirePat();
+            const result = await listFileComponents(config, { file_key: fileKey });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    components
+        .command('list-file-styles <file-key>')
+        .description('List styles in a specific file')
+        .option('--json', 'Force JSON output')
+        .action(async (fileKey, options) => {
+        try {
+            const config = requirePat();
+            const result = await listFileStyles(config, { file_key: fileKey });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    components
+        .command('list-team-components <team-id>')
+        .description('List published components across a team')
+        .option('--page-size <n>', 'Max items per page (default: 30)')
+        .option('--cursor <cursor>', 'Pagination cursor from previous response')
+        .option('--json', 'Force JSON output')
+        .action(async (teamId, options) => {
+        try {
+            const config = requirePat();
+            const result = await listTeamComponents(config, {
+                team_id: teamId,
+                page_size: options.pageSize ? parseInt(options.pageSize, 10) : undefined,
+                cursor: options.cursor,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    components
+        .command('list-team-styles <team-id>')
+        .description('List published styles across a team')
+        .option('--page-size <n>', 'Max items per page (default: 30)')
+        .option('--cursor <cursor>', 'Pagination cursor from previous response')
+        .option('--json', 'Force JSON output')
+        .action(async (teamId, options) => {
+        try {
+            const config = requirePat();
+            const result = await listTeamStyles(config, {
+                team_id: teamId,
+                page_size: options.pageSize ? parseInt(options.pageSize, 10) : undefined,
+                cursor: options.cursor,
+            });
+            output(result, options);
+        }
+        catch (e) {
+            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            process.exit(1);
+        }
+    });
+    return components;
+}
+//# sourceMappingURL=components.js.map

package/dist/cli/compound-commands.d.ts

@@ -0,0 +1,14 @@
+import { Command } from 'commander';
+export declare function fileSummaryCommand(): Command;
+export declare function workspaceOverviewCommand(): Command;
+export declare function openCommentsCommand(): Command;
+export declare function cleanupStaleFilesCommand(): Command;
+export declare function organizeProjectCommand(): Command;
+export declare function setupProjectStructureCommand(): Command;
+export declare function seatOptimizationCommand(): Command;
+export declare function permissionAuditCommand(): Command;
+export declare function branchCleanupCommand(): Command;
+export declare function offboardUserCommand(): Command;
+export declare function onboardUserCommand(): Command;
+export declare function quarterlyReportCommand(): Command;
+//# sourceMappingURL=compound-commands.d.ts.map