Strumento da riga di comando (CLI)

Con Homebrew:

brew install node
node --version

Con winget (va bene anche l'installer ufficiale):

winget install OpenJS.NodeJS.LTS
node --version

Su Debian / Ubuntu — sulle altre distribuzioni usa il tuo gestore di pacchetti:

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

Esegui:

npm install -g @shogidojo/cli

Lo stesso comando, in PowerShell:

npm install -g @shogidojo/cli

Nella tua home, così non serve sudo. Metti la seconda riga anche nel profilo della shell (~/.bashrc o ~/.zshrc), perché un nuovo terminale la trovi:

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

Verifica che ci sia:

shogidojo --version
shogidojo --help

Il modo abituale. Si apre un browser, accedi e la chiave torna da sola — non compare mai su una riga di comando, quindi non finisce nella cronologia della shell:

shogidojo login --browser

Su una macchina raggiunta via SSH, --browser da solo non può concludere: la chiave torna al 127.0.0.1 della macchina che ha eseguito il comando, quindi un browser sul tuo computer non ha a chi consegnarla. Inoltra una porta scelta da te:

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

Oppure incolla una chiave. Viene letta dallo standard input, quindi non finisce nella cronologia della shell:

shogidojo login --stdin

Dove non c'è un browser, come in CI, passala dall'ambiente. Sul disco non viene scritto nulla:

SHOGIDOJO_TOKEN=rustify… shogidojo whoami

Per la CI, Windmill o qualsiasi altra automazione, emetti una chiave separata con un nome; quella sulla tua macchina continua a funzionare. La chiave viene mostrata una sola volta (su stdout c'è solo la chiave) e non viene salvata su questa macchina. Con --read-only può leggere ma non pubblicare né modificare nulla:

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

Elencare le chiavi che possiedi (nome, ambito, creazione, ultimo uso, scadenza) e revocarne una. `app` è la chiave dell'account, quella emessa dalla pagina delle impostazioni:

shogidojo token list
shogidojo token revoke 3

La chiave è salvata in ~/.config/shogidojo/config.json con permessi 0600 (%APPDATA%\shogidojo su Windows). Per vederla o rimuoverla:

shogidojo whoami
shogidojo logout

Pubblicare un articolo:

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

Caricare una partita:

shogidojo kif upload game.kif --dir /2026

Vedere quali motori puoi usare, analizzare una partita e seguirne l'avanzamento:

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

Creare un quiz da una partita. --ply 44 chiede la mossa 44, mostrando la posizione dopo la mossa 43. --answer può essere una mossa non giocata nella partita (USI, o notazione come △５五歩); in quel caso la carta conserva anche la mossa giocata:

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

Tutto il resto — --query per leggere, omesso per scrivere:

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

Tutto ciò che questo server accetta. L'elenco è esattamente quello che prende call:

shogidojo procedures --grep quiz

[sfen:<SFEN>] disegna una posizione e [game:<gameId>] incorpora la scheda di una partita. Tutto il resto è Markdown normale:

## After ▲７六歩 △３四歩

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

[game:user-1-…]

Una partita importata parte come PRIVATE. La sua scheda [game:] è visibile a te e vuota per ogni altro lettore. Pubblicala mentre la importi con --public, oppure lascia fare a post create --game, che aggiunge il token [game:] e si ferma se una partita PRIVATE sta per finire in un post PUBLIC (aggiungi --publish-game per pubblicarla prima):

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

Per inserire le posizioni chiave in un articolo, prendi lo SFEN dopo la mossa N e mettilo in [sfen:] (0 è la posizione iniziale; senza --ply, quella finale):

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

Per lo stesso diagramma in un articolo altrove, esportalo come SVG. --sfen non richiede né account né rete; --game prende da una partita la posizione, i giocatori e la casella dell'ultima mossa. Per un PNG, converti l'SVG (rsvg-convert, ImageMagick, un browser):

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 è solo un'etichetta e un filtro del feed; il corpo viene mostrato allo stesso modo. ARTICLE è un articolo, KIFU presenta una partita, BOOK presenta un libro.

post create stampa la URL del post, /posts/<id>. La pagina di una partita è /review/<gameId> (/game/<id> è la scacchiera dal vivo), ed è quella che stampano 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)

Limiti: titolo di 200 caratteri, corpo di 50.000, fino a 20 tag da 40 caratteri ciascuno. La CLI si ferma prima di inviare qualsiasi cosa oltre questi limiti.

Vedere cosa prende una procedura:

shogidojo procedures --describe quiz.import

Partite:

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:

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

Quiz (playedUsi / playedNotation sono la mossa giocata nella partita, gameId la partita di origine; entrambi facoltativi):

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)

Un messaggio "Unsupported engine" o un errore di sintassi di solito vuol dire che Node è troppo vecchio. Serve la 20 o successiva:

node --version

Se l'installazione globale fallisce con EACCES, sposta il prefisso di installazione nella tua home invece di ricorrere a sudo:

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

login --browser stampa una URL, ma l'indirizzo di ritorno che contiene punta al loopback della macchina che l'ha stampata. Aprire quella URL su un'altra macchina fa l'accesso lì e la chiave non arriva da nessuna parte. Via SSH, inoltra una porta e passala con --port, o incolla la chiave con --stdin: entrambi sono qui sopra:

shogidojo login --stdin