figma-cli 0.3.0__tar.gz → 0.3.1__tar.gz

{figma_cli-0.3.0 → figma_cli-0.3.1}/.github/workflows/ci.yml

@@ -30,14 +30,19 @@ jobs:
         run: pytest tests/
 
   live:
-    # Runs against the real Figma API when the FIGMA_TOKEN secret is configured;
-    # the tests skip cleanly when it is absent (forks, unconfigured repos).
+    # Runs against the real Figma API when the FIGMA_TOKEN (and, for OAuth, the
+    # FIGMA_OAUTH_REFRESH_TOKEN, FIGMA_CLIENT_ID and FIGMA_CLIENT_SECRET) secrets are
+    # configured; the tests skip cleanly when they are absent (forks, unconfigured).
     runs-on: ubuntu-latest
     needs: test
     env:
       FIGMA_TOKEN: ${{ secrets.FIGMA_TOKEN }}
       FIGMA_TEST_FILE_KEY: ${{ vars.FIGMA_TEST_FILE_KEY }}
       FIGMA_TEST_NODE_ID: ${{ vars.FIGMA_TEST_NODE_ID }}
+      # A dedicated test OAuth app: each refresh invalidates its last access token.
+      FIGMA_OAUTH_REFRESH_TOKEN: ${{ secrets.FIGMA_OAUTH_REFRESH_TOKEN }}
+      FIGMA_CLIENT_ID: ${{ secrets.FIGMA_CLIENT_ID }}
+      FIGMA_CLIENT_SECRET: ${{ secrets.FIGMA_CLIENT_SECRET }}
     steps:
       - uses: actions/checkout@v5
         with:

{figma_cli-0.3.0 → figma_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: figma-cli
-Version: 0.3.0
+Version: 0.3.1
 Summary: Headless Figma CLI for AI coding agents and automated design inspection.
 Project-URL: Homepage, https://github.com/imperfect-co/figma-cli
 Project-URL: Issues, https://github.com/imperfect-co/figma-cli/issues
@@ -49,7 +49,7 @@ The npm package `silships/figma-cli` also installs a `figma-cli` executable. If
 
 ## Usage
 
-Every command talks to the Figma REST API with a personal access token. Create one under Figma account settings (Security > Personal access tokens) with these scopes, the minimum the commands below need per [Figma's scope reference](https://developers.figma.com/docs/rest-api/scopes/):
+Every command talks to the Figma REST API with either a personal access token or an OAuth token from your own Figma OAuth app (see [OAuth login](#oauth-login)). Create a personal access token under Figma account settings (Security > Personal access tokens) with these scopes, the minimum the commands below need per [Figma's scope reference](https://developers.figma.com/docs/rest-api/scopes/):
 
 | Scope | Used by |
 | --- | --- |
@@ -68,20 +68,43 @@ figma auth login --token - < token.txt # same, explicit
 
 `auth login` validates the token against `GET /v1/me` before writing anything. A rejected token exits 3 and leaves any existing token file untouched. A valid one is written to `~/.config/figma/token` with mode `0600` (its directory `0700`), through a temporary file renamed into place, so a failed write keeps the previous token, and the command reports the authenticated `id`, `handle` and `email` plus the file path. Prefer stdin over `--token <value>`, which exposes the token in process listings and shell history. Empty stdin exits 2. Add `--no-browser` to skip opening the settings page.
 
-Alternatively, export the token. `FIGMA_TOKEN` takes precedence over the stored file whenever it is set and non-empty:
+`auth login` takes this personal access token path whenever `--token` is given, stdin is piped, or no OAuth client credentials are configured. Saving a personal access token also removes `~/.config/figma/token.json`, so stale OAuth tokens never shadow it.
+
+Alternatively, export the token. `FIGMA_TOKEN` takes precedence over the stored files whenever it is set and non-empty. A value starting `figu_` (an OAuth access token) is sent as `Authorization: Bearer`, anything else as `X-Figma-Token`:
 
 ```sh
 export FIGMA_TOKEN=figd_...
 export FIGMA_API_BASE=https://api.figma.com   # optional, this is the default
 ```
 
-With neither set, commands fail with `{"error": "missing_token"}` and exit code 3.
+Credentials resolve in this order: `FIGMA_TOKEN`, then `~/.config/figma/token.json` (OAuth), then `~/.config/figma/token` (personal access token). With none of them, commands fail with `{"error": "missing_token"}` and exit code 3.
+
+### OAuth login
+
+figma-cli ships no OAuth app of its own: Figma authenticates the client with its secret on every token call, and a secret embedded in an open-source package is not a secret. Bring your own:
+
+1. Create an OAuth app in the [Figma developer console](https://www.figma.com/developers/apps) and register the redirect URL `http://127.0.0.1:54321/callback`. Grant it the four scopes above.
+2. Export its credentials and log in from an interactive terminal:
+
+```sh
+export FIGMA_CLIENT_ID=...
+export FIGMA_CLIENT_SECRET=...
+figma auth login                 # opens the browser, waits on 127.0.0.1:54321
+figma auth login --port 8765     # if you registered http://127.0.0.1:8765/callback instead
+```
+
+`--client-id` and `--client-secret` override the variables, but a literal secret shows in process listings and shell history. The flow uses PKCE (S256) and a random `state`; a callback with the wrong `state` is answered with HTTP 400 and ignored. Because Figma matches redirect URLs exactly, a busy port is not swapped for another one: the command exits 2 with `{"error": "port_unavailable"}`. Add `--no-browser` to print the authorization URL without opening it.
+
+Over SSH, in a container, or anywhere the browser runs on another machine, its redirect to `127.0.0.1` never reaches figma-cli. While it waits, the command reads the terminal: after authorizing, copy the full URL from the browser's address bar (the page itself fails to load) and paste it at the `Paste the callback URL here` prompt. A `code=...&state=...` query string works too. The paste is held to the same checks as the browser redirect: the path must be `/callback` on the configured port and `state` must match, so a bare code without `state` is refused. A rejected paste is explained and the prompt returns while the loopback server keeps listening.
+
+The access token is checked against `GET /v1/me`, then the access token, refresh token, expiry, client id and client secret are written to `~/.config/figma/token.json` (mode `0600`, directory `0700`, atomic replace). Figma access tokens last 90 days. When the stored one has expired, the next command refreshes it through `POST /v1/oauth/refresh` before running. The refresh holds an advisory lock on `~/.config/figma/token.json.lock` and re-reads the file once it has the lock, so concurrent commands refresh once rather than invalidating each other's tokens (Windows has no `fcntl`, so there the refresh runs unlocked). A refresh Figma rejects exits 3 with `{"error": "refresh_failed"}` rather than falling back to an older personal access token; run `figma auth login` again.
 
 Every subcommand prints human-readable text by default and a JSON document on stdout with `--json`.
 
 | Command | Figma endpoint |
 | --- | --- |
 | `figma auth login [--token TOKEN\|-] [--no-browser]` | `GET /v1/me`, then writes `~/.config/figma/token` |
+| `figma auth login [--client-id ID] [--client-secret SECRET] [--port PORT]` | OAuth: `POST /v1/oauth/token`, `GET /v1/me`, then writes `~/.config/figma/token.json` |
 | `figma auth check` | `GET /v1/me` |
 | `figma file get <file_key> [--depth N]` | `GET /v1/files/{file_key}?depth=N` |
 | `figma export <file_key> --nodes <ids> [--format png\|svg] [--output DIR]` | `GET /v1/images/{file_key}`, then the asset URLs |
@@ -150,7 +173,7 @@ HTTP 429 is reported at once, never retried, so the caller decides when to try a
 
 ### Token safety
 
-A request carrying `X-Figma-Token` follows no redirects. Any 3xx answer is refused with `{"error": "redirect_refused"}` and exit code 3 before a second request is made, so the token never reaches another host. Exported images are downloaded from the pre-signed URLs Figma returns with a separate request that carries no token; only that request follows redirects.
+A request carrying a credential (`X-Figma-Token`, `Authorization: Bearer`, or the `Authorization: Basic` client credentials on the OAuth token calls) follows no redirects. Any 3xx answer is refused with `{"error": "redirect_refused"}` and exit code 3 before a second request is made, so the credential never reaches another host. Exported images are downloaded from the pre-signed URLs Figma returns with a separate request that carries no token; only that request follows redirects.
 
 ## Installation and quick run
 

{figma_cli-0.3.0 → figma_cli-0.3.1}/README.md

@@ -24,7 +24,7 @@ The npm package `silships/figma-cli` also installs a `figma-cli` executable. If
 
 ## Usage
 
-Every command talks to the Figma REST API with a personal access token. Create one under Figma account settings (Security > Personal access tokens) with these scopes, the minimum the commands below need per [Figma's scope reference](https://developers.figma.com/docs/rest-api/scopes/):
+Every command talks to the Figma REST API with either a personal access token or an OAuth token from your own Figma OAuth app (see [OAuth login](#oauth-login)). Create a personal access token under Figma account settings (Security > Personal access tokens) with these scopes, the minimum the commands below need per [Figma's scope reference](https://developers.figma.com/docs/rest-api/scopes/):
 
 | Scope | Used by |
 | --- | --- |
@@ -43,20 +43,43 @@ figma auth login --token - < token.txt # same, explicit
 
 `auth login` validates the token against `GET /v1/me` before writing anything. A rejected token exits 3 and leaves any existing token file untouched. A valid one is written to `~/.config/figma/token` with mode `0600` (its directory `0700`), through a temporary file renamed into place, so a failed write keeps the previous token, and the command reports the authenticated `id`, `handle` and `email` plus the file path. Prefer stdin over `--token <value>`, which exposes the token in process listings and shell history. Empty stdin exits 2. Add `--no-browser` to skip opening the settings page.
 
-Alternatively, export the token. `FIGMA_TOKEN` takes precedence over the stored file whenever it is set and non-empty:
+`auth login` takes this personal access token path whenever `--token` is given, stdin is piped, or no OAuth client credentials are configured. Saving a personal access token also removes `~/.config/figma/token.json`, so stale OAuth tokens never shadow it.
+
+Alternatively, export the token. `FIGMA_TOKEN` takes precedence over the stored files whenever it is set and non-empty. A value starting `figu_` (an OAuth access token) is sent as `Authorization: Bearer`, anything else as `X-Figma-Token`:
 
 ```sh
 export FIGMA_TOKEN=figd_...
 export FIGMA_API_BASE=https://api.figma.com   # optional, this is the default
 ```
 
-With neither set, commands fail with `{"error": "missing_token"}` and exit code 3.
+Credentials resolve in this order: `FIGMA_TOKEN`, then `~/.config/figma/token.json` (OAuth), then `~/.config/figma/token` (personal access token). With none of them, commands fail with `{"error": "missing_token"}` and exit code 3.
+
+### OAuth login
+
+figma-cli ships no OAuth app of its own: Figma authenticates the client with its secret on every token call, and a secret embedded in an open-source package is not a secret. Bring your own:
+
+1. Create an OAuth app in the [Figma developer console](https://www.figma.com/developers/apps) and register the redirect URL `http://127.0.0.1:54321/callback`. Grant it the four scopes above.
+2. Export its credentials and log in from an interactive terminal:
+
+```sh
+export FIGMA_CLIENT_ID=...
+export FIGMA_CLIENT_SECRET=...
+figma auth login                 # opens the browser, waits on 127.0.0.1:54321
+figma auth login --port 8765     # if you registered http://127.0.0.1:8765/callback instead
+```
+
+`--client-id` and `--client-secret` override the variables, but a literal secret shows in process listings and shell history. The flow uses PKCE (S256) and a random `state`; a callback with the wrong `state` is answered with HTTP 400 and ignored. Because Figma matches redirect URLs exactly, a busy port is not swapped for another one: the command exits 2 with `{"error": "port_unavailable"}`. Add `--no-browser` to print the authorization URL without opening it.
+
+Over SSH, in a container, or anywhere the browser runs on another machine, its redirect to `127.0.0.1` never reaches figma-cli. While it waits, the command reads the terminal: after authorizing, copy the full URL from the browser's address bar (the page itself fails to load) and paste it at the `Paste the callback URL here` prompt. A `code=...&state=...` query string works too. The paste is held to the same checks as the browser redirect: the path must be `/callback` on the configured port and `state` must match, so a bare code without `state` is refused. A rejected paste is explained and the prompt returns while the loopback server keeps listening.
+
+The access token is checked against `GET /v1/me`, then the access token, refresh token, expiry, client id and client secret are written to `~/.config/figma/token.json` (mode `0600`, directory `0700`, atomic replace). Figma access tokens last 90 days. When the stored one has expired, the next command refreshes it through `POST /v1/oauth/refresh` before running. The refresh holds an advisory lock on `~/.config/figma/token.json.lock` and re-reads the file once it has the lock, so concurrent commands refresh once rather than invalidating each other's tokens (Windows has no `fcntl`, so there the refresh runs unlocked). A refresh Figma rejects exits 3 with `{"error": "refresh_failed"}` rather than falling back to an older personal access token; run `figma auth login` again.
 
 Every subcommand prints human-readable text by default and a JSON document on stdout with `--json`.
 
 | Command | Figma endpoint |
 | --- | --- |
 | `figma auth login [--token TOKEN\|-] [--no-browser]` | `GET /v1/me`, then writes `~/.config/figma/token` |
+| `figma auth login [--client-id ID] [--client-secret SECRET] [--port PORT]` | OAuth: `POST /v1/oauth/token`, `GET /v1/me`, then writes `~/.config/figma/token.json` |
 | `figma auth check` | `GET /v1/me` |
 | `figma file get <file_key> [--depth N]` | `GET /v1/files/{file_key}?depth=N` |
 | `figma export <file_key> --nodes <ids> [--format png\|svg] [--output DIR]` | `GET /v1/images/{file_key}`, then the asset URLs |
@@ -125,7 +148,7 @@ HTTP 429 is reported at once, never retried, so the caller decides when to try a
 
 ### Token safety
 
-A request carrying `X-Figma-Token` follows no redirects. Any 3xx answer is refused with `{"error": "redirect_refused"}` and exit code 3 before a second request is made, so the token never reaches another host. Exported images are downloaded from the pre-signed URLs Figma returns with a separate request that carries no token; only that request follows redirects.
+A request carrying a credential (`X-Figma-Token`, `Authorization: Bearer`, or the `Authorization: Basic` client credentials on the OAuth token calls) follows no redirects. Any 3xx answer is refused with `{"error": "redirect_refused"}` and exit code 3 before a second request is made, so the credential never reaches another host. Exported images are downloaded from the pre-signed URLs Figma returns with a separate request that carries no token; only that request follows redirects.
 
 ## Installation and quick run
 

{figma_cli-0.3.0 → figma_cli-0.3.1}/src/figma_cli/__init__.py

@@ -1,3 +1,3 @@
 """Headless Figma CLI for AI coding agents and automated design inspection."""
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"

{figma_cli-0.3.0 → figma_cli-0.3.1}/src/figma_cli/cli.py

@@ -14,6 +14,7 @@ from typing import Any
 from figma_cli import __version__
 from figma_cli.client import FigmaClient, FigmaError, download
 from figma_cli.login import login
+from figma_cli.oauth import DEFAULT_PORT
 
 # Most handlers take (client, args); those marked needs_client=False take (args).
 Handler = Callable[..., tuple[Any, str]]
@@ -123,6 +124,13 @@ def _positive_int(value: str) -> int:
     return number
 
 
+def _port(value: str) -> int:
+    number = int(value)
+    if not 1 <= number <= 65535:
+        raise argparse.ArgumentTypeError("must be between 1 and 65535")
+    return number
+
+
 def _node_list(value: str) -> list[str]:
     nodes = [n.strip() for n in value.split(",") if n.strip()]
     if not nodes:
@@ -138,7 +146,8 @@ def build_parser() -> argparse.ArgumentParser:
         ),
         epilog=(
             "Environment: FIGMA_TOKEN (optional when 'figma auth login' has stored"
-            " ~/.config/figma/token), FIGMA_API_BASE (optional)."
+            " ~/.config/figma/token.json or ~/.config/figma/token), FIGMA_API_BASE"
+            " (optional), FIGMA_CLIENT_ID and FIGMA_CLIENT_SECRET (OAuth login)."
         ),
     )
     parser.add_argument(
@@ -157,7 +166,10 @@ def build_parser() -> argparse.ArgumentParser:
     p = auth_cmds.add_parser(
         "login",
         parents=[common],
-        help="validate a token and store it in ~/.config/figma/token",
+        help=(
+            "authorize via OAuth (with client credentials) or store a personal"
+            " access token, after validating it"
+        ),
     )
     p.add_argument(
         "--token",
@@ -169,7 +181,26 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument(
         "--browser",
         action=argparse.BooleanOptionalAction,
-        help="open Figma settings when prompting interactively (default: open)",
+        help=("open Figma settings or the OAuth page when interactive (default: open)"),
+    )
+    p.add_argument(
+        "--client-id", help="OAuth app client id (default: $FIGMA_CLIENT_ID)"
+    )
+    p.add_argument(
+        "--client-secret",
+        help=(
+            "OAuth app client secret (default: $FIGMA_CLIENT_SECRET); a literal"
+            " value shows in ps and shell history, so prefer the variable"
+        ),
+    )
+    p.add_argument(
+        "--port",
+        type=_port,
+        default=DEFAULT_PORT,
+        help=(
+            "loopback port for the OAuth redirect http://127.0.0.1:PORT/callback"
+            f" (default: {DEFAULT_PORT})"
+        ),
     )
     p.set_defaults(handler=_auth_login, needs_client=False)
 

{figma_cli-0.3.0 → figma_cli-0.3.1}/src/figma_cli/client.py

@@ -2,14 +2,21 @@
 
 Two transport rules hold for every request:
 
-* A request carrying ``X-Figma-Token`` follows zero redirects. Any 3xx answer is
-  refused before a second request is made, so the token never reaches another host.
+* A request carrying a credential (``X-Figma-Token`` for a personal access token,
+  ``Authorization: Bearer`` for an OAuth token, ``Authorization: Basic`` for OAuth
+  client credentials) follows zero redirects. Any 3xx answer is refused before a
+  second request is made, so the credential never reaches another host.
 * Rendered assets are fetched from their pre-signed URLs without the token.
+
+Credentials resolve in this order: ``FIGMA_TOKEN``, then the OAuth tokens in
+``~/.config/figma/token.json`` (refreshed when expired), then the personal access
+token in ``~/.config/figma/token``.
 """
 
 import email.utils
 import json
 import os
+import secrets
 import time
 import urllib.error
 import urllib.parse
@@ -19,6 +26,7 @@ from typing import Any
 
 DEFAULT_API_BASE = "https://api.figma.com"
 TOKEN_HEADER = "X-Figma-Token"
+OAUTH_TOKEN_PREFIX = "figu_"
 TIMEOUT_SECONDS = 60
 EXIT_USAGE = 2
 EXIT_API_ERROR = 3
@@ -42,6 +50,15 @@ class FigmaError(Exception):
         self.payload = payload
 
 
+class UsageError(FigmaError):
+    """A local usage problem (bad input, busy port): exit 2."""
+
+    exit_code = EXIT_USAGE
+
+    def __init__(self, error: str, message: str):
+        super().__init__({"error": error, "message": message})
+
+
 class _RefuseRedirects(urllib.request.HTTPRedirectHandler):
     def redirect_request(self, req, fp, code, msg, headers, newurl):
         raise FigmaError(
@@ -96,10 +113,57 @@ def _network_error(err: OSError) -> FigmaError:
 
 
 def token_path() -> Path:
-    """Where ``figma auth login`` stores the token: ``~/.config/figma/token``."""
+    """Where ``figma auth login`` stores a personal access token."""
     return Path.home() / ".config" / "figma" / "token"
 
 
+def token_json_path() -> Path:
+    """Where ``figma auth login`` stores OAuth tokens and client credentials."""
+    return token_path().with_name("token.json")
+
+
+def is_oauth_token(token: str) -> bool:
+    """True for a Figma OAuth access token, which travels as a Bearer token."""
+    return token.startswith(OAUTH_TOKEN_PREFIX)
+
+
+def write_private(path: Path, text: str) -> None:
+    """Write ``text`` to ``path`` at mode 0600, replacing it only once written.
+
+    The new file is created 0600 under a fresh name (O_EXCL, so never through a
+    planted file or symlink), then renamed over the old one: a failed write
+    leaves the previous file intact, and nothing is ever readable by others.
+    """
+    tmp = path.with_name(f".{path.name}.{secrets.token_hex(8)}")
+    try:
+        path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+        path.parent.chmod(0o700)  # refuses a directory owned by someone else
+        fd = os.open(tmp, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                fh.write(text)
+                fh.flush()
+                os.fsync(fh.fileno())
+            os.replace(tmp, path)
+            _fsync_dir(path.parent)
+        except BaseException:
+            tmp.unlink(missing_ok=True)
+            raise
+    except OSError as err:
+        raise FigmaError({"error": "write_failed", "message": str(err)}) from None
+
+
+def _fsync_dir(directory: Path) -> None:
+    try:
+        dir_fd = os.open(directory, os.O_RDONLY)
+        try:
+            os.fsync(dir_fd)
+        finally:
+            os.close(dir_fd)
+    except OSError:
+        pass
+
+
 def read_token_file() -> str:
     """Return the stored token, or "" when no regular file holds one."""
     path = token_path()
@@ -127,16 +191,25 @@ class FigmaClient:
         token: str,
         base_url: str = DEFAULT_API_BASE,
         timeout: float = TIMEOUT_SECONDS,
+        bearer: bool | None = None,
     ):
         self.token = token
+        self.bearer = is_oauth_token(token) if bearer is None else bearer
         self.base_url = base_url.rstrip("/")
         self.timeout = timeout
         self._opener = urllib.request.build_opener(_RefuseRedirects)
 
     @classmethod
     def from_env(cls) -> "FigmaClient":
-        """Read FIGMA_TOKEN, falling back to the stored token file."""
-        token = os.environ.get("FIGMA_TOKEN", "").strip() or read_token_file()
+        """Resolve FIGMA_TOKEN, then stored OAuth tokens, then the stored PAT."""
+        token = os.environ.get("FIGMA_TOKEN", "").strip()
+        if token:
+            return cls(token, api_base())
+        if token_json_path().exists():
+            from figma_cli.oauth import fresh_access_token
+
+            return cls(fresh_access_token(), api_base(), bearer=True)
+        token = read_token_file()
         if not token:
             message = (
                 f"FIGMA_TOKEN is not set and {token_path()} holds no token;"
@@ -145,6 +218,11 @@ class FigmaClient:
             raise FigmaError({"error": "missing_token", "message": message})
         return cls(token, api_base())
 
+    def auth_headers(self) -> dict[str, str]:
+        if self.bearer:
+            return {"Authorization": f"Bearer {self.token}"}
+        return {TOKEN_HEADER: self.token}
+
     def request(
         self,
         method: str,
@@ -155,7 +233,7 @@ class FigmaClient:
         url = self.base_url + path
         if query:
             url += "?" + urllib.parse.urlencode(query)
-        headers = {TOKEN_HEADER: self.token, "Accept": "application/json"}
+        headers = {**self.auth_headers(), "Accept": "application/json"}
         data = None
         if body is not None:
             data = json.dumps(body).encode()
@@ -215,6 +293,15 @@ class FigmaClient:
         return self.request("DELETE", path)
 
 
+def checked_me(client: FigmaClient) -> dict[str, Any]:
+    """GET /v1/me, insisting on a user id: proof the credential works."""
+    me = client.me()
+    if not isinstance(me, dict) or not me.get("id"):
+        message = "GET /v1/me returned no user id"
+        raise FigmaError({"error": "invalid_response", "message": message})
+    return me
+
+
 def download(url: str, timeout: float = TIMEOUT_SECONDS) -> bytes:
     """Fetch a pre-signed asset URL. Sends no token, so redirects are safe to follow."""
     if urllib.parse.urlsplit(url).scheme not in ("http", "https"):

figma_cli-0.3.1/src/figma_cli/login.py

@@ -0,0 +1,92 @@
+"""``figma auth login``: obtain a token, validate it, then store it.
+
+The token is checked against ``GET /v1/me`` before anything touches disk, so a
+rejected token never replaces a working one. The OAuth browser flow lives in
+``figma_cli.oauth``.
+"""
+
+import argparse
+import getpass
+import sys
+import webbrowser
+from pathlib import Path
+
+from figma_cli import oauth
+from figma_cli.client import (
+    FigmaClient,
+    FigmaError,
+    UsageError,
+    api_base,
+    checked_me,
+    token_json_path,
+    token_path,
+    write_private,
+)
+
+SETTINGS_URL = "https://www.figma.com/settings"
+SCOPES = oauth.SCOPES
+INSTRUCTIONS = f"""\
+Create a personal access token for figma-cli:
+  1. Open {SETTINGS_URL} and go to Security > Personal access tokens.
+  2. Generate a new token with these scopes:
+{chr(10).join(f"       {scope}" for scope in SCOPES)}
+  3. Paste the token below (input is hidden).
+"""
+
+
+class TokenInputError(UsageError):
+    """A missing or malformed token on input: a usage error, exit 2."""
+
+
+def _prompt(open_browser: bool) -> str:
+    print(INSTRUCTIONS, file=sys.stderr)
+    if open_browser:
+        webbrowser.open(SETTINGS_URL)
+    return getpass.getpass("Figma personal access token: ")
+
+
+def candidate_token(args: argparse.Namespace) -> str:
+    """Take the token from --token, from stdin, or from a hidden prompt."""
+    if args.token is not None and args.token != "-":
+        token = args.token
+    elif args.token == "-" or not sys.stdin.isatty():
+        token = sys.stdin.read()
+    else:
+        token = _prompt(args.browser is not False)
+    token = token.strip()
+    if not token:
+        raise TokenInputError("empty_token", "no token was provided")
+    if any(not "!" <= ch <= "~" for ch in token):
+        message = "token must be visible ASCII, without spaces or line breaks"
+        raise TokenInputError("invalid_token", message)
+    return token
+
+
+def save_token(token: str) -> Path:
+    """Store a personal access token at mode 0600 and drop any OAuth tokens.
+
+    ``token.json`` outranks the plaintext file, so leaving it in place would let
+    stale OAuth tokens silently shadow the token just saved.
+    """
+    path = token_path()
+    write_private(path, token + "\n")
+    try:
+        token_json_path().unlink(missing_ok=True)
+    except OSError as err:
+        raise FigmaError({"error": "write_failed", "message": str(err)}) from None
+    return path
+
+
+def login(args: argparse.Namespace) -> tuple[dict, Path]:
+    """Obtain and validate a credential, store it, and return (identity, path).
+
+    An interactive terminal with OAuth client credentials runs the browser flow;
+    everything else (--token, piped stdin, no client credentials) takes a PAT.
+    """
+    if args.token is None and sys.stdin.isatty():
+        client = oauth.client_credentials(args.client_id, args.client_secret)
+        if client:
+            return oauth.login(client, args.port, args.browser is not False)
+    token = candidate_token(args)
+    me = checked_me(FigmaClient(token, api_base()))
+    return me, save_token(token)