From 2bc3ae06dd69eb4186b86f387f4788daf0c1c1b7 Mon Sep 17 00:00:00 2001 From: Andrew Ho Date: Sun, 12 Apr 2026 22:25:05 -0700 Subject: [PATCH] docs: switch to scalar pages and update docs references --- .github/workflows/docs-pages.yml | 43 ++++++++++++++++++++ README.md | 59 +++++++++++++++++---------- docs/cli-reference.mdx | 55 +++++++++++++------------ docs/development.mdx | 12 +++--- docs/doctor.mdx | 2 +- docs/index.mdx | 8 ++-- docs/local-server.mdx | 1 + docs/quickstart.mdx | 20 ++++----- package.json | 6 +-- scalar/index.html | 69 ++++++++++++++++++++++++++++++++ 10 files changed, 203 insertions(+), 72 deletions(-) create mode 100644 .github/workflows/docs-pages.yml create mode 100644 scalar/index.html diff --git a/.github/workflows/docs-pages.yml b/.github/workflows/docs-pages.yml new file mode 100644 index 0000000..fab9441 --- /dev/null +++ b/.github/workflows/docs-pages.yml @@ -0,0 +1,43 @@ +name: Docs (Scalar) + +on: + push: + branches: + - main + paths: + - "scalar/**" + - ".github/workflows/docs-pages.yml" + - "docs/**" + - "README.md" + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: true + +jobs: + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Pages + uses: actions/configure-pages@v5 + + - name: Upload Artifact + uses: actions/upload-pages-artifact@v3 + with: + path: ./scalar + + - name: Deploy To GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/README.md b/README.md index 9584245..307621b 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,8 @@ Output controls: ```bash bluebubbles contact list -bluebubbles chat list -o json +bluebubbles chats list -o wide +bluebubbles chats list -o json ``` Human-readable output (`columnify`) is the default: @@ -48,7 +49,7 @@ Alex Rivera +1-555-0100 alex@example.com Taylor Kim +1-555-0199 taylor@example.com ``` -`message list` uses the same default table style: +`messages list` uses the same default table style: ```text GUID FROM TEXT AGE CHAT @@ -74,37 +75,37 @@ JSON output is available with `-o json` or `--json`: For messages: ```bash -bluebubbles message list --chat 'iMessage;+;chat123' -bluebubbles message list --chat 'iMessage;+;chat123' --json +bluebubbles messages list --chat 'iMessage;+;chat123' +bluebubbles messages list --chat 'iMessage;+;chat123' --json ``` Pagination defaults are conservative for message-heavy commands: -- `bluebubbles message list` defaults to `--limit 50` -- `bluebubbles chat messages ` defaults to `--limit 50` +- `bluebubbles messages list` defaults to `--limit 50` +- `bluebubbles chats messages ` defaults to `--limit 50` ## Query and filter examples Get all messages for one conversation in pages: ```bash -bluebubbles message list --chat 'iMessage;+;chat123' --limit 50 --offset 0 --json -bluebubbles message list --chat 'iMessage;+;chat123' --limit 50 --offset 50 --json -bluebubbles message list --chat 'iMessage;+;chat123' --limit 50 --offset 100 --json +bluebubbles messages list --chat 'iMessage;+;chat123' --limit 50 --offset 0 --json +bluebubbles messages list --chat 'iMessage;+;chat123' --limit 50 --offset 50 --json +bluebubbles messages list --chat 'iMessage;+;chat123' --limit 50 --offset 100 --json ``` Filter by date window (epoch seconds): ```bash -bluebubbles message list --chat 'iMessage;+;chat123' --after 1710000000 --before 1710086400 --json +bluebubbles messages list --chat 'iMessage;+;chat123' --after 1710000000 --before 1710086400 --json ``` Common filters: ```bash -bluebubbles message list --chat 'iMessage;+;chat123' --text 'invoice' --limit 50 --json -bluebubbles message list --chat 'iMessage;+;chat123' --from '+15551234567' --not-from-me --json -bluebubbles message list --chat 'iMessage;+;chat123' --from-me --has-attachments --json +bluebubbles messages list --chat 'iMessage;+;chat123' --text 'invoice' --limit 50 --json +bluebubbles messages list --chat 'iMessage;+;chat123' --from '+15551234567' --not-from-me --json +bluebubbles messages list --chat 'iMessage;+;chat123' --from-me --has-attachments --json ``` Common filters are applied client-side to the returned page. Use `--where` for raw server-side filtering. @@ -112,7 +113,7 @@ Common filters are applied client-side to the returned page. Use `--where` for r Advanced filtering via raw API `where` clauses: ```bash -bluebubbles message list \ +bluebubbles messages list \ --where '[{"statement":"message.text LIKE :q","args":{"q":"%hello%"}}]' \ --limit 50 \ --json @@ -121,8 +122,8 @@ bluebubbles message list \ Conversation endpoint alternative: ```bash -bluebubbles chat messages 'iMessage;+;chat123' --limit 50 --offset 0 --json -bluebubbles chat messages 'iMessage;+;chat123' --after 1710000000 --before 1710086400 --json +bluebubbles chats messages 'iMessage;+;chat123' --limit 50 --offset 0 --json +bluebubbles chats messages 'iMessage;+;chat123' --after 1710000000 --before 1710086400 --json ``` ## Command shape @@ -130,18 +131,29 @@ bluebubbles chat messages 'iMessage;+;chat123' --after 1710000000 --before 17100 ```bash bluebubbles ping bluebubbles server info +bluebubbles server open bluebubbles server status bluebubbles server logs bluebubbles server logs --source api -bluebubbles chat list -bluebubbles message send --chat --message "hello" -bluebubbles message schedule list +bluebubbles chats list +bluebubbles messages send --chat --message "hello" +bluebubbles messages schedule list bluebubbles handle availability
bluebubbles attachment download bluebubbles contact query --address user@example.com bluebubbles icloud account ``` +Verbose diagnostics: + +```bash +bluebubbles messages list --chat 'iMessage;+;chat123' --verbose +``` + +`--verbose` prints request/response diagnostics to stderr. You can also set `BLUEBUBBLES_VERBOSE=1`. + +Request timeout defaults to `10000ms` and can be overridden with `BLUEBUBBLES_REQUEST_TIMEOUT_MS`. + ## Configuration Persist config: @@ -166,14 +178,19 @@ export BLUEBUBBLES_PASSWORD='your#server#password' ## Docs -Mintlify is configured through the local `mint` dev dependency. +Docs are served via Scalar and deployed to GitHub Pages. ```bash -bun run docs:sync-openapi bun run docs:dev bun run docs:validate ``` +GitHub Pages workflow publishes `scalar/index.html` at: + +```text +https://anmho.github.io/bluebubbles-cli/ +``` + `test:commands` is local-only by design. It exercises all registered CLI commands and can skip unavailable API/local prerequisites in tolerant mode. It uses the same auth sources as normal CLI runs (`BLUEBUBBLES_*` env vars or persisted `bluebubbles config` values). The API Reference tab renders from `docs/openapi.yaml`, which is a pinned copy of the official BlueBubbles OpenAPI source: diff --git a/docs/cli-reference.mdx b/docs/cli-reference.mdx index e41bf1b..1f9e4e9 100644 --- a/docs/cli-reference.mdx +++ b/docs/cli-reference.mdx @@ -10,8 +10,8 @@ bluebubbles config ... bluebubbles doctor bluebubbles ping bluebubbles server ... -bluebubbles chat ... -bluebubbles message ... +bluebubbles chats ... +bluebubbles messages ... bluebubbles handle ... bluebubbles attachment ... bluebubbles contact ... @@ -23,8 +23,9 @@ bluebubbles webhook ... Most API commands support: -- `-o, --output ` where format is `table` or `json` +- `-o, --output ` where format is `table`, `wide`, or `json` - `--json` as an alias for `-o json` +- `-v, --verbose` for API diagnostics to stderr ## Endpoint-mapped commands @@ -41,6 +42,8 @@ Most API commands support: Local process manager, no API endpoint - `bluebubbles server logs --source api [--count ]` API: `GET /api/v1/server/logs` +- `bluebubbles server open` + Local process manager, no API endpoint - `bluebubbles server start` Local process manager, no API endpoint - `bluebubbles server status` @@ -76,59 +79,59 @@ Most API commands support: ### Chat -- `bluebubbles chat list` +- `bluebubbles chats list` API: `POST /api/v1/chat/query` -- `bluebubbles chat get ` +- `bluebubbles chats get ` API: `GET /api/v1/chat/` -- `bluebubbles chat messages ` +- `bluebubbles chats messages ` API: `GET /api/v1/chat//message` Notes: defaults to `--limit 50`; supports `--after` and `--before` -- `bluebubbles chat update --name ` +- `bluebubbles chats update --name ` API: `PUT /api/v1/chat/` -- `bluebubbles chat delete [--yes]` +- `bluebubbles chats delete [--yes]` API: `DELETE /api/v1/chat/` -- `bluebubbles chat group leave [--yes]` +- `bluebubbles chats group leave [--yes]` API: `POST /api/v1/chat//leave` -- `bluebubbles chat group participant add
` +- `bluebubbles chats group participant add
` API: `POST /api/v1/chat//participant` -- `bluebubbles chat group participant remove
[--yes]` +- `bluebubbles chats group participant remove
[--yes]` API: `DELETE /api/v1/chat//participant` -- `bluebubbles chat group icon set ` +- `bluebubbles chats group icon set ` API: `POST /api/v1/chat//icon` -- `bluebubbles chat group icon remove [--yes]` +- `bluebubbles chats group icon remove [--yes]` API: `DELETE /api/v1/chat//icon` -- `bluebubbles chat typing start ` +- `bluebubbles chats typing start ` API: `POST /api/v1/chat//typing` -- `bluebubbles chat typing stop ` +- `bluebubbles chats typing stop ` API: `DELETE /api/v1/chat//typing` ### Message -- `bluebubbles message list` +- `bluebubbles messages list` API: `POST /api/v1/message/query` Notes: defaults to `--limit 50`; supports `--chat`, `--after`, `--before`, common filters (`--text`, `--from`, `--from-me`, `--not-from-me`, `--has-attachments`), and raw `--where ''`. `--text`, `--from`, and `--has-attachments` are applied client-side to the returned page. -- `bluebubbles message get ` +- `bluebubbles messages get ` API: `GET /api/v1/message/` -- `bluebubbles message send --chat --message ` +- `bluebubbles messages send --chat --message ` API: `POST /api/v1/message/text` -- `bluebubbles message react --chat --reaction ` +- `bluebubbles messages react --chat --reaction ` API: `POST /api/v1/message/react` -- `bluebubbles message edit --message ` +- `bluebubbles messages edit --message ` API: `POST /api/v1/message//edit` -- `bluebubbles message unsend [--yes]` +- `bluebubbles messages unsend [--yes]` API: `POST /api/v1/message//unsend` ### Message Schedule -- `bluebubbles message schedule list` +- `bluebubbles messages schedule list` API: `GET /api/v1/message/schedule` -- `bluebubbles message schedule get ` +- `bluebubbles messages schedule get ` API: `GET /api/v1/message/schedule/` -- `bluebubbles message schedule create --chat --message --date ` +- `bluebubbles messages schedule create --chat --message --date ` API: `POST /api/v1/message/schedule` -- `bluebubbles message schedule update ` +- `bluebubbles messages schedule update ` API: `PUT /api/v1/message/schedule/` -- `bluebubbles message schedule delete [--yes]` +- `bluebubbles messages schedule delete [--yes]` API: `DELETE /api/v1/message/schedule/` ### Handle diff --git a/docs/development.mdx b/docs/development.mdx index 8089bec..c9f8bef 100644 --- a/docs/development.mdx +++ b/docs/development.mdx @@ -1,6 +1,6 @@ --- title: "Development" -description: "Build, test, and validate the curated BlueBubbles CLI and Mintlify docs." +description: "Build, test, and validate the curated BlueBubbles CLI and Scalar docs." --- ## CLI workflow @@ -16,24 +16,22 @@ bun run build ## Docs workflow -The repo uses the local `mint` dev dependency. There is no separate scraper step in the current setup. +Docs are served from the `scalar/` directory and deployed with GitHub Pages. ```bash -bun run docs:sync-openapi bun run docs:dev bun run docs:validate ``` -Mintlify reads `docs/openapi.yaml`, which is kept as a pinned copy of the official upstream spec: +Scalar reads the official upstream OpenAPI spec directly: ```text -docs/openapi.yaml +https://raw.githubusercontent.com/Jish2/bluebubbles-sdk/main/openapi.yaml ``` ## Notes - CLI usage docs are hand-curated. -- API reference pages are rendered from the pinned OpenAPI file rather than maintained as generated MDX snapshots. +- API reference pages are rendered by Scalar from the upstream OpenAPI file. - The upstream source of truth remains `https://raw.githubusercontent.com/Jish2/bluebubbles-sdk/main/openapi.yaml`. -- `docs:sync-openapi` applies a minimal Mint compatibility patch when the upstream file has empty `responses` objects. - The CLI runtime uses the repo's `@anmho/bluebubbles-sdk` client layer. diff --git a/docs/doctor.mdx b/docs/doctor.mdx index 048b1cd..632544f 100644 --- a/docs/doctor.mdx +++ b/docs/doctor.mdx @@ -12,7 +12,7 @@ description: "Diagnostic checks for API connectivity, local server readiness, an - local app discovery on macOS - local process state - BlueBubbles API reachability via `ping` -- the official OpenAPI spec URL used by Mintlify +- the official OpenAPI spec URL used by Scalar docs - configured log path availability ## Example diff --git a/docs/index.mdx b/docs/index.mdx index 008cd09..6fa4c39 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -25,7 +25,7 @@ description: "A curated BlueBubbles terminal CLI organized around the resources icon="power-off" href="/local-server" > - Manage a local BlueBubbles Server app through `bluebubbles server start|stop|restart|status|logs`. + Manage a local BlueBubbles Server app through `bluebubbles server open|start|stop|restart|status|logs`. - Mintlify renders a pinned copy of the official BlueBubbles OpenAPI spec from `docs/openapi.yaml`. + Scalar renders the official BlueBubbles OpenAPI spec as an interactive API reference. @@ -46,7 +46,7 @@ description: "A curated BlueBubbles terminal CLI organized around the resources This CLI is intentionally curated. -- Root help is resource-first: `ping`, `server`, `chat`, `message`, `handle`, `attachment`, `contact`, `icloud`, `webhook`, `config`, `doctor`. +- Root help is resource-first: `ping`, `server`, `chats`, `messages`, `handle`, `attachment`, `contact`, `icloud`, `webhook`, `config`, `doctor`. - Low-value or risky clutter like `fcm`, `mac`, and web-only commands is removed. - Server-owned admin state is nested under `server`, including `server settings` and `server theme`. - Each retained command is documented with the API endpoint it corresponds to. @@ -55,4 +55,4 @@ This CLI is intentionally curated. - API commands go through the `@anmho/bluebubbles-sdk` client layer in this repo. - Local lifecycle commands manage an installed BlueBubbles Server app on macOS. -- Mintlify uses `docs/openapi.yaml`, a pinned copy of the official BlueBubbles OpenAPI spec. +- Scalar docs read the official BlueBubbles OpenAPI spec from upstream. diff --git a/docs/local-server.mdx b/docs/local-server.mdx index 7f9d44d..dedc819 100644 --- a/docs/local-server.mdx +++ b/docs/local-server.mdx @@ -8,6 +8,7 @@ description: "Manage an installed BlueBubbles Server app on macOS." These commands are local process-manager operations, not API calls. ```bash +bluebubbles server open bluebubbles server start bluebubbles server status bluebubbles server stop diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx index 2cd5520..3d5dbe8 100644 --- a/docs/quickstart.mdx +++ b/docs/quickstart.mdx @@ -45,29 +45,31 @@ export BLUEBUBBLES_PASSWORD=your-server-password bluebubbles doctor bluebubbles ping bluebubbles server info -bluebubbles chat list -bluebubbles message list --chat 'iMessage;+;chat123' -bluebubbles message send --chat 'iMessage;+;chat123' --message 'hello from bluebubbles' +bluebubbles chats list +bluebubbles messages list --chat 'iMessage;+;chat123' +bluebubbles messages send --chat 'iMessage;+;chat123' --message 'hello from bluebubbles' ``` Message pagination defaults to `--limit 50`. Page manually with offset: ```bash -bluebubbles message list --chat 'iMessage;+;chat123' --limit 50 --offset 0 --json -bluebubbles message list --chat 'iMessage;+;chat123' --limit 50 --offset 50 --json +bluebubbles messages list --chat 'iMessage;+;chat123' --limit 50 --offset 0 --json +bluebubbles messages list --chat 'iMessage;+;chat123' --limit 50 --offset 50 --json ``` Filter by date range, common flags, or raw `where`: ```bash -bluebubbles message list --chat 'iMessage;+;chat123' --after 1710000000 --before 1710086400 --json -bluebubbles message list --chat 'iMessage;+;chat123' --text 'hello' --not-from-me --json -bluebubbles message list --chat 'iMessage;+;chat123' --from-me --has-attachments --json -bluebubbles message list --where '[{"statement":"message.text LIKE :q","args":{"q":"%hello%"}}]' --json +bluebubbles messages list --chat 'iMessage;+;chat123' --after 1710000000 --before 1710086400 --json +bluebubbles messages list --chat 'iMessage;+;chat123' --text 'hello' --not-from-me --json +bluebubbles messages list --chat 'iMessage;+;chat123' --from-me --has-attachments --json +bluebubbles messages list --where '[{"statement":"message.text LIKE :q","args":{"q":"%hello%"}}]' --json ``` `--text`, `--from`, and `--has-attachments` apply client-side to the returned page; use `--where` for raw server-side filtering. +Use `-o wide` for richer human-readable list output, and `--verbose` for API diagnostics to stderr. + ## Local server lifecycle ```bash diff --git a/package.json b/package.json index c1cb7d3..4cfdb3b 100644 --- a/package.json +++ b/package.json @@ -19,16 +19,14 @@ "test": "bun test src/index.test.ts src/lib/*.test.ts", "test:commands": "bun run scripts/test-commands.ts", "test:commands:strict": "TEST_COMMANDS_STRICT=1 bun run scripts/test-commands.ts", - "docs:sync-openapi": "bun run scripts/sync-openapi.ts", - "docs:dev": "bun run docs:sync-openapi && cd docs && mint dev --no-open", - "docs:validate": "bun run docs:sync-openapi && cd docs && mint validate", + "docs:dev": "python3 -m http.server 3005 --directory scalar", + "docs:validate": "test -f scalar/index.html", "release": "bun run check && bun run build && npm publish --cache /tmp/npm-cache" }, "devDependencies": { "@types/bun": "^1.3.12", "@types/columnify": "^1.5.4", "@types/node": "^25.6.0", - "mint": "^4.2.507", "openapi-typescript": "^7.13.0", "tsc-alias": "^1.8.16", "typescript": "^6.0.2", diff --git a/scalar/index.html b/scalar/index.html new file mode 100644 index 0000000..700bfc2 --- /dev/null +++ b/scalar/index.html @@ -0,0 +1,69 @@ + + + + + + BlueBubbles CLI Docs + + + + +
+

BlueBubbles CLI Docs

+
+ README + Quickstart + CLI Reference + Local Server +
+
+ Interactive API reference from the official OpenAPI spec. +
+
+ + + + +