コマンドラインツール (CLI)

将棋道場の公式 CLI です。投稿・棋譜のアップロードなど、ブラウザでできることをターミナルから自動化できます。macOS・Windows・Linux で同じコマンドが動きます。

1 必要なもの: Node.js 20 以降

CLI 本体は依存ライブラリを持ちません。必要なのは Node.js だけで、その入れ方だけが OS ごとに違います。

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 インストール

コマンド自体は3つとも同じですが、Linux ではホーム配下に入れてください。システム全体へのインストールには root が必要で、CLI のために sudo を使う理由はありません。

macOS

次を実行します:

npm install -g @shogidojo/cli

Windows

PowerShell でも同じコマンドです:

npm install -g @shogidojo/cli

Linux

ホーム配下に入れるので sudo は不要です。2行目はシェルの設定ファイル（~/.bashrc や ~/.zshrc）にも書いておくと、新しい端末でも見つかります:

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

入ったか確認します:

shogidojo --version
shogidojo --help

3 サインイン

アカウントごとの API キーで認証します。キーはアカウントと同じ権限を持つので、扱いには注意してください。自動化には、そのための名前付きキーを別に発行できます（読み取り専用にもできます）。

ふだんはこちら。ブラウザが開き、サインインするとキーが自動で戻ってきます。キーがコマンド行に現れないので、シェルの履歴に残りません:

shogidojo login --browser

SSH でつないだ先では --browser だけでは完了しません。キーはコマンドを実行した側の 127.0.0.1 に返るので、手元のブラウザで開いても届く先がありません。ポートを自分で決めて転送してください:

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

あるいはキーを貼り付けます。標準入力から読むので、シェルの履歴には残りません:

shogidojo login --stdin

CI など、ブラウザが無い場所では環境変数で渡します。ファイルには何も書かれません:

SHOGIDOJO_TOKEN=rustify… shogidojo whoami

CI や Windmill などの自動化には、手元のキーとは別のキーを名前を付けて発行します。手元のキーはそのまま使えます。キーはこのとき一度だけ表示され（標準出力にはキーだけが出ます）、この端末には保存されません。--read-only を付けると、読み取りはできても投稿や変更はできないキーになります:

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

持っているキーの一覧（名前・範囲・作成日・最終使用日・期限）と、1本だけの失効。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 "感想戦で挙がった手" --deck 竜王戦 --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:<対局ID>] は対局カードになります。それ以外は普通の Markdown です:

## ▲７六歩 △３四歩 の局面

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

[game:user-1-…]

取り込んだ対局は PRIVATE で始まります。そのまま [game:] を貼ると、カードは自分にだけ見えて、他の読者には表示されません。取り込むときに --public で公開するか、post create の --game に任せてください。--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

同じ局面図を外部の記事（note など）に載せるときは 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 は投稿の URL（/posts/<番号>）を表示します。対局のページは /review/<対局ID> です（/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 うまくいかないとき

よくある3つです。

「Unsupported engine」や構文エラーが出る場合、Node が古い可能性があります。20 以降が必要です:

node --version

グローバルインストールで EACCES が出る場合、sudo ではなくインストール先をホーム配下に変えるのが安全です:

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

login --browser は URL を表示しますが、その中の戻り先は URL を表示したマシンの 127.0.0.1 です。別のマシンのブラウザで開くとそちらでサインインが終わり、キーはどこにも届きません。SSH 越しなら、転送したポートを --port で渡すか、--stdin で貼り付けてください（どちらも上にあります）:

shogidojo login --stdin

コマンドライン ツール (CLI)