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
| Comando | O que faz |
|---|---|
playserv login <key> | Abre uma sessão. Só aceita keys de servidor (sk_…); uma key de cliente (pk_…) é recusada. |
playserv status | Mostra 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 logout | Encerra 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.
| Comando | O 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 publish | Faz 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.
| Comando | O que faz |
|---|---|
playserv functions list | Todas 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 list | O 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.
| Comando | O 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 N | Substitui 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.
| Comando | O que faz |
|---|---|
playserv keys list | Todas 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.
| Comando | O 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ída | Significado |
|---|---|
0 | Sucesso, incluindo um upload com --detach que foi aceito. |
1 | Falha geral: argumentos inválidos, uma confirmação recusada, um erro da API ou um publish com pelo menos uma Function com falha. |
2 | A plataforma recusou o upload ou não pôde ser alcançada, ou o login falhou. |
3 | O build falhou. |
4 | A CLI parou de esperar, ou perdeu a conexão durante o upload ou o build. O build ainda pode terminar. |
5 | A 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ódigo | O que fazer |
|---|---|
not_logged_in | Rode 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_linked | O 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_arguments | Flag desconhecida ou malformada. Consulte playserv <command> --help. |
invalid_bundle | O pacote ou o platform.json está malformado. A mensagem indica o arquivo. |
invalid_manifest | Uma regra do manifesto falhou: valor inválido, escala fora do intervalo, cron inválido, nome reservado. A mensagem indica a regra. |
duplicate_function_slug | Dois manifestos da solution usam o mesmo slug. |
unknown_function_filter | publish --only indicou uma Function que não está na solution. |
upload_timeout | O upload não terminou a tempo. Nada foi publicado; tente de novo. |
function_not_found · deployment_not_found | Não existe esse slug ou esse deploy aqui. Confira functions list ou functions deploys list. |
secret_in_use · secret_not_found | Veja Secrets. |
token_slug_stale | A sessão é anterior a uma mudança de slug. Faça login de novo. |
prompt_unavailable | Era necessária uma confirmação com --json ou em um pipe. Passe a flag indicada na mensagem. |
platform_unreachable · platform_timeout | Verifique a rede e o endereço que playserv status mostra, depois tente de novo. |
unreadable_response | A 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