Công cụ dòng lệnh (CLI)

Dùng Homebrew:

brew install node
node --version

Dùng winget (trình cài đặt chính thức cũng tương đương):

winget install OpenJS.NodeJS.LTS
node --version

Trên Debian / Ubuntu — với bản phân phối khác hãy dùng trình quản lý gói của bạn:

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

Chạy:

npm install -g @shogidojo/cli

Cũng câu lệnh đó, trong PowerShell:

npm install -g @shogidojo/cli

Vào thư mục home, nên không cần sudo. Hãy đặt dòng thứ hai vào cả tệp cấu hình shell (~/.bashrc hoặc ~/.zshrc) để một cửa sổ terminal mới vẫn tìm thấy:

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

Kiểm tra đã cài được:

shogidojo --version
shogidojo --help

Cách thường dùng. Trình duyệt mở ra, bạn đăng nhập, và khoá tự quay về — nó không bao giờ xuất hiện trên dòng lệnh, nên cũng không vào lịch sử shell:

shogidojo login --browser

Trên máy bạn vào bằng SSH, chỉ --browser thì không xong: khoá quay về 127.0.0.1 của chính máy đã chạy lệnh, nên trình duyệt trên máy bạn không có ai để trao. Hãy chuyển tiếp một cổng do bạn chọn:

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

Hoặc dán một khoá. Nó được đọc từ standard input, nên không vào lịch sử shell:

shogidojo login --stdin

Ở nơi không có trình duyệt, chẳng hạn CI, hãy truyền qua biến môi trường. Không có gì được ghi xuống đĩa:

SHOGIDOJO_TOKEN=rustify… shogidojo whoami

Với CI, Windmill hay bất kỳ tác vụ tự động nào khác, hãy cấp một khoá riêng có tên; khoá trên máy bạn vẫn dùng được. Khoá chỉ hiện một lần (stdout chỉ chứa khoá) và không được lưu trên máy này. Với --read-only, khoá đọc được nhưng không đăng bài hay thay đổi được gì:

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

Liệt kê các khoá bạn có (tên, phạm vi, ngày tạo, lần dùng cuối, hạn dùng) và thu hồi một khoá. `app` là khoá tài khoản, khoá do trang cài đặt cấp:

shogidojo token list
shogidojo token revoke 3

Khoá được lưu ở ~/.config/shogidojo/config.json với quyền 0600 (Windows là %APPDATA%\shogidojo). Để xem và xoá:

shogidojo whoami
shogidojo logout

Đăng một bài viết:

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

Tải lên một ván cờ:

shogidojo kif upload game.kif --dir /2026

Xem những engine bạn dùng được, phân tích một ván và theo dõi tiến độ:

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

Tạo câu đố từ một ván cờ. --ply 44 hỏi nước thứ 44, hiển thị thế cờ sau nước thứ 43. --answer có thể là nước không được đi trong ván (USI, hoặc ký hiệu như △５五歩); khi đó thẻ vẫn giữ cả nước đã đi trong ván:

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

Mọi thứ còn lại — --query để đọc, bỏ đi để ghi:

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

Mọi thứ có thể hỏi máy chủ này. Danh sách đó chính là đối số của call:

shogidojo procedures --grep quiz

[sfen:<SFEN>] vẽ một thế cờ và [game:<gameId>] nhúng một thẻ ván cờ. Phần còn lại là Markdown thông thường:

## After ▲７六歩 △３四歩

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

[game:user-1-…]

Ván cờ được nhập bắt đầu ở trạng thái PRIVATE. Thẻ [game:] của nó hiện với bạn nhưng trống với mọi người đọc khác. Hãy công khai nó ngay khi nhập bằng --public, hoặc để post create --game lo: lệnh này thêm token [game:] và dừng lại nếu một ván PRIVATE sắp vào một bài PUBLIC (thêm --publish-game để công khai trước):

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

Để đặt các thế cờ then chốt vào bài viết, lấy SFEN sau nước thứ N và đặt vào [sfen:] (0 là thế ban đầu; không có --ply thì là thế cuối):

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

Để dùng cùng sơ đồ trong một bài viết ở nơi khác, hãy xuất nó ra SVG. --sfen không cần tài khoản cũng không cần mạng; --game lấy thế cờ, người chơi và ô của nước cuối từ một ván. Muốn PNG thì chuyển đổi SVG (rsvg-convert, ImageMagick, trình duyệt):

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 chỉ là nhãn và bộ lọc bảng tin; nội dung hiển thị như nhau. ARTICLE là bài viết, KIFU giới thiệu một ván cờ, BOOK giới thiệu một cuốn sách.

post create in ra URL của bài, /posts/<id>. Trang của một ván là /review/<gameId> (/game/<id> là bàn cờ trực tiếp), và kif import / upload in ra trang này:

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)

Giới hạn: tiêu đề 200 ký tự, nội dung 50.000, tối đa 20 thẻ, mỗi thẻ 40 ký tự. CLI dừng lại trước khi gửi bất cứ thứ gì vượt quá.

Xem một thủ tục nhận gì:

shogidojo procedures --describe quiz.import

Ván cờ:

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":"…"}

Bài viết:

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

Câu đố (playedUsi / playedNotation là nước đã đi trong ván, gameId là ván gốc; cả hai đều tuỳ chọn):

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)

Thông báo "Unsupported engine" hoặc lỗi cú pháp thường có nghĩa Node quá cũ. Cần bản 20 trở lên:

node --version

Nếu cài đặt toàn cục thất bại với EACCES, hãy chuyển thư mục cài đặt vào thư mục nhà thay vì dùng sudo:

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

login --browser in ra một URL, nhưng địa chỉ quay về trong đó trỏ tới loopback của chính máy đã in nó. Mở URL ấy trên máy khác thì bạn đăng nhập ở đó và khoá không đến đâu cả. Qua SSH, hãy chuyển tiếp một cổng rồi truyền bằng --port, hoặc dán khoá bằng --stdin — cả hai đều ở trên:

shogidojo login --stdin