명령줄 도구 (CLI)

Homebrew를 쓰는 경우:

brew install node
node --version

winget을 쓰는 경우(공식 설치 프로그램도 동일합니다):

winget install OpenJS.NodeJS.LTS
node --version

Debian / Ubuntu의 경우 — 다른 배포판은 각자의 패키지 관리자를 사용하세요:

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

실행:

npm install -g @shogidojo/cli

PowerShell에서도 같은 명령입니다:

npm install -g @shogidojo/cli

홈 디렉터리에 설치하므로 sudo가 필요 없습니다. 두 번째 줄은 셸 설정(~/.bashrc 또는 ~/.zshrc)에도 넣어 두면 새 터미널에서도 찾습니다:

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

설치되었는지 확인:

shogidojo --version
shogidojo --help

보통은 이 방법입니다. 브라우저가 열리고 로그인하면 키가 알아서 돌아옵니다 — 명령줄에 나타나지 않으므로 셸 기록에도 남지 않습니다:

shogidojo login --browser

SSH로 접속한 기기에서는 --browser만으로는 끝나지 않습니다. 키는 명령을 실행한 쪽의 127.0.0.1로 돌아오므로, 내 데스크톱의 브라우저는 건네줄 상대가 없습니다. 직접 정한 포트를 전달(forward)하세요:

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 같은 자동화에는 이름을 붙인 별도의 키를 발급합니다. 내 기기의 키는 그대로 쓸 수 있습니다. 키는 한 번만 표시되며(stdout에는 키만 출력됩니다) 이 기기에는 저장되지 않습니다. --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

글 게시:

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

[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은 본문 끝에 [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는 글의 URL(/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가 보내기 전에 멈춥니다.

프로시저가 받는 입력 보기:

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)

"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