lark-event

Name: lark-event
Author: larksuite

bylarksuite· 47 skills

Installs

387k

Stars

16k

Forks

1.2k

How to install lark-event?

larksuite/cli/lark-event

$npx -y skills add larksuite/cli --skill lark-event

Installs into the current project.

›Prefer a prompt? Paste this to your agent

Use this skill

Run `npx skills use "https://github.com/larksuite/cli" --skill "larksuite/cli/lark-event"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the whole pack

Use the skills in "https://github.com/larksuite/cli" that are relevant to the current task. Run `npx skills add "https://github.com/larksuite/cli"` and select the relevant skills, then follow their instructions.

Files · 1

View on GitHub

SKILL.md

1	# Lark Events
2
3	> Prerequisite: Read [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) first for authentication, `--as user/bot` switching, `Permission denied` handling, and safety rules.
4
5	## Core commands
6
7	\| Command \| Purpose \|
8	\|------\|------\|
9	\| `lark-cli event list [--json]` \| List all subscribable EventKeys \|
10	\| `lark-cli event schema <EventKey> [--json]` \| Show an EventKey's params and output schema \|
11	\| `lark-cli event consume <EventKey> [flags]` \| Blocking consume; events → stdout NDJSON \|
12	\| `lark-cli event status [--json] [--fail-on-orphan]` \| Inspect the local bus daemon status \|
13	\| `lark-cli event stop [--all] [--force]` \| Stop the bus daemon \|
14
15
16	## Common flags
17
18	\| Flag \| Description \|
19	\|---\|---\|
20	\| `--param key=value` / `-p` \| Business params (repeatable; comma-separated for multi-value). Unknown keys fail with valid names listed inline \|
21	\| `--jq <expr>` \| jq expression to filter / transform each event; empty output skips the event \|
22	\| `--max-events N` \| Exit after N events. Default 0 = unlimited \|
23	\| `--timeout D` \| Exit after duration D (e.g. `30s`, `2m`). Default 0 = no timeout. Whichever of `--max-events` / `--timeout` fires first wins \|
24	\| `--output-dir <dir>` \| Write each event as a file (relative paths only; prevents traversal) \|
25	\| `--quiet` \| Suppress stderr diagnostics. AI should not use this — it silences the ready marker \|
26	\| `--as user\\|bot\\|auto` \| Identity for the session (see lark-shared) \|
27
28
29	## Examples
30
31	```bash
32	# Default: stream every event for the key (no filter, no projection)
33	lark-cli event consume im.message.receive_v1 --as bot
34
35	# Grab one sample event to inspect payload shape
36	lark-cli event consume im.message.receive_v1 --max-events 1 --timeout 30s --as bot
37
38	# Run for 10 minutes then auto-exit
39	lark-cli event consume im.message.receive_v1 --timeout 10m --as bot
40
41	# Consume multiple EventKeys concurrently (one shape per process, no dispatcher)
42	lark-cli event consume im.message.receive_v1 --as bot > receive.ndjson &
43	lark-cli event consume im.message.reaction.created_v1 --as bot > reaction.ndjson &
44	wait
45
46	```
47
48	## Call flow
49
50	1. `lark-cli event list --json` → pick a legal key
51	2. `lark-cli event schema <key> --json` → read `resolved_output_schema` + `jq_root_path` to determine field paths
52	3. `lark-cli event consume <key> [--jq '<expr>']` → consume
53
54	## Subprocess contract
55
56	### Ready marker
57
58	`event consume`'s stderr emits a fixed line `[event] ready event_key=<key>`. Parent processes should block on stderr until this line appears, then start reading stdout. Do not fall back to `sleep`.
59
60	### stdin EOF = graceful exit
61
62	`event consume` treats stdin close as a shutdown signal (wired for AI subprocess callers). Bounded runs are exempt: when `--max-events` or `--timeout` is set (> 0), stdin EOF is ignored and the run exits only via its own bound, timeout, or SIGTERM. For unbounded runs, `< /dev/null` / `nohup` / systemd's default `StandardInput=null` will cause an immediate graceful exit (stderr `reason: signal`). To keep an unbounded run alive:
63
64	- Feed stdin a source that never EOFs: `< <(tail -f /dev/null)`
65	- Or run bounded: `--max-events N` / `--timeout D`
66
67	### Exit codes & reason
68
69	On exit, the last stderr line is `[event] exited — received N event(s) in Xs (reason: ...)`.
70
71	\| exit code \| reason \| Trigger \|
72	\|---\|---\|---\|
73	\| 0 \| `reason: limit` \| `--max-events` reached \|
74	\| 0 \| `reason: timeout` \| `--timeout` reached \|
75	\| 0 \| `reason: signal` \| Ctrl+C / SIGTERM / stdin EOF (stdin EOF applies to unbounded runs only) \|
76	\| 1 \| JSON error envelope on stderr \| Lark API business failure during pre-consume setup (for example subscription create/delete) \|
77	\| 2 \| JSON error envelope on stderr (no `exited` line) \| Validation failure (unknown EventKey, bad `--param` / `--jq`, another bus already connected) \|
78	\| 3 \| JSON error envelope on stderr \| Auth failure (missing token, missing scopes) \|
79	\| 4 / 5 \| JSON error envelope on stderr \| Network / internal failure (bus startup, handshake, file I/O) \|
80
81	Startup and runtime failures emit a structured JSON envelope on stderr: `{"ok":false,"error":{"type","subtype","param","message","hint",...}}` (the envelope may also carry top-level `identity` / `_notice` siblings). Parse `error.type` / `error.subtype` to branch (e.g. `missing_scope` carries a `missing_scopes` list), `error.param` to find the offending flag, and `error.hint` for the recovery action — do not regex-match message text.
82
83	Orchestrators should treat `reason: limit/timeout/signal` (all exit 0) as "business completion" and non-zero as "failure".
84
85	### Never `kill -9`
86
87	Avoid `kill -9` on consume processes: for EventKeys with a PreConsume hook (those that register server-side subscriptions via OAPI), `kill -9` skips the OAPI unsubscribe and leaks server-side subscriptions (symptoms: "subscription already exists" on restart, duplicate event delivery). Prefer SIGTERM or closing stdin.
88
89	### One consume, one EventKey (multi-key = multi-shell)
90
91	The command takes exactly one positional argument; `k1,k2` and wildcards are unsupported. Listening to N keys means N subprocesses — this is intentional:
92
93	- One shape per process stdout; no dispatcher logic required in the AI
94	- Fault isolation (one key failing doesn't affect others)
95	- Independent `--as` / `--jq` / `--max-events` / `--timeout` per key
96
97	All N consumers share a single bus daemon (UDS local IPC), so the overhead is small
98
99	## Writing jq via schema
100
101	`event schema <key> --json` is the source of truth for writing `--jq`. Four things to look at:
102
103	(1) Where fields start — see `jq_root_path`
104
105	- Value `"."` → fields are at the top level, write `.chat_id`
106	- Value `".event"` → fields are inside a V2 envelope, write `.event.chat_id`
107
108	(2) Field list and types — see `resolved_output_schema.properties.<name>`
109
110	Each field carries `type` / `description`, and some also have `format`. Snippet (from `event schema im.message.receive_v1 --json`):
111
112	```json
113	{
114	"chat_id": {"type":"string", "format":"chat_id", "description":"Chat ID, prefixed with oc_"},
115	"sender_id": {"type":"string", "format":"open_id", "description":"Sender open_id, prefixed with ou_"},
116	"create_time": {"type":"string", "format":"timestamp_ms", "description":"Send time as ms-epoch string"}
117	}
118	```
119
120	(3) Field semantics — see the `format` tag
121
122	Lark-defined semantic tags (not JSON Schema's standard `format`). Common values: `open_id` / `chat_id` / `message_id` / `timestamp_ms` / `email`. Purpose: distinguish "same string type, different meanings" fields so you can reverse-lookup via API or convert formats.
123
124	(4) Decoded state — read the field's `description`
125
126	`event consume` runs Process hooks that may pre-decode some payload fields (flattening V2 envelopes, rendering `.content` to plain text, etc.) — behavior differs from raw OAPI. Always read the field's `description` before writing jq, especially for generic field names like `content` / `data` / `body` / `payload`.
127
128	Why it matters: blindly applying `fromjson` to an already-decoded text field makes jq error on every event and silently drop it — the consumer looks alive but emits nothing, with only a single `WARN` line buried on stderr. (This is the general behavior: any jq runtime error skips the event with a one-line WARN; the loop does not abort.)
129
130	Don't shortcut the schema: when projecting `event schema --json` with jq, do not strip `.description` from `properties` — that's the field that tells you whether a field is already decoded. Dump the full property objects, not just keys.
131
132	---
133
134	Aside: `--param`'s valid parameters also live in the schema — the `params` section lists `name` / `type` / `required` / `enum` / `default` / `description`; section missing = this key accepts no `--param`.
135
136	## Topic index
137
138	\| Topic \| Reference \| Coverage \|
139	\|------------\|------------------------------------------------------------------------------\|---\|
140	\| Application \| [`references/lark-event-application.md`](references/lark-event-application.md) \| Catalog of Application EventKeys, including `application.bot.menu_v6` for custom bot menu push events + flattened `event_key` / operator fields + jq recipe \|
141	\| Approval \| [`references/lark-event-approval.md`](references/lark-event-approval.md) \| Catalog of 2 Approval EventKeys (`approval.instance.status_changed_v4`, `approval.task.status_changed_v4`) + optional/multi `subscription_type` pre-registration + user-auth subscription lifecycle + flat output field reference \|
142	\| IM \| [`references/lark-event-im.md`](references/lark-event-im.md) \| Catalog of 12 IM EventKeys + shape notes (flat vs V2 envelope) + `im.message.receive_v1` field gotchas (`sender_id` is open_id only; `.content` is plain text except for `interactive` cards) + common jq recipes (filter by chat_type / message_type / sender); for `card.action.trigger` see also [`../lark-im/references/lark-im-card-action-reply.md`](../lark-im/references/lark-im-card-action-reply.md) \|
143	\| Task \| [`references/lark-event-task.md`](references/lark-event-task.md) \| Catalog of 1 Task EventKey (`task.task.update_user_access_v2`) + Native V2 envelope shape + task commit types + user/bot subscription notes \|
144	\| VC \| [`references/lark-event-vc.md`](references/lark-event-vc.md) \| Catalog of 4 VC EventKeys (`vc.meeting.participant_meeting_started_v1`, `vc.meeting.participant_meeting_joined_v1`, `vc.meeting.participant_meeting_ended_v1`, `vc.note.generated_v1`) + field reference + source type semantics (meeting only) \|
145	\| Minutes \| [`references/lark-event-minutes.md`](references/lark-event-minutes.md) \| Catalog of 1 Minutes EventKey (`minutes.minute.generated_v1`) + field reference + source type semantics (meeting only) \|
146	\| Whiteboard \| [`references/lark-event-whiteboard.md`](references/lark-event-whiteboard.md) \| Catalog of 1 Board EventKey (`board.whiteboard.updated_v1`) + per-whiteboard subscription model (requires `-p whiteboard_id=<token>`) + payload field reference (whiteboard_id / operator_ids triple-id) \|

6 picks

Type

Run `npx skills use "https://github.com/larksuite/cli" --skill "larksuite/cli/lark-event"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the skills in "https://github.com/larksuite/cli" that are relevant to the current task. Run `npx skills add "https://github.com/larksuite/cli"` and select the relevant skills, then follow their instructions.

lark-event

How to install lark-event?

Related

lark-event

How to install lark-event?

Related