Libervia 0.9.0 常用 CLI 命令与工具详解

目标：系统整理 Libervia 0.9.0 命令行前端 libervia-cli 的常用命令族——profile 身份管理、消息收发、博客、PubSub、联系人、参数与探测、账户、文件、shell 交互模式等，全部命令与回显来自真实服务器实测（实测日期：2026-10-26），逐行照抄；并给出后端日志排障路径与常见问题。

一、环境信息

💡 回显约定：本机每次执行 CLI 命令，输出前均有一行 jinja2 兼容告警（Can't import sat_frontends.jp.output_template plugin, ignoring it: cannot import name 'Markup' from 'jinja2'）。这是 Debian 12 打包的 jinja2 与 CLI 输出模板插件的兼容提示，不影响任何命令功能。为节省篇幅，下文回显统一省略该行。

二、CLI 概览与命令总表

libervia-cli 是 Libervia 的命令行前端（历史名 jp，man 手册与社区文档仍常用此名；二进制不再提供 jp 别名）。它通过 D-Bus 会话总线调用后端能力，覆盖 IM、博客、PubSub、文件、账户等全部平台功能。

libervia-cli --help 实测回显：

usage: libervia-cli [-h] [--version]
                    {file,identity,encryption,bookmarks,ad-hoc,roster,debug,invitation,pubsub,input,pipe,event,avatar,merge-request,forums,param,shell,blocking,message,ping,application,app,uri,info,list,account,profile,blog}
                    ...

27 个顶层命令族一览：

版本确认：

libervia-cli --version

Libervia CLI 0.9.0a0 Copyright (C) 2009-2021 Jérôme Poisson, Adrien Cossa

通用参数约定（全族适用）：

• -p PROFILE, --profile PROFILE：指定 profile 名；
• --pwd PASSWORD：profile 密码（非交互脚本必带）；
• -c, --connect：执行前先连接该 profile；
• -v, --verbose：详细输出。

三、profile 族：身份管理

子命令：{create,delete,connect,modify,list,info}。

3.1 profile create / list / info

libervia-cli profile create admin -j admin@srv.lan -p q1w2e3r4

成功静默（退出码 0）。重复创建已存在的 profile：

Profile admin already exists.

libervia-cli profile list
libervia-cli profile info -p admin

admin
user1

jid: admin@srv.lan
autoconnect (backend): false

3.2 profile connect

libervia-cli profile connect -p admin --pwd q1w2e3r4 -c

成功静默。--pwd 提供 profile 密码，-c 表示连接前先让后端接入 XMPP 网络。省略 --pwd 时 CLI 交互提示输入；脚本环境会因读取不到终端输入而报 termios.error: (25, 'Inappropriate ioctl for device')——脚本场景务必显式带密码。

3.3 profile delete

profile 名为位置参数（不是 -p 选项，误用会报 unrecognized arguments: -p）：

libervia-cli profile delete test1 --force

成功静默。

四、message 族：消息收发与归档

子命令：{send,retract,mam}。

4.1 message send：发送消息

消息正文从 stdin 读入（不接受正文作为位置参数）：

echo '你好，这是 Libervia 0.9.0 的第一条 CLI 消息' | libervia-cli message send -p admin -c user1@srv.lan

发送成功静默退出。对端不在线时消息由服务器 MAM 归档留存。

4.2 message mam：归档查询

以 user1 身份回读 admin 发来的归档：

libervia-cli message mam -p user1 -c -W admin@srv.lan

[06:48] admin> 你好，这是 Libervia 0.9.0 的第一条 CLI 消息

-W 过滤对话方 JID。报 service-unavailable 说明服务器未启用 MAM 模块（Prosody 需在 modules_enabled 启用 "mam" 并重启）。

4.3 message retract：撤回消息

子命令 {send,retract,mam} 中的 retract 按消息 ID 撤回（XEP-0424），需知道目标消息 ID，常与 message mam 输出的 ID 配合使用。

五、blog 族：微博客

子命令：{set,get,edit,rename,repeat,preview,import,attachments}。博客基于 XEP-0277，数据落在账户自己的 PEP（个人 PubSub）节点。

5.1 blog set：发布博文

正文经 stdin 传入：

echo '这是 Libervia CLI 发布的第一篇博客，用于命令实测。' | libervia-cli blog set -p admin

Item published with ID -gvec

发布成功返回条目 ID（后缀由 CLI 随机生成，每次不同）。

5.2 blog get：读取博文

libervia-cli blog get -p admin -m 2

content: 
这是 Libervia CLI 发布的第一篇博客，用于命令实测。

-m 限制条数。完整回显中每条博文还包含 title、id、author 等元数据行，此处为实测样例节选格式。

六、pubsub 族：发布/订阅

子命令（libervia-cli pubsub --help）：node、set、get、items、delete、affiliations、subscriptions、invite、uri 等；节点管理挂在 pubsub node 下（{info,create,delete,purge,purge-all,affiliations,subscriptions,set,import}）。

6.1 建节点与发布条目

libervia-cli pubsub node create -p admin -c -s srv.lan -n notes

发布条目（payload 必须是 XML 片段，经 stdin 传入）：

echo '<note xmlns="urn:srv.lan:notes">第一篇 PubSub 条目内容</note>' | libervia-cli pubsub set -p admin -c -s srv.lan -n notes note-1

Item published at note-1

参数约定：-s 服务 JID、-n 节点名、末尾位置参数为条目 ID。

6.2 读取条目

libervia-cli pubsub get -p user1 -c -s srv.lan -n notes

回显包含条目 XML（<note>第一篇 PubSub 条目内容</note>）与条目元数据。纯文本 payload 会报 Can't parse the payload XML in input——务必传合法 XML。

💡 Libervia 的博客（XEP-0277）、列表、论坛、活动都是 PubSub 之上的数据约定，pubsub 族因此是平台最底层的通用读写工具。

七、roster 与 identity 族：联系人与身份

7.1 roster：联系人列表

子命令：{get,set,delete,stats,purge,resync}。空名册时的统计回显（实测）：

libervia-cli roster stats -p admin -c

Total number of contacts: 0
Number of different hosts: 0


Contacts with no 'from' subscription: 0
Contacts with no 'to' subscription: 0
Contacts with no subscription at all: 0

Total number of groups: 0
Average contacts per group: 0.0
Average groups' subscriptions per contact: 0.0
Contacts not assigned to any group: 0

7.2 identity：身份元数据

子命令：{set,get}。设置昵称：

libervia-cli identity set -p admin -c -n 'Admin 测试号'

成功静默。读取（目标 JID 为位置参数）：

libervia-cli identity get -p admin -c admin@srv.lan

avatar: None
nicknames: ['Admin 测试号']
description: 

八、param / info / ping：参数与探测

8.1 param：参数读写

子命令：{get,set,delete,save}；get 的 category/name 为位置参数：

usage: libervia-cli param get [-h] [-p PROFILE] [--pwd PASSWORD]
                              [-c | --start-session] [-a ATTRIBUTE]
                              [--security-limit SECURITY_LIMIT]
                              [category] [name]

8.2 info：服务发现与版本

探测服务器支持的特性（XEP-0030）：

libervia-cli info disco -p admin -c srv.lan

Features

http://jabber.org/protocol/commands
http://jabber.org/protocol/disco#info
http://jabber.org/protocol/disco#items
http://jabber.org/protocol/pubsub

查询对端软件版本（XEP-0092）：

libervia-cli info version -p admin srv.lan

Software name: Prosody
Software version: 0.12.3
Operating System: Linux

8.3 ping：连通性探测

libervia-cli ping -p admin -c srv.lan

PONG (0.02831745147705078 s)

⚠️ ping 目标请使用服务器 JID（如 srv.lan）。对未在线的用户 JID 执行 ping 会得到 service-unavailable——XMPP ping 对普通用户实体需要对端客户端在线响应，属正常语义而非故障。

九、account 族：账户注册与维护

子命令：{create,modify,delete}；create 的 JID 与密码均为位置参数：

usage: libervia-cli account create [-h] [--verbose] [-p PROFILE] [-e EMAIL]
                                   [-H HOST] [-P PORT]
                                   jid password

实测向自建 Prosody 注册：

libervia-cli account create testd1@srv.lan q1w2e3r4 -p admin -H srv.lan

本机对端（Debian 12 的 Prosody 0.12.3 默认策略）返回拒绝：

can't create account on 'srv.lan' with jid 'testd1@srv.lan' using In-Band Registration: StanzaError: StanzaError with condition 'not-acceptable': Registration on this server is through invitation only

结论：带内注册（XEP-0077）能否成功取决于服务器端策略——Debian 打包的 Prosody 0.12 默认仅允许邀请制注册。服务器侧放开策略，或改用管理面命令注册（prosodyctl adduser，见安装指南 9.4 节）。-H 指定注册主机（缺省尝试 localhost）。

十、file / bookmarks / encryption 族

10.1 file：文件传输

子命令：{send,request,receive,get,upload,share}：

• file send <文件路径> <对端JID>：Jingle 点对点发送，需对端在线并接受；对端不在线时命令会等待会话建立直至超时，无人值守脚本应避免直接调用；
• file get <URI>：按 xmpp:/aesgcm: 等 URI 下载文件；
• file upload：经 HTTP 上传组件（XEP-0363）转存，适合对端离线场景；
• file share：管理文件共享目录。

10.2 bookmarks：书签管理

子命令：{list,remove,add}——管理 MUC 聊天室与 URL 书签（XEP-0048）。

10.3 encryption：端到端加密会话

子命令：{algorithms,get,start,stop,trust}：

  {algorithms,get,start,stop,trust}
    algorithms          show available encryption algorithms
    get                 get encryption session data
    start               start encrypted session with an entity
    stop                stop encrypted session with an entity
    trust               trust manangement

encryption start <对端JID> 建立加密会话（OMEMO 等），algorithms 列出可用算法。帮助文本中 "trust manangement" 为上游原文拼写瑕疵，照录备查。

十一、shell 交互模式

libervia-cli shell 进入交互式 shell，一次登录、多条命令复用会话参数（省去每条重复 -p/--pwd），支持管道喂入脚本：

printf 'profile list\nquit\n' | libervia-cli shell -p admin

实测回显（欢迎语为上游原文，含旧名与拼写瑕疵，照录）：

Welcome to Libervia CLI shell, the Salut à Toi shell !

This enrironment helps you using several Libervia CLI commands with similar parameters.

To quit, just enter "quit" or press C-d.
Enter "help" or "?" to know what to do

> admin
user1
> good bye!

进入后每行一条命令（可省略顶层命令前缀中的重复参数），quit 或 Ctrl+D 退出。

十二、后端日志与排障

CLI 排障分三层，由浅入深：

第一层：命令本身。加 -v 看详细输出；报错多为 BridgeException（后端返回的 XMPP 层错误，如 PasswordError、service-unavailable），语义直接对应服务器侧行为。

第二层：journalctl（systemd 托管）：

journalctl -u libervia-backend.service -f          # 实时跟踪
journalctl -u libervia-backend.service --since "-10m" --no-pager   # 最近 10 分钟

启动成功的标志日志（实测）：

Backend is ready

第三层：文件日志。libervia-backend fg 前台模式或 log_dir 未重定向时，日志位于 ~/.local/share/libervia/libervia.log，按 .1~.10 轮转：

tail -f ~/.local/share/libervia/libervia.log

调试提级：环境变量优先于配置文件（前缀 SAT_）：

SAT_LOG_LEVEL=debug libervia-cli profile connect -p admin --pwd q1w2e3r4 -c

连接类问题的固定排查顺序：D-Bus 会话总线是否可用（报 D-Bus is not launched / Can't init bridge）→ profile 密码是否正确（PasswordError）→ 服务器证书是否受信（handshake failure / InvalidCertificate）→ 服务器模块是否启用（service-unavailable）。

十三、常见问题（FAQ）

Q1：命令报 D-Bus is not launched / Can't init bridge。 会话总线未就绪。依次执行 systemctl start dbus、systemctl start user@0.service，并 export DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/0/bus（详见安装指南第七节）。

Q2：脚本中 connect/任意命令报 termios.error: (25, 'Inappropriate ioctl for device')。 命令尝试交互式询问 profile 密码但终端不可交互。显式加 --pwd。

Q3：message send 报 unrecognized arguments: <消息内容>。 消息正文不接受位置参数，改由 stdin 传入：echo '内容' | libervia-cli message send ...。

Q4：pubsub set 报 Can't parse the payload XML in input。 条目 payload 必须是合法 XML 片段（经 stdin），纯文本不被接受。

Q5：profile delete -p xxx 报 unrecognized arguments: -p。 delete 的 profile 名是位置参数：libervia-cli profile delete <名> --force。

Q6：account create 报 Registration on this server is through invitation only。 服务器未开放自由注册（Debian Prosody 0.12 默认邀请制）。放开服务器注册策略，或用 prosodyctl adduser 在服务器侧注册。

Q7：file send 无输出卡住。 对端不在线/未响应文件会话，Jingle 协商在等待。确认对端在线，或改用 file upload（HTTP 上传组件）。

Q8：ping 用户 JID 报 service-unavailable。 对端未在线。ping 服务器 JID（如 srv.lan）验证链路。

十四、参考链接

• 官方文档站 CLI 手册：https://libervia.org/documentation
• 官方源码仓库：https://repos.goffi.org/libervia
• 本机 man 手册：man libervia-cli（libervia-cli 包自带，内含 jp 历史名说明）
• 本站相关篇目：
  • 《Debian 12 安装 Libervia 0.9.0 后端与 CLI 指南》
  • 《Libervia 0.9.0 配置参数详解》
  • 《Libervia 0.9.0 介绍与选型指南》