Pular para o conteúdo principal
Engenharia

Esta página ainda não foi traduzida: mostrando a versão em inglês.

Interface de linha de comando

playserv é a ferramenta de linha de comando para operar o backend do seu jogo pelo terminal ou pelo CI. Ela cria a estrutura de Functions e Game servers e faz o deploy deles, lê os logs, ajusta a escala e gerencia API keys e secrets. Cada comando trabalha dentro de um Environment de projeto com login feito e pode imprimir uma saída legível por máquina para scripts.

Esta página trata da instalação, do login e de todos os comandos. Como fazer o build e publicar o código está em Deploy com a CLI.


Instalação

Baixe o binário playserv para o seu sistema operacional com Download CLI no Backoffice — na página Functions de um projeto que ainda não tem nenhuma, ou no banner de configuração de um projeto novo — e coloque-o no seu PATH.

Ela também é uma ferramenta global do .NET no feed NuGet da PlayServ, que não exige credenciais. Registre o feed uma vez e instale:

dotnet nuget add source https://nuget.playserv.com/v3/index.json -n playserv
dotnet tool install --global PlayServ.Platform.Cli
playserv --version

Para atualizar, use dotnet tool update --global PlayServ.Platform.Cli. Em qualquer caso, criar projetos C# exige o .NET 10 SDK.


Login

A CLI trabalha dentro de uma sessão aberta com uma API key de servidor. A sessão pertence ao projeto e ao Environment da key, e todos os comandos seguintes atuam neles.

playserv status
playserv login <sk_your_key>
playserv logout
ComandoO que faz
playserv login <key>Abre uma sessão. Só aceita keys de servidor (sk_…); uma key de cliente (pk_…) é recusada.
playserv statusMostra o endereço da plataforma, a organização, o projeto e o Environment da sessão. Sai com 1 quando não há login, para que scripts possam usá-lo como verificação.
playserv logoutEncerra a sessão.

Crie keys no Backoffice (Gerenciamento de API keys) ou com playserv keys create. A sessão nunca guarda a key em si.

--env verifica o Environment, não troca de Environment

A maioria dos comandos aceita --env <env>, mas passar um Environment diferente do da sessão é recusado. Use em scripts para garantir onde um comando roda. Para trabalhar em outro Environment, faça login com uma key dele: mantenha uma key de dev e outra de prod e rode playserv status antes de qualquer operação destrutiva.

A CLI aponta para a plataforma para a qual o build dela foi feito. Quando definida, PLAYSERV_API_URL faz todos os comandos apontarem para outro endereço de plataforma.


Referência de comandos

functions pode ser abreviado como fn. Os comandos que removem ou substituem algo pedem confirmação: publish, functions delete, rollback, disable, keys revoke, keys undo-revoke, keys rotate e rooms config delete. -y / --yes pula a confirmação; os outros comandos não aceitam essa flag.

Build e publicação. Detalhes e opções estão em Deploy com a CLI.

ComandoO que faz
playserv init <slug>Cria um projeto com o seu platform.json: um Game server por padrão, uma cloud function com --kind cloud_function. --solution <Name> cria, em vez disso, uma solution com projetos compartilhados.
playserv publishFaz o deploy de todas as Functions da solution que têm platform.json, depois de mostrar o plano.
playserv functions deploy --slug <slug> --kind <kind>Faz o deploy de uma Function a partir do código-fonte.
playserv functions declare <slug>Registra uma Function sem fazer deploy de código, por exemplo um Game server que você mesmo executa.
playserv image push --slug <slug>Faz o build e envia a imagem de um Game server para um pool de máquinas; --roll passa o pool para essa imagem.
playserv rooms config get|set|delete <slug>Lê ou substitui as configurações de Room de um Game server.

Inspeção.

ComandoO que faz
playserv functions listTodas as Functions do Environment: slug, tipo, linguagem, status, endereço.
playserv functions logs <slug>Linhas de log recentes. --tail N, --since <ISO 8601>, --level error|warn|info.
playserv functions deploys listO histórico de deploys do Environment, com os IDs.
playserv functions deploys get <id>Fase, mensagem e tempos de um deploy, pelo ID que functions deploy imprimiu.
playserv functions replicas <slug>Réplicas em execução, com ID, região, status e horário de início.

Operação.

ComandoO que faz
playserv functions redeploy <slug>Reinicia a Function no build atual, sem refazer o build.
playserv functions rollback <slug> --to <deploy-id>Devolve o tráfego para um deploy anterior, pelo ID dele em deploys list.
playserv functions enable <slug> · disable <slug>Retoma ou para o atendimento de tráfego. A Function e os dados dela continuam lá.
playserv functions scale <slug> --policy manual|auto --desired N --min N --max NSubstitui a especificação de escalonamento. As quatro flags são obrigatórias.
playserv functions delete --slug <slug>Remove a Function do Environment.

Keys e secrets.

ComandoO que faz
playserv keys listTodas as keys do Environment, com tipo, prefixo, status e último uso. Os valores secretos nunca são mostrados de novo.
playserv keys create --name <name> [--kind sk|pk]Cria uma key de servidor (padrão) ou de cliente e imprime o segredo uma única vez.
playserv keys rotate <id>Substitui o segredo. O antigo para de funcionar na hora.
playserv keys revoke <id> · keys undo-revoke <id>Revoga uma key, fechando as conexões ativas dela, ou cancela a revogação dentro da janela para desfazer.
playserv secrets set <NAME>Define ou rotaciona um secret. O valor é lido do stdin ou de um prompt oculto, nunca de um argumento.
playserv secrets list · secrets delete <NAME>Lista os nomes dos secrets e quais Functions os usam, ou exclui um deles.

Somente para o owner.

ComandoO que faz
playserv org:regenerate-slug --confirmation <slug>Gera de novo o slug público da organização.
playserv project:regenerate-slug --confirmation <slug>Gera de novo o slug público do projeto.

O slug antigo continua funcionando por --redirect-window-days dias (de 0 a 180, padrão 60). A regeneração é limitada a uma vez a cada 30 dias e a cinco vezes por recurso.


Secrets

Secrets são valores nomeados, guardados por projeto e Environment, nunca no git nem em um pacote de deploy. Uma Function lista no platform.json os nomes de que precisa e os lê como variáveis de ambiente; definir um nome que já existe o rotaciona, e as Functions que o usam passam a receber o novo valor.

printf %s "$STRIPE_KEY" | playserv secrets set STRIPE_API_KEY

Um secret não pode ser excluído enquanto alguma Function ainda o declara (secret_in_use): remova-o do manifesto, faça o deploy de novo e então exclua. Em um Environment novo, defina os secrets antes do primeiro deploy; uma Function cujo secret declarado não tem valor fica em failing até recebê-lo.


Scripts e CI

--json torna qualquer comando legível por máquina. Em caso de sucesso, ele imprime um objeto ou array JSON no stdout; uma falha imprime {"error": {…}} no stderr, com summary, detail, hint e um code. Um deploy que falha ou estoura o tempo imprime o resultado no stdout, e publish informa o erro de cada Function nos resultados. Com --json, nenhum prompt fica esperando: ele falha e indica qual flag passar.

Código de saídaSignificado
0Sucesso, incluindo um upload com --detach que foi aceito.
1Falha geral: argumentos inválidos, uma confirmação recusada, um erro da API ou um publish com pelo menos uma Function com falha.
2A plataforma recusou o upload ou não pôde ser alcançada, ou o login falhou.
3O build falhou.
4A CLI parou de esperar, ou perdeu a conexão durante o upload ou o build. O build ainda pode terminar.
5A sessão expirou durante a espera.

Um job de CI típico guarda como secret uma key sk_ do Environment de destino e executa:

playserv login "$PLAYSERV_KEY" --json
playserv status --json
playserv publish --dry-run --json
playserv publish --yes --parallel 4 --json

Flags desconhecidas são erros (invalid_arguments), então um erro de digitação nunca faz outra coisa em silêncio.


Erros

CódigoO que fazer
not_logged_inRode playserv login.
env_not_resolved--env indica um Environment diferente do da sessão. Faça login com uma key desse Environment ou remova --env.
env_not_linkedO Environment não está vinculado para deploys. Um operador o vincula de novo em Project settings → Environments com Re-link deploys; os builds já em andamento continuam.
invalid_argumentsFlag desconhecida ou malformada. Consulte playserv <command> --help.
invalid_bundleO pacote ou o platform.json está malformado. A mensagem indica o arquivo.
invalid_manifestUma regra do manifesto falhou: valor inválido, escala fora do intervalo, cron inválido, nome reservado. A mensagem indica a regra.
duplicate_function_slugDois manifestos da solution usam o mesmo slug.
unknown_function_filterpublish --only indicou uma Function que não está na solution.
upload_timeoutO upload não terminou a tempo. Nada foi publicado; tente de novo.
function_not_found · deployment_not_foundNão existe esse slug ou esse deploy aqui. Confira functions list ou functions deploys list.
secret_in_use · secret_not_foundVeja Secrets.
token_slug_staleA sessão é anterior a uma mudança de slug. Faça login de novo.
prompt_unavailableEra necessária uma confirmação com --json ou em um pipe. Passe a flag indicada na mensagem.
platform_unreachable · platform_timeoutVerifique a rede e o endereço que playserv status mostra, depois tente de novo.
unreadable_responseA CLI e a plataforma estão em versões diferentes. Atualize a CLI.

Quando um deploy falha e o motivo não está claro, rode playserv functions deploys get <id> para ver a fase e a mensagem e, em seguida, playserv functions logs <slug> --level error. Quando uma Function retorna 404 logo depois de um deploy, confira o Environment com playserv status: uma Function publicada em dev não existe em prod.


Próximos passos

  • Deploy com a CLI — crie a estrutura, faça o deploy e publique Functions e Game servers
  • Functions — acompanhe as Functions publicadas no Backoffice
  • Servers — execute Game servers em pools de máquinas

Atualizado em 14 de out. de 2026