命令行工具 (CLI)

将棋道场官方 CLI。发布文章、上传棋谱，把浏览器里能做的事都放到终端里自动化。macOS、Windows、Linux 上命令完全相同。

1 前提：Node.js 20 或更新版本

CLI 本身没有任何依赖，只需要 Node.js —— 各系统的差别仅在于如何安装它。

macOS

使用 Homebrew：

brew install node
node --version

Windows

使用 winget（官方安装包同样可以）：

winget install OpenJS.NodeJS.LTS
node --version

Linux

Debian / Ubuntu —— 其他发行版请使用各自的包管理器：

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node --version

2 安装

三个系统的命令相同，但在 Linux 上请安装到主目录。装到整个系统需要 root，而一个命令行工具不值得动用 sudo。

macOS

执行：

npm install -g @shogidojo/cli

Windows

在 PowerShell 里也是同一条命令：

npm install -g @shogidojo/cli

Linux

装到主目录，因此不需要 sudo。第二行也写进 shell 配置（~/.bashrc 或 ~/.zshrc），新开的终端才找得到：

npm install -g --prefix ~/.local @shogidojo/cli
export PATH="$HOME/.local/bin:$PATH"

确认安装成功：

shogidojo --version
shogidojo --help

3 登录

CLI 使用个人 API 密钥认证。密钥拥有与账号相同的权限，请像对待密码一样保管。自动化任务可以拥有自己的命名密钥；如果只需读取，还可以设为只读。

常用方式。浏览器会打开，登录后密钥自动返回 —— 它不会出现在命令行上，因此不会留在 shell 历史里：

shogidojo login --browser

在通过 SSH 连上的机器上，只用 --browser 无法完成：密钥会回到执行命令那台机器的 127.0.0.1，所以你本地的浏览器无处交付。请自行选一个端口并转发：

ssh -L 47311:127.0.0.1:47311 you@host
shogidojo login --browser --port 47311

也可以粘贴密钥。它从标准输入读取，因此不会留在 shell 历史里：

shogidojo login --stdin

没有浏览器的地方（例如 CI）改用环境变量传入，不会写入磁盘：

SHOGIDOJO_TOKEN=rustify… shogidojo whoami

CI、Windmill 或其他自动化任务请另行签发一个命名密钥；你本机上的密钥照常可用。新密钥只显示一次（标准输出中只有密钥本身），也不会保存在这台机器上。加上 --read-only 后，它只能读取，不能发布或修改任何内容：

shogidojo token create --name windmill --read-only --days 90

列出你持有的密钥（名称、范围、创建时间、最后使用时间、到期时间），并吊销其中一个。`app` 是账号密钥，即设置页面签发的那个：

shogidojo token list
shogidojo token revoke 3

密钥保存在 ~/.config/shogidojo/config.json，权限 0600（Windows 为 %APPDATA%\shogidojo）。查看与删除：

shogidojo whoami
shogidojo logout

4 使用

命名命令只是快捷方式。应用能做的一切都可以通过 call 调用。

发布文章：

shogidojo post create --title "..." --body-file note.md --tag 居飛車

上传棋谱：

shogidojo kif upload game.kif --dir /2026

查看可用的引擎、分析一局棋，并查看进度：

shogidojo engines
shogidojo analyze game.kif --seconds 5
shogidojo jobs

从对局生成测验。--ply 44 考的是第 44 手，显示第 43 手之后的局面。--answer 可以是实战中没有走的着法（USI，或 △５五歩这样的记法）；此时卡片也会保留实战的着法：

shogidojo quiz create --game user-1-… --ply 44 --answer △５五歩 --note "Suggested in the post-mortem" --deck Ryuo --public

其他所有操作 —— 读取加 --query，写入则不加：

shogidojo call post.list --query --input '{"page":1}'
shogidojo call quiz.createDeck --input '{"name":"..."}'

这台服务器能被调用的全部过程。这份清单就是 call 的参数：

shogidojo procedures --grep quiz

5 撰写文章

post create 的正文是 Markdown，另加两种用于嵌入局面图和对局的写法。

[sfen:<SFEN>] 显示局面图，[game:<gameId>] 嵌入对局卡片。其余都是普通 Markdown：

## After ▲７六歩 △３四歩

[sfen:lnsgkgsnl/1r5b1/pppppp1pp/6p2/9/2P6/PP1PPPPPP/1B5R1/LNSGKGSNL b - 3]

[game:user-1-…]

导入的对局初始为 PRIVATE。它的 [game:] 卡片只有你能看到，其他读者看到的是空白。可以在导入时用 --public 公开，或交给 post create --game：它会在正文末尾追加 [game:]，如果要把 PRIVATE 对局放进 PUBLIC 文章则会中止（加 --publish-game 会先公开再发布）：

shogidojo kif import game.kif --public
shogidojo post create --type KIFU --title "..." --body-file note.md --game user-1-… --publish-game

要在文章中放关键局面，取出第 N 手之后的 SFEN 填入 [sfen:]（0 为初始局面；省略 --ply 则为最终局面）：

shogidojo kif position user-1-… --ply 60

要在其他网站的文章中使用同样的局面图，可以导出为 SVG。--sfen 不需要账号，也不需要联网；--game 从对局中取局面、对局者和最后一手的落点。需要 PNG 时请转换 SVG（rsvg-convert、ImageMagick、浏览器等）：

shogidojo diagram --sfen "lnsgkgsnl/1r5b1/ppppppppp/9/9/9/PPPPPPPPP/1B5R1/LNSGKGSNL b - 1" -o start.svg
shogidojo diagram --game user-1-… --ply 60 -o move60.svg
rsvg-convert -o move60.png move60.svg

--type 只是标签和信息流筛选条件，正文显示不变。ARTICLE 是文章，KIFU 介绍棋谱，BOOK 介绍书籍。

post create 会打印文章的网址 /posts/<id>。对局页面是 /review/<gameId>（/game/<id> 是实时棋盘），kif import / upload 打印的就是它：

Posted #12  https://shogidojo.online/posts/12
Imported game.kif as user-1-…
  https://shogidojo.online/review/user-1-…  (private — only you can open it)

限制：标题 200 字符，正文 50,000 字符，最多 20 个标签，每个 40 字符。超出时 CLI 会在发送前中止。

6 call 可用的过程

call 接受什么，可以用 --describe 查看。服务器会把它用来校验输入的 Zod 模式以 JSON Schema 返回，因此不会与实际不符。只有声明了返回值的过程才会显示返回结构；常用的列在下面（读取时加 --query）。

查看某个过程接受的输入：

shogidojo procedures --describe quiz.import

棋谱：

game.importKifFromText        {"kifText":"…","dir":"/2026"}
  → {"game_id":"user-1-…"}
game.setGameVisibility        {"gameId":"user-1-…","visibility":"PUBLIC"}
  → {"success":true}
game.getFullGameById (read)   {"gameId":"user-1-…"}
  → {"game_id":…, "visibility":…, "moves":[{"id":1, "moveNumber":0, "sfen":"…",
       "children":[{"childId":2, "usi":"7g7f", "notation":"▲７六歩"}]}, …]}
game.applyMove (read)         {"sfen":"…","move":"△５五歩","lastUsi":"7g7f"}
  → {"sfen":"…","usi":"5d5e","notation":"△５五歩","nextSfen":"…"}

文章：

post.create   {"type":"KIFU","title":"…","body":"…","tags":["居飛車"],"visibility":"PUBLIC"}
  → {"id":12, …}

测验（playedUsi / playedNotation 为实战着法，gameId 为出处对局；均可省略）：

quiz.import   {"title":"…","visibility":"PUBLIC","gameId":"user-1-…",
               "items":[{"sfen":"…","answerUsi":"5d5e","answerNotation":"△５五歩",
                         "nextSfen":"…","note":"…",
                         "playedUsi":"8a7c","playedNotation":"△７三桂"}]}
  → {"deckId":5,"listIds":[9]}
  (or {"deck":{"title":"…"},"lists":[ …the same list… ]} for a named deck)

7 遇到问题时

大多数情况是这三种。

出现 “Unsupported engine” 或语法错误，通常是 Node 太旧。需要 20 或更新版本：

node --version

全局安装报 EACCES 时，把安装目录改到主目录下，比用 sudo 更安全：

npm config set prefix ~/.local
export PATH="$HOME/.local/bin:$PATH"

login --browser 会打印一个网址，但其中的回调地址指向打印它那台机器的本机回环。在另一台机器上打开，登录发生在那一边，密钥不会到任何地方。走 SSH 时请转发端口并用 --port 传入，或用 --stdin 粘贴密钥——两者都在上面：

shogidojo login --stdin