命令行参考CLI reference

两个子命令，参数都是位置参数。

Two subcommands, both driven by positional arguments.

produce <topic> <value> [key] [host] [port]
consume <topic> [host] [port] [earliest|latest] [--max-messages <n>]

因为参数是位置参数，要指定靠后的参数，就必须把前面的都写出来。例如想连远程 broker，就得连 key 一起给出。

Because they are positional, giving a later argument means giving every argument before it — pointing at a remote broker means supplying the key as well.

produce

moon run --target native cmd/main -- produce <topic> <value> [key] [host] [port]

参数	必需	默认值	说明
`topic`	是	—	目标主题，必须已存在
`value`	是	—	消息内容，按 UTF-8 编码
`key`	否	无 key	消息 key，按 UTF-8 编码；省略时发送无 key 的记录
`host`	否	`127.0.0.1`	broker 地址
`port`	否	`9092`	broker 端口，取值 1–65535

Argument	Required	Default	Meaning
`topic`	yes	—	Target topic; it must already exist
`value`	yes	—	Message payload, encoded as UTF-8
`key`	no	no key	Message key, encoded as UTF-8; omit it to send a keyless record
`host`	no	`127.0.0.1`	Broker host
`port`	no	`9092`	Broker port, 1–65535

它通过 Producer::connect 连接主题，以 acks=-1 发送一条记录，等 broker 确认后打印返回的偏移量，然后关闭 producer。

It connects through Producer::connect, sends one record with acks=-1, waits for the broker's acknowledgement, prints the offset that came back, and closes the producer.

sent to topic "events" at offset 0

consume

moon run --target native cmd/main -- consume <topic> [host] [port] [earliest|latest] [--max-messages <n>]

参数	必需	默认值	说明
`topic`	是	—	要读取的主题，必须已存在
`host`	否	`127.0.0.1`	broker 地址
`port`	否	`9092`	broker 端口，取值 1–65535
`earliest` / `latest`	否	`earliest`	起始位置：从最早可用偏移量，还是从末尾开始
`--max-messages <n>`	否	无限制	打印 n 条记录后正常退出；`<n>` 必须 ≥ 1

Argument	Required	Default	Meaning
`topic`	yes	—	Topic to read; it must already exist
`host`	no	`127.0.0.1`	Broker host
`port`	no	`9092`	Broker port, 1–65535
`earliest` / `latest`	no	`earliest`	Start position: earliest available offset, or the end of the log
`--max-messages <n>`	no	unlimited	Exit cleanly after printing n records; `<n>` must be ≥ 1

它通过 Consumer::connect 连接主题，然后在一个循环里反复调用 Consumer::poll()，把每一批记录逐条打印出来。没有 --max-messages 时会一直轮询，直到 Ctrl-C。

It connects through Consumer::connect, then loops calling Consumer::poll() and prints every record from each batch. Without --max-messages it polls until Ctrl-C.

启动时先打印一行会话说明：

It opens with one line describing the session:

consuming topic "events" from 127.0.0.1:9092; press Ctrl-C to stop

之后每条记录一行，字段顺序固定：

Then one line per record, always in this order:

offset=0 timestamp=1757923200000 key=demo-key value=Hello from MoonBit

字段	来源
`offset`	记录在分区里的偏移量
`timestamp`	记录的墙上时钟毫秒值
`key`	key 解码为 UTF-8；没有 key 时显示 `<null>`
`value`	value 解码为 UTF-8；value 为空（tombstone）时显示 `<tombstone>`

Field	Source
`offset`	The record's offset within its partition
`timestamp`	The record's wall-clock timestamp in milliseconds
`key`	The key decoded as UTF-8; prints `<null>` when there is no key
`value`	The value decoded as UTF-8; prints `<tombstone>` for an empty (null) value

--max-messages 有两种写法 --max-messages 5 与 --max-messages=5 等价。它以参数的形式在解析早期被摘出来，所以可以出现在 argv 的任意位置——但位置参数仍然按剩余顺序排列，见下。

Two spellings for --max-messages --max-messages 5 and --max-messages=5 are equivalent. It is pulled out of argv early during parsing, so it may appear anywhere — but the positional arguments are then read from what remains, in order. See below.

位置参数要写在 --max-messages 之前 --max-messages 和它的取值会从位置参数序列里被移除。写成 consume events --max-messages 1 latest 时，latest 会落到 host 的位置上，于是程序把 latest 当成主机名去连接。把位置参数写在前面：consume events 127.0.0.1 9092 latest --max-messages 1。

Put positionals before --max-messages The flag and its value are removed from the positional sequence. Written as consume events --max-messages 1 latest, the word latest lands in the host slot and the program tries to connect to a host named latest. Keep positionals first: consume events 127.0.0.1 9092 latest --max-messages 1.

host 与 port 是一对只写 host 而不写 port 会让 port 取到下一个位置上的词。想连 kafka.example.com:9092 就两个都写： consume events kafka.example.com 9092 latest。

host and port travel together Giving a host without a port lets port pick up whatever word sits next. To reach kafka.example.com:9092, give both: consume events kafka.example.com 9092 latest.

参数校验Validation

取值在解析期就被检查，非法输入不会走到连接 broker 那一步。

Values are checked while parsing, so a bad one never reaches the broker.

输入	规则	违反时的输出
`port`	整数，且 1 ≤ port ≤ 65535	`invalid port: <v>` 或 `port must be between 1 and 65535: <v>`
起始位置	只接受 `earliest` 或 `latest`	`invalid start position: <v> (expected earliest or latest)`
`--max-messages`	必须是整数且 ≥ 1	`invalid --max-messages value: <v>` 或 `--max-messages must be at least 1: <v>`
`--max-messages` 缺值	后面必须跟一个取值	`--max-messages needs a value`

Input	Rule	Output when violated
`port`	An integer with 1 ≤ port ≤ 65535	`invalid port: <v>` or `port must be between 1 and 65535: <v>`
Start position	Only `earliest` or `latest`	`invalid start position: <v> (expected earliest or latest)`
`--max-messages`	An integer ≥ 1	`invalid --max-messages value: <v>` or `--max-messages must be at least 1: <v>`
`--max-messages` with no value	Must be followed by a value	`--max-messages needs a value`

两类失败，两种退出方式 缺少必需参数（没给 topic 或 value）时只打印一行用法然后正常结束，退出码为 0。取值非法（端口、起始位置、--max-messages）时程序中止，退出码非 0。脚本里要区分这两种情况，请看 stderr/stdout 上的文字而不是只看退出码。集成测试断言的是成功路径，因此不受影响。

Two kinds of failure, two kinds of exit A missing required argument (no topic or value) prints a one-line usage and returns normally with exit code 0. An invalid value (port, start position, --max-messages) aborts with a non-zero exit code. A script that needs to tell them apart should read the message rather than trust the exit code alone. The integration test asserts the success paths, so it is unaffected.

帮助与错误Help and errors

不带参数、-h 或 --help 都会打印内置帮助。未知子命令会先打印 unknown command: <name>，再打印帮助。

No arguments, -h or --help all print the built-in help. An unknown subcommand prints unknown command: <name> followed by the same help.

moon run --target native cmd/main -- --help

moonkafka demo

Usage:
  moon run --target native cmd/main -- produce <topic> <value> [key] [host] [port]
  moon run --target native cmd/main -- consume <topic> [host] [port] [earliest|latest]
    [--max-messages <n>]

Defaults:
  host       127.0.0.1
  port       9092
  start      earliest

--max-messages <n> stops the consumer after it has printed n records,
which is what scripts and tests use. Omit it to poll until Ctrl-C.

The topic must already exist. Press Ctrl-C to stop the consumer.