Interface de linha de comando

Última atualização: 6 de agosto de 2026

playserv é a CLI de operador da plataforma. Da sua máquina você se autentica no seu Project, implanta e gerencia Functions (cloud functions e game servers), gerencia secrets por Environment e rotaciona slugs públicos.

É um client leve: você envia apenas o código do seu handler — a plataforma sintetiza o Dockerfile e os arquivos de build, constrói a imagem e faz o rollout. Sem Dockerfile, sem registry de container e sem commit no git do seu lado.

---

Instalação

A CLI é uma ferramenta global .NET 10 chamada playserv.

dotnet tool

dotnet tool install --global PlayServ.Platform.Cli
playserv status        # verify it's on your PATH

Atualize depois com dotnet tool update --global PlayServ.Platform.Cli.

A partir do código

dotnet pack src/PlayServ.Platform.Cli          # → artifacts/nupkg/*.nupkg
dotnet tool install --global PlayServ.Platform.Cli --add-source artifacts/nupkg

# or run without installing:
dotnet run --project src/PlayServ.Platform.Cli -- functions list

observação

O endpoint da API da plataforma é embutido na CLI e não é configurável pelo usuário. O estado local (sessão + identidade resolvida) fica em ~/.playserv/config.json, escrito de forma atômica no login.

---

Autenticação

1

Obtenha uma Platform API key

Crie uma Platform API key para o seu Project no Backoffice — uma key publicável pk_* ou secreta sk_*. Cada key está atrelada a um Project e um Environment (dev ou prod). Veja API Key Management.

2

Faça login

playserv login <key>     # or: playserv login  (hidden prompt)

Isso troca a key na plataforma por uma sessão de operador e guarda os tokens de acesso e refresh, além da org / Project / env resolvidos. A key bruta nunca é salva. As sessões se renovam automaticamente (janela de 30 dias), inclusive depois de uma troca de slug, então você não é interrompido no meio do trabalho.

3

Confirme e gerencie a sessão

playserv status mostra o Project/org/env ativo com uma sondagem ao vivo; playserv logout limpa a sessão.

Todo comando com escopo de Project envia Authorization: Bearer <session>, X-Project-Slug e X-Env. --env é opcional e assume o env da sessão; um valor conflitante é recusado localmente.

---

Implantar uma Function

functions deploy (alias fn deploy) é o fluxo central: empacota o seu código local, faz o upload e deixa a plataforma construir e publicar o serviço — acompanhando até o fim.

playserv fn deploy --slug <slug> --kind <game_server|cloud_function> --src <path> \
  [--language <csharp|node|python|go>] [--env <dev|prod>] [--poll-timeout <seconds>]

Opção	Obrigatória	Descrição
--slug	Sim	Nome público da Function. Precisa ser um nome válido de Cloud Run — letras minúsculas, dígitos, hifens, 3 a 50 caracteres. Validado localmente antes do upload.
--kind	Sim	cloud_function (Function HTTP) ou game_server (serviço de longa duração).
--src	Sim	Um único arquivo de código ou um diretório. bin/, obj/, .git/ e node_modules/ ficam de fora do pacote.
--language	Não	csharp, node, python ou go. Detectado a partir de --src quando omitido (veja abaixo).
--env	Não	Environment de destino; assume o env da sessão.
--poll-timeout	Não	Quanto tempo esperar pelo build/rollout antes de desistir.

O que acontece na implantação: a CLI empacota --src em um .tar.gz, faz o upload (encaminhando as bindings do platform.json — variáveis de ambiente, secrets, escala, triggers) e acompanha a implantação por queued → uploading → building → deploying → deployed. A plataforma sintetiza o Dockerfile e os arquivos de build e roda o build; nada disso vem de você.

Linguagens

A CLI é multilinguagem. O que é suportado depende do kind:

Kind	csharp	node	python	go
cloud_function	✓	✓	✓	✓
game_server	✓	✓	—	—

Game servers em python e go são recusados hoje — ainda não há runtime para eles. Cloud functions suportam as quatro.

Detecção automática (quando --language é omitido):

• por extensão de arquivo — .cs → csharp, .js/.mjs/.cjs → node, .py → python, .go → go;
• por marcador de diretório — um .csproj → csharp, package.json → node, go.mod → go, requirements.txt ou main.py → python;
• cai para csharp se nada casar.

C#

playserv fn deploy --slug match-maker --kind game_server --src ./server --language csharp

Node / TypeScript

playserv fn deploy --slug leaderboard --kind cloud_function --src ./fn --language node

--language node aceita TypeScript puro — aponte --src para uma pasta com package.json + tsconfig.json + src/**, sem index.js pré-compilado. A plataforma transpila o entry (src/index.ts por padrão, ou o campo entry do platform.json) com esbuild no momento do build. É só transpilação — rode a checagem de tipos na sua CI. node_modules/** e qualquer arquivo .env* nunca são enviados; os pacotes npm são instalados durante o build e resolvidos em runtime.

Python

playserv fn deploy --slug webhook --kind cloud_function --src ./fn --language python

Python está disponível apenas para cloud_function.

Go

playserv fn deploy --slug webhook --kind cloud_function --src ./fn --language go

Go está disponível apenas para cloud_function.

platform.json

Um platform.json ao lado do seu código é a fonte da verdade para variáveis de ambiente, secrets, escala e triggers — o deploy encaminha essas bindings. Os valores dos secrets são definidos à parte, com secrets set; o manifesto só declara quais nomes de secret a Function usa.

Dependências em monorepo

Para node, uma dependência local file: cujo código vive fora de --src (por exemplo "@scope/shared": "file:../shared") é embutida no pacote na hora do deploy e recebe um alias para a etapa de esbuild da plataforma — então um servidor que importa ../shared continua implantando a partir de --src ./server, sem build local. Dependências de registry seguem externas.

Ressalvas do deploy

• Environments copiados ficam bloqueados. Um env criado como cópia de outro não traz link de deploy: fn deploy nele falha com 409 env_not_linked até que um operador o re-vincule (aba Environments → Re-link deploys). Builds que já estejam rodando ali não são afetados.
• Recriar um slug que já existiu antes pode fazer o build falhar — se isso acontecer, rode fn delete nele e implante de novo do zero.
• Um game_server recém-implantado pode retornar 401 no uplink interno até que a service account de compute dele receba os papéis corretos de run (uma política da organização pode remover o binding não autenticado).

---

Gerenciar Functions

playserv fn list [--env <env>]
playserv fn invoke --slug <slug> (--json '<json>' | --body <file>)
playserv fn delete --slug <slug> [-y]

• list — tabela das Functions provisionadas: slug, kind, linguagem, status, URL pública e id.
• invoke — chama uma cloud_function pelo gateway POST /fn/<slug>, com um corpo JSON inline (--json) ou um arquivo (--body).
• delete — derruba o serviço Cloud Run e o registro na plataforma (-y pula a confirmação).

---

Secrets

Secrets de Function por Environment. Os valores são lidos apenas de stdin — nunca de um argumento — para que não fiquem no histórico do shell.

printf '%s' "$MY_VALUE" | playserv secrets set STRIPE_KEY --env prod
playserv secrets list [--env <env>]
playserv secrets delete STRIPE_KEY [--env <env>]

• set cria ou rotaciona um secret e faz um restart gradual das Functions que o usam.
• list mostra os nomes com last_set_at e in_use_by — nunca os valores.
• delete é recusado com 409 in_use enquanto alguma Function ainda declarar o secret.

As Functions declaram de quais nomes de secret precisam no platform.json; secrets set fornece os valores.

---

Slugs públicos

Rotação dos slugs públicos de org/Project, restrita ao owner. Com limite de frequência (uma vez a cada 30 dias, 5 no total); o slug antigo redireciona por uma janela e depois passa a retornar 404.

playserv org:regenerate-slug     --confirmation <current-slug> [--redirect-window-days <N>]
playserv project:regenerate-slug --confirmation <current-slug> [--redirect-window-days <N>]

---

Referência de comandos

Comando	Para que serve
playserv login [token]	Trocar uma key pk_*/sk_* por uma sessão de operador.
playserv logout	Limpar a sessão local.
playserv status	Mostrar o estado de login com uma sondagem ao vivo da sessão.
playserv fn list [--env]	Listar as Functions provisionadas.
playserv fn deploy --slug --kind --src [--language] [--env] [--poll-timeout]	Empacotar, enviar, construir e publicar uma Function.
playserv fn invoke --slug (--json | --body)	Invocar uma cloud function.
playserv fn delete --slug [-y]	Excluir uma Function.
playserv secrets set <NAME> [--env]	Criar/rotacionar um secret (valor via stdin).
playserv secrets list [--env]	Listar os nomes dos secrets.
playserv secrets delete <NAME> [--env]	Excluir um secret.
playserv org:regenerate-slug --confirmation <slug>	Rotacionar o slug público da org.
playserv project:regenerate-slug --confirmation <slug>	Rotacionar o slug público do Project.

fn é um alias para functions. O código de saída é 0 em caso de sucesso; o deploy usa códigos diferentes de zero distintos para cada classe de falha.

---

Próximos passos

• Functions — o que são cloud functions e game servers, e como eles rodam
• API Key Management — as keys com as quais você faz login