Ferramenta de linha de comandos (CLI)

Com Homebrew:

brew install node
node --version

Com winget (o instalador oficial serve igualmente):

winget install OpenJS.NodeJS.LTS
node --version

Em Debian / Ubuntu — noutras distribuições use o seu gestor de pacotes:

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

Execute:

npm install -g @shogidojo/cli

O mesmo comando, no PowerShell:

npm install -g @shogidojo/cli

Na sua pasta pessoal, então não é preciso sudo. Coloque a segunda linha também no perfil do shell (~/.bashrc ou ~/.zshrc), para um terminal novo continuar a encontrá-la:

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

Confirme que ficou instalada:

shogidojo --version
shogidojo --help

A forma habitual. Abre-se um navegador, inicia sessão e a chave regressa sozinha — nunca aparece numa linha de comandos, por isso nunca chega ao histórico da shell:

shogidojo login --browser

Numa máquina alcançada por SSH, --browser sozinho não conclui: a chave volta para o 127.0.0.1 da máquina que executou o comando, então um navegador no seu computador não tem a quem entregá-la. Encaminhe uma porta escolhida por você:

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

Ou cole uma chave. Ela é lida da entrada padrão, portanto não vai para o histórico do shell:

shogidojo login --stdin

Onde não há navegador, como em CI, passe-a pelo ambiente. Nada é escrito no disco:

SHOGIDOJO_TOKEN=rustify… shogidojo whoami

Para CI, Windmill ou qualquer outra automação, emita uma chave com nome à parte; a da sua máquina continua a funcionar. A chave é mostrada uma única vez (o stdout traz apenas a chave) e não fica guardada nesta máquina. Com --read-only pode ler, mas não publicar nem alterar nada:

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

Listar as chaves que tem (nome, âmbito, criação, última utilização, expiração) e revogar uma delas. `app` é a chave da conta, a que a página de definições emite:

shogidojo token list
shogidojo token revoke 3

A chave fica em ~/.config/shogidojo/config.json com modo 0600 (%APPDATA%\shogidojo no Windows). Para ver ou remover:

shogidojo whoami
shogidojo logout

Publicar um artigo:

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

Enviar uma partida:

shogidojo kif upload game.kif --dir /2026

Ver quais motores estão disponíveis, analisar uma partida e acompanhar o progresso:

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

Criar um quiz a partir de uma partida. --ply 44 pergunta pelo lance 44, mostrando a posição depois do lance 43. --answer pode ser um lance que não foi jogado na partida (USI, ou notação como △５五歩); nesse caso o cartão guarda também o lance jogado:

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

Tudo o resto — --query para ler, omitido para escrever:

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

Tudo o que este servidor aceita. A lista é exatamente o que call recebe:

shogidojo procedures --grep quiz

[sfen:<SFEN>] desenha uma posição e [game:<gameId>] incorpora um cartão de partida. O resto é Markdown normal:

## After ▲７六歩 △３四歩

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

[game:user-1-…]

Uma partida importada começa como PRIVATE. O seu cartão [game:] aparece para si e fica em branco para qualquer outro leitor. Publique-a ao importá-la com --public, ou deixe isso para post create --game, que acrescenta o token [game:] e para se uma partida PRIVATE estiver prestes a entrar numa publicação PUBLIC (acrescente --publish-game para a publicar primeiro):

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

Para colocar posições-chave num artigo, obtenha o SFEN após o lance N e coloque-o em [sfen:] (0 é o início; sem --ply, a posição final):

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

Para o mesmo diagrama num artigo noutro sítio, exporte-o como SVG. --sfen não precisa de conta nem de rede; --game tira de uma partida a posição, os jogadores e a casa do último lance. Para um PNG, converta o SVG (rsvg-convert, ImageMagick, um navegador):

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 é só uma etiqueta e um filtro do feed; o corpo é apresentado da mesma forma. ARTICLE é um artigo, KIFU apresenta uma partida, BOOK apresenta um livro.

post create imprime a URL da publicação, /posts/<id>. A página de uma partida é /review/<gameId> (/game/<id> é o tabuleiro ao vivo), e é essa que kif import / upload imprimem:

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)

Limites: título de 200 caracteres, corpo de 50 000, até 20 etiquetas de 40 caracteres cada. A CLI para antes de enviar seja o que for que os ultrapasse.

Ver o que um procedimento recebe:

shogidojo procedures --describe quiz.import

Partidas:

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

Publicações:

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

Quizzes (playedUsi / playedNotation são o lance jogado na partida, gameId a partida de origem; ambos opcionais):

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)

Uma mensagem "Unsupported engine" ou um erro de sintaxe costuma significar que o Node é demasiado antigo. É preciso a 20 ou mais recente:

node --version

Se a instalação global falhar com EACCES, mova o prefixo de instalação para a sua pasta pessoal em vez de recorrer a sudo:

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

login --browser imprime uma URL, mas o endereço de retorno dentro dela aponta para o loopback da máquina que a imprimiu. Abrir essa URL noutra máquina faz o login lá e a chave não chega a lugar nenhum. Por SSH, encaminhe uma porta e passe-a com --port, ou cole a chave com --stdin — os dois estão acima:

shogidojo login --stdin