OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add ably/agent-skills --skill debugging-with-ably-cli
ALWAYS use when diagnosing Ably issues — messages not arriving, presence not updating, connection failures, auth errors (40101, 40142, 40160), channel lifecycle problems, push notification issues, Chat room issues, Spaces member/cursor issues, or any Ably error code. Provides Ably CLI commands to observe live traffic, inspect state, and simulate clients. Not for building new Ably integrations (use using-ably skill instead).
npx skills add ably/agent-skills --skill debugging-with-ably-cli
The Ably CLI (@ably/cli, install via npm install -g @ably/cli) lets you observe, test, and simulate Ably operations from the terminal — faster than console.log or browser DevTools.
Discovering commands: Run ably --help for command groups, ably <command> --help for subcommands, flags, and examples. The CLI is self-documenting. This skill teaches what's possible and when to use it.
persisted: true. If not enabled, tell the user and suggest enabling via channel rules or the dashboard.presence capability; subscribing to presence events requires subscribe capability. A client can observe who's present without entering itself. Without the right capability, presence operations fail with 40160.publish:["chat:*"] allows publish on channels starting with chat: (e.g., chat:room-1), but NOT on a channel literally named chat. The colon separator and wildcard pattern matter — this is a common cause of 40160 errors.authUrl or authCallback configured for renewal, the token expires; any connection will fail and any other API requests will be refused. Test token issuance via the CLI to verify auth flow works independently of the app.[meta]* capability. All ably logs commands subscribe to logs metachannels ([meta]log, [meta]channel.lifecycle, etc.). A key scoped to * does not match metachannels — the key needs [meta]* or [*]* in its capability resource list. The app's root API key has [*]* by default. If ably logs commands fail with 40160, check the key's capability scope. For deep inspection of a single channel (per-channel stats, regional breakdown, attached integrations), use ably channels inspect <channel> to open the dashboard's channel inspector — this uses privileged inspection metachannels ([meta]inspect:*) not currently available to the CLI.ably accounts login --endpoint <host> to target the right cluster.help.ably.io/error/{code}, or use ably support ask "error {code}".The CLI needs credentials. Two approaches:
Credentials from the project (quick, no login):
Set ABLY_API_KEY as an environment variable. Find the key from the project's environment files and export it (e.g. export ABLY_API_KEY=...). Alternatively, if you have a token (e.g., from the app's auth server), use ABLY_TOKEN instead. If the key is for a production app, note this to the user before using it.
Log in to the CLI (for extended debugging or account-level commands):
ably login opens a browser for OAuth. Once logged in, use ably apps list and ably apps switch to target the right app, and ably auth keys list to see available keys and their capabilities.
If no credentials are available, ask the user to check that their Ably environment variables are set (e.g. ABLY_API_KEY) or to run ably login to authenticate.
Subscribe to channels, presence, occupancy, logs, and stats in real time — you see exactly what Ably sees.
channel.lifecycle, channel.occupancy, channel.presence, connection.lifecycle, push.publish), rewind to catch recent events.Act as a participant — simulate one end of a conversation to test the other (client when debugging server, server when debugging client).
{"role": "server"}).Query and modify app configuration to diagnose config-related issues.
ably support ask "your question" — searches Ably docs and FAQs. Use --continue for follow-ups.ably status checks platform health.Many commands (subscribe, presence enter, stats --live, occupancy subscribe) are long-running — they stream output until Ctrl+C or --duration N expires. Run these as background tasks so they don't block your workflow. Start a subscribe in the background, reproduce the issue, then check the output.
| State | Meaning | Diagnostic |
|---|---|---|
connecting | Attempting connection | Normal on startup; if stuck, check network/auth |
connected | Active WebSocket | Healthy |
disconnected | Temporary loss, SDK retries | Transient is normal; recurring = network issues → watch connection lifecycle logs |
suspended | Offline >2 min, less frequent retries | Test connection to check connectivity |
failed | Permanent failure, SDK won't retry | Almost always auth — test with the specific API key |
closed | Explicitly closed by code | Search for .close() calls |
| State | Meaning | Diagnostic |
|---|---|---|
initialized | Channel object created, not yet attached | Normal before first subscribe/publish |
attaching | Requesting attach from server | If stuck, check connection state and auth capabilities |
attached | Active — messages flowing | Healthy |
detaching | Requesting detach | Normal during cleanup |
detached | Not attached, no messages flowing | Check if detach() was called intentionally |
suspended | Attach failed, will retry | Usually follows connection suspension — check connection state first |
failed | Permanent channel failure | Often capability denied (40160) or invalid channel name |
| Environment | Symptom | Root Cause | Diagnostic |
|---|---|---|---|
| Next.js SSR | Connection fails during render | No WebSocket in server-side render | Guard with typeof window or useEffect |
| Serverless (Lambda, Edge) | Stale/frozen connections | Connection frozen between invocations | Use Ably.Rest server-side |
| React StrictMode | Duplicate messages, presence flicker | Double-render duplicates subscriptions | Check occupancy — much higher than expected = duplicates |
| CSP headers | WebSocket blocked | Ably domains not in connect-src | Test connection — ws fails, xhr works = CSP |
| Corporate proxy | WebSocket fails silently | Proxy blocking upgrade | Test connection — ws fails, xhr works = proxy |
| Mobile background | Messages missed after resume | OS kills WebSocket | Check channel history for messages sent during gap |
Messages not arriving
├── Is anyone on the channel? → list channels with a prefix filter
├── Was anything published? → check channel history (2 min only without persistence)
├── Can I see messages live? → subscribe to the channel
├── Test round-trip → subscribe in background, publish from main terminal
└── Check channel lifecycle → subscribe to channel lifecycle logs, or inspect the channel in the dashboard
Presence not working
├── Who is actually present? → subscribe to presence on the channel
├── Simulate a client joining → enter presence with custom client-id and data
├── Check presence member count → get channel occupancy
│ (stale members? ungraceful disconnects take ~15s to be removed)
└── Watch all presence events → subscribe to logs filtered by channel.presence, or inspect the channel in the dashboard
Connection problems
├── Can I connect at all? → test connection (try ws and xhr separately)
├── Is Ably up? → check service status
├── Watch connection lifecycle → subscribe to connection lifecycle logs
└── Connection count vs plan limit → check app stats in live mode
Auth errors
├── Is the API key valid? → test connection with the specific key
├── What capabilities does key have? → list auth keys
├── Using tokens (JWT or Ably)? → issue a test token via CLI to verify the key can create valid tokens
│ (CLI token issuance tests the key, not your app's authUrl/authCallback)
├── Token expired (40142)? → check TTL and renewal config (authUrl/authCallback)
└── Look up the error code → ask the support agent or fetch help.ably.io/error/{code}
Channel state / lifecycle issues
├── Watch channel events → subscribe to channel lifecycle logs
├── Watch all app meta events → subscribe to all logs
├── Check channel occupancy → get or subscribe to occupancy
└── Check channel rules/config → list channel rules (persistence, TLS, push, etc.)
Push notifications not working
├── Watch push delivery logs → subscribe to push logs (meta channel)
├── Check push log history → get push log history
├── Is push enabled on namespace? → list channel rules, check push-enabled
└── Check integration rules → list integrations, check source type and channel filter
Integration rules not firing
├── List all integrations → list integrations to see rules, source types, status
├── Check source type matches → source can be channel.message, channel.presence,
│ channel.lifecycle, or presence.message
├── Check channel filter → filter pattern must match the channel name
├── Is the rule enabled? → check integration status (enabled/disabled)
└── Check for delivery errors → check log history — the log metachannel captures
errors sending on integrations
Queue issues
├── Are queues configured? → list queues
├── Is the integration routing to it?→ list integrations, check AMQP rule target
└── Check message flow → subscribe to the source channel to verify messages exist
Chat room issues (@ably/chat)
├── Are messages flowing? → subscribe to room messages
│ (if CLI sees messages but app doesn't → room.attach() likely missing)
├── Check room presence → subscribe to room presence
├── Check occupancy → get room occupancy
├── Check underlying channel events → inspect the room's channels in the dashboard, or subscribe to channel lifecycle logs and look for the room's channel names
└── Send a test message → send a message to the room from CLI
Spaces issues (@ably/spaces)
├── Who is in the space? → subscribe to space members
├── Watch cursors → subscribe to space cursors
├── Watch locations → subscribe to space locations
└── Check locks → get all locks in the space