figmanage 0.2.1 → 1.0.0

package/README.md

@@ -1,144 +1,127 @@
 # figmanage
 
-MCP server for managing your Figma workspace.
+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.
 
-Manages Figma workspaces through AI assistants. 79 tools covering files, projects, teams, permissions, comments, versions, components, webhooks, org admin, and more. Works with Claude Code, Claude Desktop, ChatGPT, and any MCP-compatible client.
+## install
 
-## quick start
-
-### PAT only (30 seconds)
+```bash
+npm install -g figmanage
+```
 
-Get a token at [figma.com/settings](https://www.figma.com/settings) > Security > Personal access tokens, then:
+## setup
 
 ```bash
-claude mcp add figmanage -s user -e FIGMA_PAT=figd_xxx -- npx -y figmanage
+figmanage login
 ```
 
-Restart Claude Code. Gives you 30+ tools (comments, reading, export, components, versions, webhooks).
-
-### full setup (2 minutes, all 79 tools)
+Extracts your Chrome session cookie, prompts for a PAT, and stores credentials locally at `~/.config/figmanage/`. One-time setup -- no env vars, no JSON config editing.
 
 ```bash
-npx -y figmanage --setup
+figmanage whoami    # verify auth
+figmanage logout    # clear credentials
 ```
 
-Extracts your Chrome cookie, prompts for a PAT, registers with Claude Code automatically. Unlocks all 79 tools including workspace management, permissions, and org admin. Restart Claude Code.
+## usage
 
-Use `--no-prompt --pat figd_xxx` for non-interactive setup.
+```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
+```
 
-### Claude Desktop / Cowork
+All commands output JSON when piped or when `--json` is passed.
 
-Full setup with cookie extraction:
+## AI integration (MCP)
 
-```bash
-npx -y figmanage --setup --desktop
-```
+figmanage runs as an MCP server for Claude, ChatGPT, Cursor, and other AI assistants:
 
-Or manually add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+```bash
+# Claude Code
+claude mcp add figmanage -- npx -y figmanage --mcp
 
-```json
+# Claude Desktop / Cowork
+# Add to claude_desktop_config.json:
 {
   "mcpServers": {
     "figmanage": {
       "command": "npx",
-      "args": ["-y", "figmanage"],
-      "env": {
-        "FIGMA_PAT": "figd_your_token_here"
-      }
+      "args": ["-y", "figmanage", "--mcp"]
     }
   }
 }
 ```
 
-## configuration
+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.
 
-| Env var | Description |
-|---------|-------------|
-| `FIGMA_PAT` | Personal access token |
-| `FIGMA_AUTH_COOKIE` | Session cookie value |
-| `FIGMA_USER_ID` | Your Figma user ID |
-| `FIGMA_ORG_ID` | Your org ID |
-| `FIGMA_TOOLSETS` | Toolset filter or preset name |
-| `FIGMA_READ_ONLY` | Set to `1` to disable mutations |
+MCP mode exposes all 85 tools to the AI assistant. HTTP transport available via `--mcp --http <port>`.
 
-The setup script stores credentials as env vars in the MCP server config. You can also set them manually.
+### toolset presets (MCP only)
 
-### toolset presets
+Use `FIGMA_TOOLSETS` to expose only specific tool groups:
 
-Use `FIGMA_TOOLSETS` to expose only the tool groups you need. Presets bundle common combinations:
-
-| Preset | Toolsets included |
-|--------|-------------------|
+| Preset | Toolsets |
+|--------|----------|
 | `starter` | navigate, reading, comments, export |
 | `admin` | navigate, org, permissions, analytics, teams, libraries |
 | `readonly` | navigate, reading, comments, export, components, versions |
 | `full` | everything (default) |
 
-Or pass individual toolsets:
-
-```bash
-FIGMA_TOOLSETS=navigate,reading,comments
-```
-
-Available toolsets: `navigate`, `files`, `projects`, `permissions`, `org`, `versions`, `branching`, `comments`, `export`, `analytics`, `reading`, `components`, `webhooks`, `variables`, `compound`, `teams`, `libraries`.
-
-### multi-org support
-
-`list_orgs` discovers all available orgs. `switch_org` changes the active workspace for the session. 12 tools accept an `org_id` override parameter for one-off cross-org queries without switching.
-
 ## auth
 
-figmanage uses two API clients targeting different Figma endpoints:
+figmanage uses two Figma API surfaces:
 
-| Client | Base URL | Auth | Capabilities |
-|--------|----------|------|-------------|
-| Internal API | `www.figma.com` | Session cookie | Workspace management, search, permissions, org admin, file lifecycle |
-| Public API | `api.figma.com` | Personal Access Token | Comments, export, file reading, components, versions, webhooks, variables |
+| Client | Auth | Capabilities |
+|--------|------|-------------|
+| 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 |
 
-Each tool declares its auth requirement:
+Cookie auth unlocks all 85 tools. PAT-only gives ~30 (reading, comments, export, components). Both together is recommended.
 
-| Requirement | Meaning |
-|-------------|---------|
-| `cookie` | Internal API only. Needs `FIGMA_AUTH_COOKIE` + `FIGMA_USER_ID`. |
-| `pat` | Public API only. Needs `FIGMA_PAT`. |
-| `either` | Works with whichever auth is available. Prefers public API when PAT present. |
+Auth resolution: env vars > config file > prompt to run `figmanage login`.
 
-Tools are automatically filtered at startup based on available credentials. If you only have a PAT, cookie-only tools are not registered.
+## commands
 
-## tools
+### navigate (10)
 
-### navigate (10 tools)
-
-| Tool | Auth | Description |
-|------|------|-------------|
+| Command | Auth | Description |
+|---------|------|-------------|
 | `check_auth` | either | Validate PAT and cookie authentication |
-| `list_orgs` | cookie | List available Figma workspaces (orgs) with names |
+| `list_orgs` | cookie | List available Figma workspaces |
 | `switch_org` | cookie | Switch active workspace for this session |
 | `list_teams` | cookie | List teams in your org |
 | `list_projects` | either | List projects in a team |
-| `list_files` | either | List files in a project (paginated) |
-| `list_recent_files` | cookie | Recently viewed/edited files across teams |
+| `list_files` | either | List files in a project |
+| `list_recent_files` | cookie | Recently viewed/edited files |
 | `search` | cookie | Search files across the workspace |
 | `get_file_info` | either | File metadata: name, project, team, link access |
-| `list_favorites` | cookie | List favorited files (broken -- see known limitations) |
+| `list_favorites` | cookie | Favorited files (broken -- Figma BigInt bug) |
 
-### files (8 tools)
+### files (8)
 
-| Tool | Auth | Description |
-|------|------|-------------|
+| Command | Auth | Description |
+|---------|------|-------------|
 | `create_file` | cookie | Create design, whiteboard, slides, or sites file |
 | `rename_file` | cookie | Rename a file |
 | `move_files` | cookie | Move files between projects (batch) |
-| `duplicate_file` | cookie | Copy a file, optionally to another project |
+| `duplicate_file` | cookie | Copy a file |
 | `trash_files` | cookie | Move files to trash (batch) |
 | `restore_files` | cookie | Restore files from trash (batch) |
-| `favorite_file` | cookie | Add/remove file from sidebar favorites |
-| `set_link_access` | cookie | Set link sharing level (inherit/view/edit/org_view/org_edit) |
+| `favorite_file` | cookie | Add/remove from favorites |
+| `set_link_access` | cookie | Set link sharing level |
 
-### projects (6 tools)
+### projects (6)
 
-| Tool | Auth | Description |
-|------|------|-------------|
+| Command | Auth | Description |
+|---------|------|-------------|
 | `create_project` | cookie | Create a project in a team |
 | `rename_project` | cookie | Rename a project |
 | `move_project` | cookie | Move a project to another team |
@@ -146,206 +129,151 @@ Tools are automatically filtered at startup based on available credentials. If y
 | `restore_project` | cookie | Restore a project from trash |
 | `set_project_description` | cookie | Set or update project description |
 
-### permissions (7 tools)
+### permissions (7)
 
-| Tool | Auth | Description |
-|------|------|-------------|
-| `get_permissions` | cookie | List who has access to a file/project/team with roles |
+| Command | Auth | Description |
+|---------|------|-------------|
+| `get_permissions` | cookie | List who has access with roles |
 | `set_permissions` | cookie | Change a user's access level |
-| `share` | cookie | Invite someone by email (viewer or editor) |
+| `share` | cookie | Invite someone by email |
 | `revoke_access` | cookie | Remove someone's access |
-| `list_role_requests` | cookie | List pending file access requests |
+| `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 tools)
+### reading (2)
 
-| Tool | Auth | Description |
-|------|------|-------------|
-| `get_file` | pat | Read file contents as a node tree with depth control |
-| `get_nodes` | pat | Read specific nodes by ID from a file |
+| 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 tools)
+### components (4)
 
-| Tool | Auth | Description |
-|------|------|-------------|
-| `list_file_components` | pat | List components published from a file |
-| `list_file_styles` | pat | List styles in a file |
-| `list_team_components` | pat | List published components across a team (paginated) |
-| `list_team_styles` | pat | List published styles across a team (paginated) |
+| 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 |
 
-### versions (2 tools)
+### versions (2)
 
-| Tool | Auth | Description |
-|------|------|-------------|
-| `list_versions` | pat | List version history (named checkpoints and auto-saves) |
+| Command | Auth | Description |
+|---------|------|-------------|
+| `list_versions` | pat | Version history |
 | `create_version` | cookie | Create a named version checkpoint |
 
-### branching (3 tools)
+### branching (3)
 
-| Tool | Auth | Description |
-|------|------|-------------|
+| Command | Auth | Description |
+|---------|------|-------------|
 | `list_branches` | either | List branches of a file |
-| `create_branch` | cookie | Create a branch from a file |
-| `delete_branch` | cookie | Archive (delete) a branch |
+| `create_branch` | cookie | Create a branch |
+| `delete_branch` | cookie | Archive a branch |
 
-### comments (4 tools)
+### comments (4)
 
-| Tool | Auth | Description |
-|------|------|-------------|
-| `list_comments` | pat | List comments with thread structure (optional markdown format) |
-| `post_comment` | pat | Post a comment, optionally pinned to a node or as a reply |
-| `delete_comment` | pat | Permanently delete a comment |
-| `list_comment_reactions` | pat | List emoji reactions on a comment |
+| Command | Auth | Description |
+|---------|------|-------------|
+| `list_comments` | pat | Comments with thread structure |
+| `post_comment` | pat | Post a comment |
+| `delete_comment` | pat | Delete a comment |
+| `list_comment_reactions` | pat | Emoji reactions on a comment |
 
-### export (2 tools)
+### export (2)
 
-| Tool | Auth | Description |
-|------|------|-------------|
-| `export_nodes` | pat | Export nodes as PNG, SVG, PDF, or JPG (returns temporary URLs) |
-| `get_image_fills` | pat | Get URLs for all images used as fills in a file |
+| Command | Auth | Description |
+|---------|------|-------------|
+| `export_nodes` | pat | Export as PNG, SVG, PDF, or JPG |
+| `get_image_fills` | pat | URLs for all images used as fills |
 
-### webhooks (4 tools)
+### webhooks (4)
 
-| Tool | Auth | Description |
-|------|------|-------------|
+| Command | Auth | Description |
+|---------|------|-------------|
 | `list_webhooks` | pat | List webhooks for a team |
-| `create_webhook` | pat | Create a webhook subscription for a team |
-| `update_webhook` | pat | Update a webhook (endpoint, event type, status) |
+| `create_webhook` | pat | Create a webhook subscription |
+| `update_webhook` | pat | Update a webhook |
 | `delete_webhook` | pat | Delete a webhook |
 
-### variables (3 tools, Enterprise only)
-
-| Tool | Auth | Description |
-|------|------|-------------|
-| `list_local_variables` | pat | List local variables and collections in a file |
-| `list_published_variables` | pat | List published variables from a library file |
-| `update_variables` | pat | Bulk create, update, or delete variables, collections, modes, and values |
-
-### analytics (2 tools)
-
-| Tool | Auth | Description |
-|------|------|-------------|
-| `library_usage` | cookie | Team-level library adoption metrics over a lookback period |
-| `component_usage` | cookie | Per-file component usage analytics |
-
-### org (12 tools)
-
-| Tool | Auth | Description |
-|------|------|-------------|
-| `list_admins` | cookie | Org admins with permission levels and seat status |
-| `list_org_teams` | cookie | All teams with member counts, project counts, access levels |
-| `seat_usage` | cookie | Seat breakdown: permissions, seat types, activity, account types |
-| `list_team_members` | cookie | Team members with name, email, role, last active date |
-| `list_org_members` | cookie | List org members with seat type, permission, email, last active |
-| `contract_rates` | cookie | Seat pricing per product (expert, developer, collaborator) |
-| `change_seat` | cookie | Change a user's seat type (confirm flag required for upgrades) |
-| `billing_overview` | cookie | Invoice history, billing status, amounts, billing periods |
+### variables (3, Enterprise)
+
+| Command | Auth | Description |
+|---------|------|-------------|
+| `list_local_variables` | pat | Local variables and collections |
+| `list_published_variables` | pat | Published variables from a library |
+| `update_variables` | pat | Bulk create, update, or delete variables |
+
+### analytics (2)
+
+| Command | Auth | Description |
+|---------|------|-------------|
+| `library_usage` | cookie | Team-level library adoption metrics |
+| `component_usage` | cookie | Per-file component usage |
+
+### org (12)
+
+| Command | Auth | Description |
+|---------|------|-------------|
+| `list_admins` | cookie | Org admins with permission levels |
+| `list_org_teams` | cookie | All teams with member and project counts |
+| `seat_usage` | cookie | Seat breakdown by type and activity |
+| `list_team_members` | cookie | Team members with roles and activity |
+| `list_org_members` | cookie | All org members with seats and activity |
+| `contract_rates` | cookie | Per-seat pricing |
+| `change_seat` | cookie | Change a user's seat type |
+| `billing_overview` | cookie | Invoice history and billing status |
 | `list_invoices` | cookie | Open and upcoming invoices |
-| `org_domains` | cookie | Domain configuration and SSO/SAML settings |
-| `ai_credit_usage` | cookie | AI credit usage summary for a billing plan |
-| `export_members` | cookie | Trigger async CSV export of all org members (emailed to admin) |
+| `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 tools)
+### teams (3)
 
-| Tool | Auth | Description |
-|------|------|-------------|
-| `create_team` | cookie | Create a new team in the org |
-| `rename_team` | cookie | Rename an existing team |
-| `delete_team` | cookie | Delete a team (destructive, cannot be undone) |
+| Command | Auth | Description |
+|---------|------|-------------|
+| `create_team` | cookie | Create a team |
+| `rename_team` | cookie | Rename a team |
+| `delete_team` | cookie | Delete a team |
 
-### libraries (1 tool)
+### libraries (1)
 
-| Tool | Auth | Description |
-|------|------|-------------|
-| `list_org_libraries` | cookie | All design system libraries in the org with sharing group info |
+| Command | Auth | Description |
+|---------|------|-------------|
+| `list_org_libraries` | cookie | Design system libraries with sharing info |
 
-### compound (6 tools)
+### compound (12)
 
 Multi-step operations that aggregate data from several API calls.
 
-| Tool | Auth | Description |
-|------|------|-------------|
-| `file_summary` | pat | Quick overview: pages, components, styles, comment counts |
-| `workspace_overview` | cookie | Full org snapshot: teams, seats, billing in one call |
-| `open_comments` | pat | Aggregated unresolved comments across all files in a project |
-| `cleanup_stale_files` | either | Find files not modified in N days, optionally trash them (dry run by default) |
-| `organize_project` | cookie | Batch-move files into a target project |
-| `setup_project_structure` | cookie | Create multiple projects in a team from a plan |
-
-## transport modes
-
-| Mode | Flag | Use case |
-|------|------|----------|
-| stdio | (default) | Claude Code, Claude Desktop, most MCP clients |
-| HTTP | `--http <port>` | ChatGPT, web-based clients |
-
-```bash
-npx figmanage              # stdio
-npx figmanage --http 3333  # HTTP on port 3333
-```
+| 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 |
 
 ## security
 
-### ID validation
-
-All tool parameters that accept Figma IDs (file keys, team IDs, project IDs, node IDs) are validated against a strict regex (`/^[\w.:-]+$/`) before use. This blocks path traversal in URL templates.
-
-### safe retry policy
-
-Both API clients retry on transient errors with exponential backoff. Rate limit responses (429) are only retried for safe methods (`GET`, `HEAD`, `OPTIONS`). Mutations are never retried on 429 to prevent duplicate writes. Auth failures (401, 403) are never retried.
-
-### response shaping
-
-Org admin tools extract documented fields and strip PII (e.g., `shipping_address` is removed from billing responses).
-
-## architecture
-
-```
-src/
-  index.ts              MCP server entry point (stdio transport, toolset parsing)
-  setup.ts              Chrome cookie extraction + Claude MCP config
-  auth/
-    client.ts           AuthConfig, env var loading
-    health.ts           Auth validation
-  clients/
-    internal-api.ts     Axios client for www.figma.com (cookie auth, safe retry)
-    public-api.ts       Axios client for api.figma.com (PAT auth, safe retry)
-  tools/
-    register.ts         defineTool() pattern, toolset filtering, read-only mode, figmaId validation
-    navigate.ts         Browse and search (10 tools)
-    files.ts            File lifecycle (8 tools)
-    projects.ts         Project management (6 tools)
-    permissions.ts      Sharing, access control, role requests (7 tools)
-    reading.ts          File and node reading via public API (2 tools)
-    components.ts       Components and styles via public API (4 tools)
-    versions.ts         Version history (2 tools)
-    branching.ts        Branch CRUD (3 tools)
-    comments.ts         Comments and reactions via public API (4 tools)
-    export.ts           Image export and fills via public API (2 tools)
-    webhooks.ts         Webhook CRUD via V2 public API (4 tools)
-    variables.ts        Variables via public API, Enterprise only (3 tools)
-    analytics.ts        Library and component analytics via internal API (2 tools)
-    org.ts              Org admin, billing, seats, domains via internal API (9 tools)
-    teams.ts            Team CRUD (3 tools)
-    libraries.ts        Design system libraries via internal API (1 tool)
-    compound.ts         Multi-step aggregation tools (6 tools)
-  types/
-    figma.ts            Shared types (Toolset, AuthConfig, etc.)
-```
-
-Tools self-register via `defineTool()` side-effect imports. Each tool declares its toolset, auth requirement, and whether it mutates. `registerTools()` filters at startup based on available credentials, enabled toolsets, and read-only mode.
+All parameters that accept Figma IDs are validated against `/^[\w.:-]+$/` before use. Rate limit retries are restricted to safe HTTP methods. Mutations are never retried. Billing responses strip PII. Destructive operations default to dry-run mode. Config file is stored with 0o600 permissions.
 
 ## known limitations
 
-- **list_favorites**: Figma's server has a BigInt overflow bug on large user IDs. The `favorite_file` tool for adding/removing favorites works fine.
-- **Branch merging**: Figma merges branches through its real-time multiplayer protocol, not a REST endpoint. Must be done in the Figma UI.
-- **Cookie expiry**: Session cookies expire roughly every 30 days. Re-run `npm run setup` to refresh.
-- **Windows cookie extraction**: Best-effort via DPAPI/PowerShell. Falls back to PAT-only setup if extraction fails.
-- **Variables require Enterprise**: The `file_variables:read` and `file_variables:write` scopes are not available in the standard PAT UI. Variables tools return a clear error on non-Enterprise plans.
-- **No org-level member list**: There is no single REST endpoint to list all org members. Use `list_admins` + `list_team_members` per team, or `export_members` for a full CSV.
-- **No activity log API**: Figma's activity log is SSR only with no REST endpoint.
-- **get_file returns full tree**: Without a `depth` parameter, `get_file` returns the entire document. Use `depth` or `get_nodes` for large files.
+- **list_favorites**: Figma BigInt overflow bug on their server. `favorite_file` works fine.
+- **Branch merging**: Requires Figma's multiplayer protocol, no REST endpoint.
+- **Cookie expiry**: ~30 days. Run `figmanage login --refresh` to renew.
+- **Windows cookies**: Best-effort DPAPI extraction. Falls back to PAT-only.
+- **Variables**: Enterprise-gated scopes.
+- **get_file**: Returns full document tree. Use `depth` param or `get_nodes`.
 
 ## development
 
@@ -353,11 +281,8 @@ Tools self-register via `defineTool()` side-effect imports. Each tool declares i
 git clone https://github.com/dannykeane/figmanage.git
 cd figmanage
 npm install
-npm run build    # compile
-npm run setup    # configure auth + MCP client
-npm run dev      # watch mode
-npm run lint     # type-check
-npm test         # run tests
+npm run build
+npm test
 ```
 
 ## license

package/dist/auth/client.d.ts

@@ -9,6 +9,22 @@ export interface AuthConfig {
     orgId?: string;
     orgs?: OrgEntry[];
 }
+/**
+ * Load auth from environment variables. This is the original path --
+ * env vars set by MCP client config or shell.
+ */
+export declare function loadFromEnv(): AuthConfig;
+/**
+ * Load auth from the config file's active workspace.
+ * Returns null if no config file or active workspace found.
+ */
+export declare function loadFromConfigFile(): AuthConfig | null;
+/**
+ * Load auth config with fallback chain:
+ * 1. Environment variables (backwards compatible)
+ * 2. Config file (~/.config/figmanage/config.json)
+ * 3. Empty config (caller decides what to do)
+ */
 export declare function loadAuthConfig(): AuthConfig;
 export declare function hasPat(config: AuthConfig): boolean;
 export declare function hasCookie(config: AuthConfig): boolean;

package/dist/auth/client.js

@@ -1,3 +1,4 @@
+import { getActiveWorkspace } from '../config.js';
 function parseOrgs(raw) {
     if (!raw)
         return undefined;
@@ -11,7 +12,11 @@ function parseOrgs(raw) {
         return undefined;
     }
 }
-export function loadAuthConfig() {
+/**
+ * Load auth from environment variables. This is the original path --
+ * env vars set by MCP client config or shell.
+ */
+export function loadFromEnv() {
     return {
         pat: process.env.FIGMA_PAT,
         cookie: process.env.FIGMA_AUTH_COOKIE,
@@ -20,6 +25,44 @@ export function loadAuthConfig() {
         orgs: parseOrgs(process.env.FIGMA_ORGS),
     };
 }
+/**
+ * Load auth from the config file's active workspace.
+ * Returns null if no config file or active workspace found.
+ */
+export function loadFromConfigFile() {
+    const workspace = getActiveWorkspace();
+    if (!workspace)
+        return null;
+    // Only return if the workspace has usable credentials
+    const hasCreds = workspace.pat || (workspace.cookie && workspace.user_id);
+    if (!hasCreds)
+        return null;
+    return {
+        pat: workspace.pat,
+        cookie: workspace.cookie,
+        userId: workspace.user_id,
+        orgId: workspace.org_id,
+    };
+}
+/**
+ * Load auth config with fallback chain:
+ * 1. Environment variables (backwards compatible)
+ * 2. Config file (~/.config/figmanage/config.json)
+ * 3. Empty config (caller decides what to do)
+ */
+export function loadAuthConfig() {
+    // Env vars take precedence -- backwards compatible
+    const envConfig = loadFromEnv();
+    if (envConfig.pat || (envConfig.cookie && envConfig.userId)) {
+        return envConfig;
+    }
+    // Fall back to config file
+    const fileConfig = loadFromConfigFile();
+    if (fileConfig)
+        return fileConfig;
+    // Return env config as-is (empty or partial)
+    return envConfig;
+}
 export function hasPat(config) {
     return !!config.pat;
 }

package/dist/auth/cookie.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Chrome cookie extraction and Figma session validation.
+ *
+ * Extracted from setup.ts so both the setup flow and the CLI login
+ * command can reuse this logic.
+ */
+export interface ParsedCookie {
+    userId: string;
+    token: string;
+    cookieValue: string;
+}
+export declare function parseCookieValue(raw: string): ParsedCookie;
+export interface SessionInfo {
+    orgId: string;
+    orgs: {
+        id: string;
+        name: string;
+    }[];
+    teams: {
+        id: string;
+        name: string;
+    }[];
+}
+export declare function validateSession(cookieValue: string, userId: string): Promise<SessionInfo>;
+export declare function validatePat(pat: string): Promise<string>;
+export interface FigmaAccount {
+    userId: string;
+    cookieValue: string;
+    profile: string;
+}
+/**
+ * Extract Figma auth cookies from all Chrome profiles.
+ * Returns an array of accounts found (may be empty on Windows failure).
+ * Throws on non-Windows platforms if no Chrome profiles exist.
+ */
+export declare function extractCookies(): FigmaAccount[];
+//# sourceMappingURL=cookie.d.ts.map