命令行

应用随附命令行 zikaron：一个操作一个子命令，每条命令在标准输出给一个 JSON 值，结论看退出码。它有三种用法：经桌面 App 操作、经凭据操作，或者纯命令行。

接进终端

在「设置 › 命令行与 AI 控制」的「终端」里打开「启用 zikaron 命令」，之后在终端里直接敲 zikaron 就能用。用 .pkg 或 .deb 安装的，装完就已经可以；用 AppImage 的，要用命令行请装 .deb。Windows 上的 zikaron.exe 要在终端里运行。

同一页的「自动控制等级」决定命令行怎样写桌面封存的数据：「经桌面 App 操作」（默认开）是用法一，「经凭据操作」（默认关）是用法二。「经凭据操作」开着时，「经桌面 App 操作」变灰，任何时候只有一条路开着；两个都关着时，封存的数据只由桌面自己写。纯命令行写它自己的账本目录，与这两个开关无关。

同一页「终端」一组里还有「接入 AI 应用」：按「复制配置」，把配置贴进 AI 代理的 MCP 设置，AI 代理不经终端也能调用命令行（zikaron mcp）。每次写入照这一页的开关走用法一或用法二，见经 MCP 接入。

运行 zikaron contract，列出全部子命令、各自的参数和退出码。每条命令的写法见开发者指南 · 命令行。

用法一：经桌面 App 操作

桌面开着并已解锁时，命令带上数据目录 --home "<数据目录>"，就交给正在运行的 ZIKARON Desk 去做。桌面用你的身份签名，写进它的账本，走的是与你亲手点按同一条路：同样的检查，同样的提示，窗口里随即更新。私钥和口令一直留在桌面里，命令行只递请求。

• 数据目录在哪：「设置 › 本机数据」的「详细信息」里，「数据目录」一行就是当前身份这一角色的数据目录路径。
• 只读的事：核验别人的材料这类只读的操作，命令行直接就能做。
• 桌面上做的事：设口令、管理密钥、整机备份、打开「经凭据操作」、「加价重发」，以及要输口令的操作，在桌面上做。把账本移交给另一把钥也在桌面上亲手做：succeed 带 --home 一律答 E_ON_DESKTOP。
• 通道何时开着：本机通道只对这台电脑上的你开放，只在「经桌面 App 操作」开着、桌面解锁并开着这个数据目录时开着；锁定、关闭数据目录或退出，通道即关，命令行收到退出码 4。「经凭据操作」开着时，带 --home 的命令答 E_DESKTOP，detail 为 ALONE：去掉 --home，照用法二写。

用法二：经凭据操作

你在桌面上授权一份限期的凭据，命令行凭它直接写桌面封存的账本、发它的待上链队列，桌面关着、锁着都行。

1. 打开开关。在「设置 › 命令行与 AI 控制」的「自动控制等级」里打开「经凭据操作」，在弹出的卡上输口令，填有效期：天、小时、分钟三格（至多 365、23、59，合计一分钟到一年），或打开「不过期」；按「打开」。开着时，这一行下面写着凭据何时到期。
2. 找到账本文件夹。「设置 › 本机数据」的「详细信息」里「数据目录」一行是数据目录的路径；命令里的 --ledger 给它里面的 ledger 文件夹。
3. 写与读。写条目的命令带 --ledger "<数据目录里的 ledger 文件夹>"，用桌面密钥库里这个身份这一角色的钥签名，不带 --key、--key-file 或 --home；写进去的条目照桌面的样子排进待上链。核验、导出记录包等读的命令给同一个文件夹，导出时照桌面带上所选存证的原件。
4. 上链。zikaron anchor --ledger "<数据目录里的 ledger 文件夹>" 发这个数据目录的待上链队列：链、登记合约和节点取这个数据目录的设置，代理取「设置 › 网络」的「代理」。

收回。关掉「经凭据操作」，凭据即删。到期即删，桌面提示一句，命令行答 E_CREDENTIAL_EXPIRED。换主身份或整机恢复之后，凭据作废，开关自动回到关，提示「主钥已换，「经凭据操作」已关。」。改口令照用；凭据出错不计口令错次。

与桌面轮流写。桌面和命令行每写一笔各自拿这个数据目录的写者锁，写完即放。命令行正赶上桌面在写，答 E_HOME_HELD，稍后再试；桌面正赶上命令行在写，这一笔不做，提示「命令行正在写入。」，提示上的「去设置」直达这一页。桌面开着并已解锁时每秒看一眼盘，命令行写进的条目随即出现；开着「自动上链」时，照桌面自己记一条之后那样弹出发送确认。

凭据文件。它在机器目录里，只有你这个系统账户能读写，里面封着打开本机数据的主钥。拿到它的人或程序，能像命令行一样以这台电脑上的各个身份写账本、发上链交易，直到它到期或你关掉开关。有效期按需要设，用完就关。

命令行上链的两种模式

用法一与用法二上链时，都按「设置 › 命令行与 AI 控制」「上链操作」里的「命令行上链」走：

自动发送

默认。照「全部上链」的做法，把队里能发的条目装进一笔交易发出，费用从这个身份的地址里付。进入区块即交回区块号和交易号；等到时限还没入块，答交易还没入块（退出码 4），这一批留在途，桌面或下一次上链接着问收据。经桌面等 30 秒，经凭据缺省等 90 秒。这一批里有存证已在链上时一笔不发，答 E_ON_CHAIN；那几条移出队列之后，再发一次即发其余的。

仅加入队列

条目留在队里，命令行答「已在队列，待用户在桌面上发」（E_QUEUED，退出码 3）。经桌面时，桌面弹出提示「命令行提交了 N 条记录，已加入队列」并提醒你一次。你在桌面上核对后按「确认上链」。

打开「经凭据操作」的卡上写明：「命令行上链」为「自动发送」时，命令行可花这个身份的 gas。

用法三：纯命令行

命令行自己就能从头做起，用不着桌面，也用不着图形界面：

1. 生成密钥。在你自己的终端里运行 zikaron keygen，它输出一个新地址和它的私钥。把私钥那一串存进一个文件，设成只有你能读（macOS 与 Linux 上用 chmod 600），之后的命令用 --key-file 指向它。
2. 充值 gas。往这个地址转一点 ETH。
3. 建账本。zikaron init --ledger "<账本目录>" --key-file "<私钥文件>" --statement "<说明>"。之后存证、授权、撤销、注记等写入，都带这两项写进这个账本目录。
4. 上链。anchor 用 --key-file 给私钥文件，--endpoint 指定节点，--form registry 指明经登记合约，--registry 指定登记合约（以太坊主网上是 0x36Ea8A857a5FE813429d4D9947000C644A88809A），--hash 给要上链的条目编号，可以给好几个，一笔交易锚多条。签名之前它先问登记合约这把钥是否已锚过这几个编号：有一条已在链上即答 E_ON_CHAIN，names 列出已有的，一笔不发。同一条命令重跑时，先查已经签过的交易，同一次上链只付一次费。
5. 核验与出示。用 scan 和 audit 对着链检查账本；用 kit-export 导出记录包（缺省写成 --out 给的一个文件，名字自己取，桌面导出的叫 .zkit；--as folder 为文件夹）；用 kit-verify 逐条核验一份记录包，带上 scan 的读数才判上没上链；用 check-grant 核验授权；kit-export 加 --to-key <公钥>（或 --to <地址> 并给 --endpoint）即加密给一个接收方；kit-verify 加 --originals-to <文件夹> 即把原件取到那个文件夹。

写出的账本与桌面写的是同一种格式，任何人用桌面应用或命令行都能核验。日后要把这本账接进桌面，先用「导入密钥」导入这把私钥，再在「设置 › 本机数据」的「高级选项」里用「收编已有账本目录」。收编之后，这本账由桌面接着写：命令行再写原目录即答 E_ADOPTED，原目录保持原样；要从命令行接着写，用用法二。要让一本账在两处之间来回写，见交接账本。

交接账本

一本账可以在两处之间来回交，比如远程主机上命令行的账本目录与本机桌面的数据目录；任何时候只有一处在写。两端用同一组命令：

• zikaron hand-over --ledger "<这一处>" --out "<交接件>"：把整本账写成一份交接件（.zkhand），这一处随即停写，再写即答 E_HANDED_OFF。交接件路上丢了，再跑一次写出的是同一份。
• zikaron take-over --ledger "<那一处>" --handoff "<交接件>"：只收顺接的交接件，把这一处没有的条目按序号写进来，这一处随即复写。收不下时答 E_HANDOFF，token 写明原因，什么也不写。

两处写的是同一本账、用同一把钥：命令行那一侧用 --key-file 给的私钥，桌面那一侧是用「导入密钥」导入同一把私钥的身份。桌面那一侧给数据目录里的 ledger 文件夹，要开着「经凭据操作」，桌面锁着也行。桌面那一侧交出之后，桌面上写这本账即提示「这本账已交接到另一处。」，等那一处交回、用命令行收下交接件再写。上链记录不随交接件走：桌面下一趟账本检查从链上现读，只把链上还没有的排进待上链，另一处上过的不会再付一次 gas。

明文的文件

纯命令行时，下面几样以明文存在磁盘上：

要紧的是私钥文件。能用这个系统账户读文件的人或程序，都能读到它，所以这样保管：

• 只放小钱、只管专用的账。这把钥单独用，地址里只放够付 gas 的 ETH，与你主要的身份分开。
• 守住系统账户。开启系统的全盘加密；远程登录只许用密钥。
• 私钥只经文件交给命令行。用 --key-file 给，命令行只认只有你能读的私钥文件；文件放在同步盘与自动备份的文件夹之外，另抄一份放在离线的安全处。
• 能走桌面就走桌面。用法一与用法二里，私钥在桌面的密钥库里，用口令加密。纯命令行留给真正需要无界面、只用一把专用钥的场合。

三种用法怎么选

命令行的答复