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

{figma_cli-0.2.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.1/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.5
+Name: figma-cli
+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
+Author: imperfect-co
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine>=6.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# figma-cli
+
+Headless Figma CLI for AI coding agents and automated design inspection.
+
+Requires Python 3.11 or newer. Licensed under MIT.
+
+## Commands
+
+The package installs two console scripts that run the same entrypoint:
+
+- `figma-cli`
+- `figma` (short alias)
+
+Each reports its own name in `--help` and `--version`:
+
+```console
+$ figma-cli --version
+figma-cli 0.1.0
+$ figma --version
+figma 0.1.0
+```
+
+The npm package `silships/figma-cli` also installs a `figma-cli` executable. If both are installed, whichever directory comes first on `PATH` wins. Run `command -v figma-cli` to check which one you get, or use the `figma` alias.
+
+## Usage
+
+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 |
+| --- | --- |
+| `current_user:read` | `auth check`, `auth login` (`GET /v1/me`) |
+| `file_content:read` | `file get`, `export` |
+| `file_comments:read` | `comment list` |
+| `file_comments:write` | `comment post`, `comment delete` |
+
+Then store it once with `figma auth login`:
+
+```sh
+figma auth login                       # interactive: prints the steps, opens settings, hidden prompt
+echo "$TOKEN" | figma auth login       # agents and CI: piped stdin
+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.
+
+`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
+```
+
+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 |
+| `figma comment list <file_key>` | `GET /v1/files/{file_key}/comments` |
+| `figma comment post <file_key> --message TEXT [--comment-id ID] [--node-id ID]` | `POST /v1/files/{file_key}/comments` |
+| `figma comment delete <file_key> <comment_id>` | `DELETE /v1/files/{file_key}/comments/{comment_id}` |
+
+The file key is the segment after `/design/` (or `/file/`) in a Figma URL. Node ids use the `1:2` form; a URL shows them as `node-id=1-2`.
+
+### Examples
+
+Check the token:
+
+```console
+$ figma auth check --json
+{
+  "id": "123456789",
+  "handle": "Design Bot",
+  "email": "bot@example.com"
+}
+```
+
+Inspect only the pages of a file. `--depth` is passed to Figma, so the server trims the tree before it is sent:
+
+```sh
+figma file get AbCdEf123 --depth 1
+figma file get AbCdEf123 --depth 2 --json | jq '.document.children[].name'
+```
+
+Render two frames to PNG and print where they were written. Files are named `<file_key>_<node_id>.<format>` with `:` and other unsafe characters replaced by `-`; re-exporting the same node overwrites its file:
+
+```console
+$ figma export AbCdEf123 --nodes 1:2,1:3 --output shots
+shots/AbCdEf123_1-2.png
+shots/AbCdEf123_1-3.png
+```
+
+Post a comment pinned to a frame, reply to it, list the thread, then clean up:
+
+```sh
+id=$(figma comment post AbCdEf123 --message "Spacing is off" --node-id 1:2 --json | jq -r .id)
+figma comment post AbCdEf123 --message "Fixed in the next build" --comment-id "$id"
+figma comment list AbCdEf123
+figma comment delete AbCdEf123 "$id"
+```
+
+### Errors and exit codes
+
+| Exit code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 2 | Usage error (bad or missing arguments) |
+| 3 | Figma API, network, or local write failure |
+
+With `--json`, a failure prints a JSON object on stdout; without it, a one-line message goes to stderr. HTTP 401, 403, 404 and 5xx become `unauthorized`, `forbidden`, `not_found` and `server_error`:
+
+```json
+{"error": "forbidden", "status": 403, "message": "Invalid token"}
+```
+
+HTTP 429 is reported at once, never retried, so the caller decides when to try again. `retry_after` comes from the `Retry-After` header and is `null` when Figma sends none:
+
+```json
+{"error": "rate_limit_exceeded", "status": 429, "retry_after": 30}
+```
+
+### Token safety
+
+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
+
+Run on-demand without installing via [uv](https://docs.astral.sh/uv/):
+
+```sh
+uvx figma-cli --help
+uvx figma-cli auth check --json
+```
+
+Or install from [PyPI](https://pypi.org/project/figma-cli/):
+
+```sh
+pip install figma-cli
+```
+
+From a local checkout:
+
+```sh
+uvx --from . figma-cli --version
+```
+
+## Development
+
+```sh
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+ruff check .
+ruff format --check .
+pytest tests/
+```
+
+The tests are hermetic: no network access and no Figma token are needed, and `HOME` points at a temporary directory so a stored token never leaks in. The redirect tests use real sockets on `127.0.0.1`.
+
+`tests/test_live.py` runs against the real API only when `FIGMA_TOKEN` is set. With the token alone it checks `auth check` and runs `auth login` from stdin into a temporary `HOME`; the file, comment and export checks also need `FIGMA_TEST_FILE_KEY` (add `FIGMA_TEST_NODE_ID` to exercise export). The comment check posts one comment and deletes it. CI runs it in the `live` job from the `FIGMA_TOKEN` secret and the `FIGMA_TEST_FILE_KEY` / `FIGMA_TEST_NODE_ID` repository variables, and skips it when they are absent.
+
+## Release
+
+Bump `__version__` in `src/figma_cli/__init__.py`, merge, then push a matching tag (`v0.1.0` for `0.1.0`). The release workflow refuses a tag that does not match `__version__`, builds the sdist and wheel, runs `twine check`, and publishes to PyPI through trusted publishing (OIDC, the `pypi` environment).
+
+## License
+
+MIT, see [LICENSE](LICENSE).

figma_cli-0.3.1/README.md

@@ -0,0 +1,194 @@
+# figma-cli
+
+Headless Figma CLI for AI coding agents and automated design inspection.
+
+Requires Python 3.11 or newer. Licensed under MIT.
+
+## Commands
+
+The package installs two console scripts that run the same entrypoint:
+
+- `figma-cli`
+- `figma` (short alias)
+
+Each reports its own name in `--help` and `--version`:
+
+```console
+$ figma-cli --version
+figma-cli 0.1.0
+$ figma --version
+figma 0.1.0
+```
+
+The npm package `silships/figma-cli` also installs a `figma-cli` executable. If both are installed, whichever directory comes first on `PATH` wins. Run `command -v figma-cli` to check which one you get, or use the `figma` alias.
+
+## Usage
+
+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 |
+| --- | --- |
+| `current_user:read` | `auth check`, `auth login` (`GET /v1/me`) |
+| `file_content:read` | `file get`, `export` |
+| `file_comments:read` | `comment list` |
+| `file_comments:write` | `comment post`, `comment delete` |
+
+Then store it once with `figma auth login`:
+
+```sh
+figma auth login                       # interactive: prints the steps, opens settings, hidden prompt
+echo "$TOKEN" | figma auth login       # agents and CI: piped stdin
+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.
+
+`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
+```
+
+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 |
+| `figma comment list <file_key>` | `GET /v1/files/{file_key}/comments` |
+| `figma comment post <file_key> --message TEXT [--comment-id ID] [--node-id ID]` | `POST /v1/files/{file_key}/comments` |
+| `figma comment delete <file_key> <comment_id>` | `DELETE /v1/files/{file_key}/comments/{comment_id}` |
+
+The file key is the segment after `/design/` (or `/file/`) in a Figma URL. Node ids use the `1:2` form; a URL shows them as `node-id=1-2`.
+
+### Examples
+
+Check the token:
+
+```console
+$ figma auth check --json
+{
+  "id": "123456789",
+  "handle": "Design Bot",
+  "email": "bot@example.com"
+}
+```
+
+Inspect only the pages of a file. `--depth` is passed to Figma, so the server trims the tree before it is sent:
+
+```sh
+figma file get AbCdEf123 --depth 1
+figma file get AbCdEf123 --depth 2 --json | jq '.document.children[].name'
+```
+
+Render two frames to PNG and print where they were written. Files are named `<file_key>_<node_id>.<format>` with `:` and other unsafe characters replaced by `-`; re-exporting the same node overwrites its file:
+
+```console
+$ figma export AbCdEf123 --nodes 1:2,1:3 --output shots
+shots/AbCdEf123_1-2.png
+shots/AbCdEf123_1-3.png
+```
+
+Post a comment pinned to a frame, reply to it, list the thread, then clean up:
+
+```sh
+id=$(figma comment post AbCdEf123 --message "Spacing is off" --node-id 1:2 --json | jq -r .id)
+figma comment post AbCdEf123 --message "Fixed in the next build" --comment-id "$id"
+figma comment list AbCdEf123
+figma comment delete AbCdEf123 "$id"
+```
+
+### Errors and exit codes
+
+| Exit code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 2 | Usage error (bad or missing arguments) |
+| 3 | Figma API, network, or local write failure |
+
+With `--json`, a failure prints a JSON object on stdout; without it, a one-line message goes to stderr. HTTP 401, 403, 404 and 5xx become `unauthorized`, `forbidden`, `not_found` and `server_error`:
+
+```json
+{"error": "forbidden", "status": 403, "message": "Invalid token"}
+```
+
+HTTP 429 is reported at once, never retried, so the caller decides when to try again. `retry_after` comes from the `Retry-After` header and is `null` when Figma sends none:
+
+```json
+{"error": "rate_limit_exceeded", "status": 429, "retry_after": 30}
+```
+
+### Token safety
+
+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
+
+Run on-demand without installing via [uv](https://docs.astral.sh/uv/):
+
+```sh
+uvx figma-cli --help
+uvx figma-cli auth check --json
+```
+
+Or install from [PyPI](https://pypi.org/project/figma-cli/):
+
+```sh
+pip install figma-cli
+```
+
+From a local checkout:
+
+```sh
+uvx --from . figma-cli --version
+```
+
+## Development
+
+```sh
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+ruff check .
+ruff format --check .
+pytest tests/
+```
+
+The tests are hermetic: no network access and no Figma token are needed, and `HOME` points at a temporary directory so a stored token never leaks in. The redirect tests use real sockets on `127.0.0.1`.
+
+`tests/test_live.py` runs against the real API only when `FIGMA_TOKEN` is set. With the token alone it checks `auth check` and runs `auth login` from stdin into a temporary `HOME`; the file, comment and export checks also need `FIGMA_TEST_FILE_KEY` (add `FIGMA_TEST_NODE_ID` to exercise export). The comment check posts one comment and deletes it. CI runs it in the `live` job from the `FIGMA_TOKEN` secret and the `FIGMA_TEST_FILE_KEY` / `FIGMA_TEST_NODE_ID` repository variables, and skips it when they are absent.
+
+## Release
+
+Bump `__version__` in `src/figma_cli/__init__.py`, merge, then push a matching tag (`v0.1.0` for `0.1.0`). The release workflow refuses a tag that does not match `__version__`, builds the sdist and wheel, runs `twine check`, and publishes to PyPI through trusted publishing (OIDC, the `pypi` environment).
+
+## License
+
+MIT, see [LICENSE](LICENSE).

{figma_cli-0.2.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.2.0"
+__version__ = "0.3.1"

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

@@ -13,16 +13,18 @@ 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
 
-Handler = Callable[[FigmaClient, argparse.Namespace], tuple[Any, str]]
+# Most handlers take (client, args); those marked needs_client=False take (args).
+Handler = Callable[..., tuple[Any, str]]
 
 
 def _print_json(payload: Any) -> None:
     print(json.dumps(payload, indent=2, ensure_ascii=False))
 
 
-def _auth_check(client: FigmaClient, args: argparse.Namespace) -> tuple[Any, str]:
-    me = client.me()
+def _identity(me: dict[str, Any]) -> tuple[dict[str, Any], str]:
     ident = {key: me.get(key) for key in ("id", "handle", "email")}
     return (
         ident,
@@ -30,6 +32,16 @@ def _auth_check(client: FigmaClient, args: argparse.Namespace) -> tuple[Any, str
     )
 
 
+def _auth_check(client: FigmaClient, args: argparse.Namespace) -> tuple[Any, str]:
+    return _identity(client.me())
+
+
+def _auth_login(args: argparse.Namespace) -> tuple[Any, str]:
+    me, path = login(args)
+    ident, text = _identity(me)
+    return {**ident, "token_path": str(path)}, f"{text}\nToken saved to {path}"
+
+
 def _tree_lines(node: dict[str, Any], indent: int = 0) -> list[str]:
     label = f"{node.get('type', '?')} {node.get('name', '')} ({node.get('id', '')})"
     lines = ["  " * indent + label]
@@ -112,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:
@@ -125,7 +144,11 @@ def build_parser() -> argparse.ArgumentParser:
         description=(
             "Headless Figma CLI for AI coding agents and automated design inspection."
         ),
-        epilog="Environment: FIGMA_TOKEN (required), FIGMA_API_BASE (optional).",
+        epilog=(
+            "Environment: FIGMA_TOKEN (optional when 'figma auth login' has stored"
+            " ~/.config/figma/token.json or ~/.config/figma/token), FIGMA_API_BASE"
+            " (optional), FIGMA_CLIENT_ID and FIGMA_CLIENT_SECRET (OAuth login)."
+        ),
     )
     parser.add_argument(
         "--version", action="version", version=f"%(prog)s {__version__}"
@@ -134,10 +157,52 @@ def build_parser() -> argparse.ArgumentParser:
     common.add_argument("--json", action="store_true", help="print structured JSON")
     commands = parser.add_subparsers(dest="command", metavar="<command>")
 
-    auth = commands.add_parser("auth", help="token checks")
+    auth = commands.add_parser("auth", help="token setup and checks")
     auth_cmds = auth.add_subparsers(dest="action", metavar="<action>", required=True)
-    p = auth_cmds.add_parser("check", parents=[common], help="validate FIGMA_TOKEN")
+    p = auth_cmds.add_parser(
+        "check", parents=[common], help="validate FIGMA_TOKEN or stored token file"
+    )
     p.set_defaults(handler=_auth_check)
+    p = auth_cmds.add_parser(
+        "login",
+        parents=[common],
+        help=(
+            "authorize via OAuth (with client credentials) or store a personal"
+            " access token, after validating it"
+        ),
+    )
+    p.add_argument(
+        "--token",
+        help=(
+            "token value, or '-' to read stdin; a literal value shows in ps and"
+            " shell history, so prefer piped stdin, which is read without this flag"
+        ),
+    )
+    p.add_argument(
+        "--browser",
+        action=argparse.BooleanOptionalAction,
+        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)
 
     file = commands.add_parser("file", help="file inspection")
     file_cmds = file.add_subparsers(dest="action", metavar="<action>", required=True)
@@ -194,7 +259,10 @@ def main(argv: Sequence[str] | None = None) -> int:
         parser.print_help()
         return 0
     try:
-        payload, text = handler(FigmaClient.from_env(), args)
+        if getattr(args, "needs_client", True):
+            payload, text = handler(FigmaClient.from_env(), args)
+        else:
+            payload, text = handler(args)
     except FigmaError as err:
         if args.json:
             _print_json(err.payload)