diff --git a/AGENTS.md b/AGENTS.md index 889d2513..50c632ea 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -299,12 +299,13 @@ When adding COMMANDS sections in `src/help.ts`, use `chalk.bold()` for headers, ### Flag conventions - All flags kebab-case: `--my-flag` (never camelCase) +- **No duplicate defaults in descriptions**: oclif appends `[default: N]` to `--help` automatically. Don't repeat it in `description`. Exceptions: falsy defaults (`0`, `false`) — oclif suppresses these, so keep them in the description. Behavioral phrases like `"defaults to current app"` are fine too. - `--app`: `"The app ID or name (defaults to current app)"` (for commands with `resolveAppId`), `"The app ID (defaults to current app)"` (for commands without) -- `--limit`: `"Maximum number of results to return"` with `min: 1` (oclif shows `[default: N]` automatically, don't duplicate in description) +- `--limit`: `"Maximum number of results to return"` with `min: 1` - `--duration`: Use `durationFlag` from `src/flags.ts`. `"Automatically exit after N seconds"`, alias `-D`. - `--rewind`: Use `rewindFlag` from `src/flags.ts`. `"Number of messages to rewind when subscribing (default: 0)"`. Apply with `this.configureRewind(channelOptions, flags.rewind, flags, component, channelName)`. - `--start`/`--end`: Use `timeRangeFlags` from `src/flags.ts` and parse with `parseTimestamp()` from `src/utils/time.ts`. Accepts ISO 8601, Unix ms, or relative (e.g., `"1h"`, `"30m"`, `"2d"`). -- `--direction`: `"Direction of message retrieval (default: backwards)"` or `"Direction of log retrieval"`, options `["backwards", "forwards"]`. +- `--direction`: `"Direction of message retrieval"` or `"Direction of log retrieval"`, options `["backwards", "forwards"]`. - Channels use "publish", Rooms use "send" (matches SDK terminology) - Command descriptions: imperative mood, sentence case, no trailing period (e.g., `"Subscribe to presence events on a channel"`) diff --git a/README.md b/README.md index 425661d1..bb4b2e0a 100644 --- a/README.md +++ b/README.md @@ -865,7 +865,7 @@ FLAGS --json Output in JSON format --pretty-json Output in colorized JSON format --token-only Output only the token string without any formatting or additional information - --ttl= [default: 3600] Time to live in seconds (default: 3600, 1 hour) + --ttl= [default: 3600] Time to live in seconds DESCRIPTION Create an Ably Token with capabilities @@ -910,7 +910,7 @@ FLAGS --json Output in JSON format --pretty-json Output in colorized JSON format --token-only Output only the token string without any formatting or additional information - --ttl= [default: 3600] Time to live in seconds (default: 3600, 1 hour) + --ttl= [default: 3600] Time to live in seconds DESCRIPTION Create an Ably JWT token with capabilities @@ -1401,11 +1401,15 @@ DESCRIPTION Manage annotations on Ably Pub/Sub channel messages EXAMPLES - $ ably channels annotations publish my-channel "01234567890:0" "reactions:flag.v1" --name thumbsup + $ ably channels annotations publish my-channel "01234567890:0" "metrics:total.v1" + + $ ably channels annotations publish my-channel "01234567890:0" "reactions:unique.v1" --name thumbsup $ ably channels annotations subscribe my-channel $ ably channels annotations get my-channel "01234567890:0" + + $ ably channels annotations delete my-channel "01234567890:0" "receipts:flag.v1" ``` _See code: [src/commands/channels/annotations/index.ts](https://github.com/ably/ably-cli/blob/v0.17.0/src/commands/channels/annotations/index.ts)_ @@ -1436,13 +1440,15 @@ DESCRIPTION Delete an annotation from a channel message EXAMPLES - $ ably channels annotations delete my-channel "01234567890:0" "reactions:flag.v1" --name thumbsup + $ ably channels annotations delete my-channel "01234567890:0" "receipts:flag.v1" - $ ably channels annotations delete my-channel "01234567890:0" "reactions:multiple.v1" --name thumbsup + $ ably channels annotations delete my-channel "01234567890:0" "categories:distinct.v1" --name important - $ ably channels annotations delete my-channel "01234567890:0" "reactions:flag.v1" --json + $ ably channels annotations delete my-channel "01234567890:0" "reactions:unique.v1" --name thumbsup - $ ably channels annotations delete my-channel "01234567890:0" "reactions:flag.v1" --pretty-json + $ ably channels annotations delete my-channel "01234567890:0" "rating:multiple.v1" --name stars + + $ ably channels annotations delete my-channel "01234567890:0" "receipts:flag.v1" --json ``` _See code: [src/commands/channels/annotations/delete.ts](https://github.com/ably/ably-cli/blob/v0.17.0/src/commands/channels/annotations/delete.ts)_ @@ -1509,15 +1515,17 @@ DESCRIPTION Publish an annotation on a channel message EXAMPLES - $ ably channels annotations publish my-channel "01234567890:0" "reactions:flag.v1" --name thumbsup + $ ably channels annotations publish my-channel "01234567890:0" "metrics:total.v1" + + $ ably channels annotations publish my-channel "01234567890:0" "receipts:flag.v1" - $ ably channels annotations publish my-channel "01234567890:0" "reactions:multiple.v1" --name thumbsup --count 3 + $ ably channels annotations publish my-channel "01234567890:0" "categories:distinct.v1" --name important - $ ably channels annotations publish my-channel "01234567890:0" "reactions:flag.v1" --data '{"key":"value"}' + $ ably channels annotations publish my-channel "01234567890:0" "reactions:unique.v1" --name thumbsup - $ ably channels annotations publish my-channel "01234567890:0" "reactions:flag.v1" --json + $ ably channels annotations publish my-channel "01234567890:0" "rating:multiple.v1" --name stars --count 4 - $ ably channels annotations publish my-channel "01234567890:0" "reactions:flag.v1" --pretty-json + $ ably channels annotations publish my-channel "01234567890:0" "metrics:total.v1" --json ``` _See code: [src/commands/channels/annotations/publish.ts](https://github.com/ably/ably-cli/blob/v0.17.0/src/commands/channels/annotations/publish.ts)_ @@ -1552,11 +1560,11 @@ EXAMPLES $ ably channels annotations subscribe my-channel --type "reactions:flag.v1" - $ ably channels annotations subscribe my-channel --json - - $ ably channels annotations subscribe my-channel --pretty-json + $ ably channels annotations subscribe my-channel --type "metrics:total.v1" $ ably channels annotations subscribe my-channel --duration 30 + + $ ably channels annotations subscribe my-channel --json ``` _See code: [src/commands/channels/annotations/subscribe.ts](https://github.com/ably/ably-cli/blob/v0.17.0/src/commands/channels/annotations/subscribe.ts)_ @@ -1698,8 +1706,8 @@ ARGUMENTS FLAGS -v, --verbose Output verbose logs - --cipher= Decryption key for encrypted messages (AES-128) - --direction=