{"id":50512649,"url":"https://github.com/anmho/bluebubbles-cli","last_synced_at":"2026-06-02T21:04:37.466Z","repository":{"id":350933621,"uuid":"1208770604","full_name":"anmho/bluebubbles-cli","owner":"anmho","description":"Terminal-first BlueBubbles CLI for chats, messages, and server workflows.","archived":false,"fork":false,"pushed_at":"2026-05-26T05:56:38.000Z","size":359,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T06:34:13.840Z","etag":null,"topics":["bluebubbles","bun","cli","imessage","scalar"],"latest_commit_sha":null,"homepage":"https://anmho.github.io/bluebubbles-cli/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anmho.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-12T18:11:59.000Z","updated_at":"2026-05-26T05:56:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/anmho/bluebubbles-cli","commit_stats":null,"previous_names":["anmho/bluebubbles-cli"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/anmho/bluebubbles-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anmho%2Fbluebubbles-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anmho%2Fbluebubbles-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anmho%2Fbluebubbles-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anmho%2Fbluebubbles-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anmho","download_url":"https://codeload.github.com/anmho/bluebubbles-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anmho%2Fbluebubbles-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33835766,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bluebubbles","bun","cli","imessage","scalar"],"created_at":"2026-06-02T21:04:36.117Z","updated_at":"2026-06-02T21:04:37.460Z","avatar_url":"https://github.com/anmho.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bluebubbles-cli\n\n`bluebubbles-cli` is a terminal-first BlueBubbles CLI.\n\nIt focuses on real workflows: chats, messages, server operations, and clean output (`table`, `wide`, `json`).\n\n## Install\n\n```bash\nnpm install -g bluebubbles-cli\n```\n\nFrom source:\n\n```bash\nbun install\nbun run build\nbun link\n```\n\n## Development\n\n```bash\nbun run check\nbun test\nbun run test:commands\nbun run build\n```\n\nRun from source:\n\n```bash\nbun run dev -- --help\n```\n\nOutput controls:\n\n```bash\nbluebubbles contacts list\nbluebubbles chats list -o wide\nbluebubbles messages list --chat 'iMessage;+;chat123' -o wide\nbluebubbles chats list -o json\n```\n\nHuman-readable output (`columnify`) is the default:\n\n```text\nNAME            PHONE             EMAIL\nAlex Rivera     +1-555-0100       alex@example.com\nTaylor Kim      +1-555-0199       taylor@example.com\n```\n\n`messages list` uses the same default table style:\n\n```text\nGUID                        FROM       TEXT                          AGE   CHAT\n4b2f...e91                  me         hello from bluebubbles        2m    iMessage;+;chat123\n9aa1...77c                  +1555...   sounds good, see you soon     8m    iMessage;+;chat123\n```\n\n`messages list -o wide` includes extra columns:\n\n```text\nGUID                        FROM       TEXT                          AGE   CHAT                     FROM_ME   ATTACHMENTS   CREATED_AT              CHAT_NAME\n4b2f...e91                  me         hello from bluebubbles        2m    iMessage;+;chat123      yes       0             2026-04-12 21:08:14     Weekend Plans\n9aa1...77c                  +1555...   sounds good, see you soon     8m    iMessage;+;chat123      no        1             2026-04-12 21:02:07     Weekend Plans\n```\n\nJSON output is available with `-o json` or `--json`:\n\n```json\n{\n  \"ok\": true,\n  \"data\": [\n    {\n      \"displayName\": \"Alex Rivera\",\n      \"phoneNumbers\": [{ \"address\": \"+1-555-0100\" }],\n      \"emails\": [{ \"address\": \"alex@example.com\" }]\n    }\n  ]\n}\n```\n\nFor messages:\n\n```bash\nbluebubbles messages list --chat 'iMessage;+;chat123'\nbluebubbles messages list --chat 'iMessage;+;chat123' -o wide\nbluebubbles messages list --chat 'iMessage;+;chat123' --json\n```\n\n`-o wide` affects table output only. JSON output remains the full payload (`-o json` / `--json`).\n\nPagination defaults are conservative for message-heavy commands:\n\n- `bluebubbles messages list` defaults to `--limit 50`\n- `bluebubbles chats messages \u003cguid\u003e` defaults to `--limit 50`\n\n## Query and filter examples\n\nGet all messages for one conversation in pages:\n\n```bash\nbluebubbles messages list --chat 'iMessage;+;chat123' --limit 50 --offset 0 --json\nbluebubbles messages list --chat 'iMessage;+;chat123' --limit 50 --offset 50 --json\nbluebubbles messages list --chat 'iMessage;+;chat123' --limit 50 --offset 100 --json\n```\n\nFilter by date window (epoch seconds):\n\n```bash\nbluebubbles messages list --chat 'iMessage;+;chat123' --after 1710000000 --before 1710086400 --json\n```\n\nCommon filters:\n\n```bash\nbluebubbles messages list --chat 'iMessage;+;chat123' --text 'invoice' --limit 50 --json\nbluebubbles messages list --chat 'iMessage;+;chat123' --from '+15551234567' --not-from-me --json\nbluebubbles messages list --chat 'iMessage;+;chat123' --from-me --has-attachments --json\n```\n\nCommon filters are applied client-side to the returned page. Use `--where` for raw server-side filtering.\n\nAdvanced filtering via raw API `where` clauses:\n\n```bash\nbluebubbles messages list \\\n  --where '[{\"statement\":\"message.text LIKE :q\",\"args\":{\"q\":\"%hello%\"}}]' \\\n  --limit 50 \\\n  --json\n```\n\nConversation endpoint alternative:\n\n```bash\nbluebubbles chats messages 'iMessage;+;chat123' --limit 50 --offset 0 --json\nbluebubbles chats messages 'iMessage;+;chat123' --after 1710000000 --before 1710086400 --json\n```\n\n## Command shape\n\n```bash\nbluebubbles ping\nbluebubbles server info\nbluebubbles server open\nbluebubbles server status\nbluebubbles server logs\nbluebubbles server logs --source api\nbluebubbles chats list\nbluebubbles messages send --chat \u003cguid\u003e --message \"hello\"\nbluebubbles messages schedule list\nbluebubbles handle availability \u003caddress\u003e\nbluebubbles attachment download \u003cguid\u003e\nbluebubbles contact query --address user@example.com\nbluebubbles icloud account\n```\n\nVerbose diagnostics:\n\n```bash\nbluebubbles messages list --chat 'iMessage;+;chat123' --verbose\n```\n\n`--verbose` prints request/response diagnostics to stderr. You can also set `BLUEBUBBLES_VERBOSE=1`.\n\nRequest timeout defaults to `10000ms` and can be overridden with `BLUEBUBBLES_REQUEST_TIMEOUT_MS`.\n\n## Configuration\n\nPersist config:\n\n```bash\nbluebubbles config set baseUrl http://localhost:1234\nbluebubbles config set password your-server-password\n```\n\nOr use environment variables:\n\n```bash\nexport BLUEBUBBLES_BASE_URL=http://localhost:1234\nexport BLUEBUBBLES_PASSWORD=your-server-password\n```\n\nIf your password contains shell-special characters (for example `#`), quote it:\n\n```bash\nexport BLUEBUBBLES_PASSWORD='your#server#password'\n```\n\n## Docs\n\nDocs are served via Scalar and deployed to GitHub Pages.\n\n```bash\nbun run docs:dev\nbun run docs:validate\n```\n\nGitHub Pages workflow publishes `scalar/index.html` at:\n\n```text\nhttps://anmho.github.io/bluebubbles-cli/\n```\n\n`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).\n\nThe API Reference tab renders from `docs/openapi.yaml`, which is a pinned copy of the official BlueBubbles OpenAPI source:\n\n```text\nhttps://raw.githubusercontent.com/Jish2/bluebubbles-sdk/main/openapi.yaml\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanmho%2Fbluebubbles-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanmho%2Fbluebubbles-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanmho%2Fbluebubbles-cli/lists"}