figmanage 1.0.1 → 1.2.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/completion.d.ts

@@ -0,0 +1,7 @@
+import { Command } from 'commander';
+/**
+ * Create the `completion` command. Needs the parent program reference
+ * so it can introspect the full command tree at runtime.
+ */
+export declare function completionCommand(program: Command): Command;
+//# sourceMappingURL=completion.d.ts.map

package/dist/cli/completion.js

@@ -0,0 +1,160 @@
+import { Command } from 'commander';
+/**
+ * Introspect a Commander program and extract its command tree.
+ * Returns a map of command names to their subcommand names.
+ * Top-level commands without subcommands (like login, whoami) get an empty array.
+ */
+function extractCommandTree(program) {
+    const tree = new Map();
+    for (const cmd of program.commands) {
+        const subs = cmd.commands.map((sub) => sub.name());
+        tree.set(cmd.name(), subs);
+    }
+    return tree;
+}
+/**
+ * Extract all option flags from a command (including inherited ones).
+ * Returns long-form flags like --json, --help.
+ */
+function extractOptions(cmd) {
+    const flags = [];
+    for (const opt of cmd.options) {
+        if (opt.long)
+            flags.push(opt.long);
+    }
+    return flags;
+}
+/**
+ * Collect global options that appear across most commands.
+ * These get offered at every completion point.
+ */
+function extractGlobalOptions(program) {
+    const flags = new Set();
+    // Program-level options (--version, etc.)
+    for (const opt of program.options) {
+        if (opt.long)
+            flags.add(opt.long);
+    }
+    // Common flags present on subcommands
+    flags.add('--help');
+    flags.add('--json');
+    return [...flags];
+}
+function generateZshScript(program) {
+    const tree = extractCommandTree(program);
+    const globalOpts = extractGlobalOptions(program);
+    const topLevelCmds = [...tree.keys()];
+    // Build case arms for subcommand completion
+    const caseArms = [];
+    for (const [group, subs] of tree) {
+        if (subs.length > 0) {
+            caseArms.push(`      ${group})\n        local subcmds=(${subs.join(' ')})\n        _describe 'subcommand' subcmds\n        ;;`);
+        }
+    }
+    return `#compdef figmanage
+
+# Shell completion for figmanage
+# Add to ~/.zshrc: eval "$(figmanage completion)"
+
+_figmanage() {
+  local -a commands
+  commands=(${topLevelCmds.join(' ')})
+
+  local global_opts=(${globalOpts.join(' ')})
+
+  _arguments -C \\
+    '1:command:->cmd' \\
+    '2:subcommand:->sub' \\
+    '*::options:->opts'
+
+  case $state in
+    cmd)
+      _describe 'command' commands
+      ;;
+    sub)
+      case $words[1] in
+${caseArms.join('\n')}
+      *)
+        _describe 'option' global_opts
+        ;;
+      esac
+      ;;
+    opts)
+      _values 'options' $global_opts
+      ;;
+  esac
+}
+
+compdef _figmanage figmanage
+`;
+}
+function generateBashScript(program) {
+    const tree = extractCommandTree(program);
+    const globalOpts = extractGlobalOptions(program);
+    const topLevelCmds = [...tree.keys()];
+    // Build case arms for subcommand completion
+    const caseArms = [];
+    for (const [group, subs] of tree) {
+        if (subs.length > 0) {
+            caseArms.push(`      ${group})\n        COMPREPLY=($(compgen -W "${subs.join(' ')}" -- "$cur"))\n        ;;`);
+        }
+    }
+    return `# Shell completion for figmanage
+# Add to ~/.bashrc: eval "$(figmanage completion)"
+
+_figmanage() {
+  local cur prev words cword
+  _init_completion || return
+
+  local commands="${topLevelCmds.join(' ')}"
+  local global_opts="${globalOpts.join(' ')}"
+
+  case $cword in
+    1)
+      COMPREPLY=($(compgen -W "$commands" -- "$cur"))
+      ;;
+    2)
+      case "\${words[1]}" in
+${caseArms.join('\n')}
+      *)
+        COMPREPLY=($(compgen -W "$global_opts" -- "$cur"))
+        ;;
+      esac
+      ;;
+    *)
+      COMPREPLY=($(compgen -W "$global_opts" -- "$cur"))
+      ;;
+  esac
+}
+
+complete -F _figmanage figmanage
+`;
+}
+function detectShell() {
+    const shell = process.env.SHELL ?? '';
+    if (shell.endsWith('/zsh'))
+        return 'zsh';
+    return 'bash';
+}
+/**
+ * Create the `completion` command. Needs the parent program reference
+ * so it can introspect the full command tree at runtime.
+ */
+export function completionCommand(program) {
+    const cmd = new Command('completion')
+        .description('Output shell completion script')
+        .option('--shell <shell>', 'Shell type (bash or zsh)')
+        .action((options) => {
+        const shell = options.shell ?? detectShell();
+        if (shell !== 'bash' && shell !== 'zsh') {
+            console.error(`Unsupported shell: ${shell}. Use --shell bash or --shell zsh.`);
+            process.exit(1);
+        }
+        const script = shell === 'zsh'
+            ? generateZshScript(program)
+            : generateBashScript(program);
+        process.stdout.write(script);
+    });
+    return cmd;
+}
+//# sourceMappingURL=completion.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