Cloudflare cria CLI unificada para toda a linha de produtos

 (blog.cloudflare.com)
5 pontos por GN⁺ 16 일 전 | 2 comentários | Compartilhar no WhatsApp
  • A Cloudflare está reconstruindo o Wrangler de próxima geração para oferecer mais de 100 produtos e cerca de 3.000 APIs HTTP em uma única CLI unificada (cf), com prévia técnica já disponível via npx cf
  • Como apenas o esquema OpenAPI existente não conseguia representar interfaces diversas como comandos de CLI, bindings de Workers e skills de agentes, a empresa adotou um novo sistema de esquemas baseado em TypeScript
  • Seguindo a tendência de agentes usarem a CLI como principal consumidor, a Cloudflare passou a impor em nível de esquema regras de consistência e guardrails de comandos como get/--force/--json
  • Foi lançada em beta aberto a funcionalidade Local Explorer, que permite explorar facilmente recursos simulados no desenvolvimento local e inspecionar diretamente dados locais de KV, R2, D1 e outros
  • Ao oferecer toda a API da Cloudflare de forma consistente no mesmo formato tanto na CLI quanto no ambiente local, a empresa busca uma experiência de desenvolvimento otimizada para agentes e desenvolvedores

A escala da API da Cloudflare e a mudança para agentes

  • A Cloudflare possui mais de 100 produtos e cerca de 3.000 operações de API HTTP
  • Agentes estão emergindo como consumidores principais de APIs, e desenvolvedores já usam agentes de programação para criar e implantar aplicações, agentes e plataformas na Cloudflare
  • A empresa já disponibiliza toda a sua API em um servidor MCP único do Code Mode com menos de 1.000 tokens, mas ainda precisa cobrir mais interfaces como comandos de CLI, bindings de Workers, SDK, arquivos de configuração, Terraform, documentação para desenvolvedores e Agent Skills
  • A CLI Wrangler existente não incluía comandos para muitos produtos da Cloudflare, e agentes tendem a preferir CLI

Reconstrução da CLI Wrangler de próxima geração

  • A Cloudflare está reconstruindo a CLI Wrangler como uma CLI para toda a Cloudflare, com comandos para todos os produtos e configuração unificada em estilo infrastructure-as-code
  • A prévia técnica pode ser usada com npx cf ou instalada com npm install -g cf
  • No momento, apenas alguns produtos são suportados, mas internamente a empresa já testa uma versão que cobre toda a superfície de API da Cloudflare
  • Os comandos de cada produto estão sendo revisados e ajustados com saída ergonômica tanto para agentes quanto para humanos
  • Nos próximos meses, isso será combinado com os pontos fortes do Wrangler atual

Esquema baseado em TypeScript e pipeline de geração de código

  • Antes, a empresa gerava automaticamente API SDK, provider do Terraform e servidor MCP do Code Mode com base em esquemas OpenAPI
  • Atualizações de CLI, bindings de Workers, configuração em wrangler.jsonc, Agent Skills, dashboard e documentação ainda seguiam um processo manual, com erros frequentes e sem escalabilidade
  • Como o esquema OpenAPI só consegue descrever APIs REST, ele não conseguia representar comandos de CLI interativos que combinam desenvolvimento local e requisições de API, nem bindings de Workers baseados em RPC, Agent Skills e documentação
  • Observando que o TypeScript já é uma linguagem comum dentro da Cloudflare, a empresa concluiu em projetos como Cap n' Web, Code Mode e o sistema de RPC da plataforma Workers que expressar APIs em TypeScript era mais eficaz
  • Por isso, adotou um novo esquema TypeScript para definir APIs, comandos de CLI, argumentos e todo o contexto necessário para gerar interfaces
    • Trata-se de tipos TypeScript com convenções, linting e guardrails aplicados
    • Como é um formato próprio, ele oferece flexibilidade para suportar qualquer interface necessária, ao mesmo tempo em que ainda permite gerar esquemas OpenAPI

Consistência entre agentes e CLI, e engenharia de contexto

  • Agentes esperam consistência na CLI; se um comando usa info e outro usa get, o agente pode acabar chamando um comando que não existe
  • Em organizações grandes com centenas ou milhares de engenheiros, manter essa consistência apenas via revisão inevitavelmente cria falhas, como no modelo do queijo suíço
  • Impor consistência apenas na camada de CLI pode piorar o problema, fazendo com que CLI, API REST e SDK usem nomes diferentes
  • Por isso, a Cloudflare aplica regras e guardrails no nível do esquema: sempre get (nunca info), sempre --force (nunca --skip-confirmations), sempre --json (nunca --format) e assim por diante em todos os comandos
  • A CLI Wrangler tem uma estrutura especial porque funciona tanto com recursos simulados locais quanto com recursos remotos
    • Bancos de dados D1, buckets R2 e namespaces KV são suportados tanto local quanto remotamente
    • Isso pode causar confusão quando um agente acha que está alterando um banco remoto, mas na prática adiciona um registro ao banco local
    • A empresa fornece orientação explícita aos agentes com padrões consistentes e saídas que deixam claro se o alvo é local ou remoto

Local Explorer — exploração local com os mesmos recursos do remoto

  • O Local Explorer foi lançado em beta aberto e pode ser usado tanto na CLI Wrangler quanto no plugin Vite da Cloudflare
  • Durante o desenvolvimento local, é possível explorar diretamente os recursos simulados usados pelo Worker: KV, R2, D1, Durable Objects e Workflows
  • As mesmas ações possíveis na API e no dashboard da Cloudflare podem ser realizadas em um ambiente totalmente local, com a mesma estrutura de API
  • A Cloudflare vem investindo há anos em desenvolvimento totalmente local, e até bancos de dados serverless hospedados como o D1 podem rodar integralmente de forma local por meio de bindings, sem configuração nem ferramentas extras
    • O Miniflare (emulador de plataforma para desenvolvimento local) fornece a mesma API da produção e usa bancos SQLite locais
    • Isso permite escrever e executar testes rapidamente sem acesso à rede, inclusive offline
  • Antes, para verificar quais dados haviam sido salvos localmente, era preciso fazer engenharia reversa no diretório .wrangler/state ou instalar ferramentas de terceiros
  • Ao executar a aplicação pela CLI Wrangler ou pelo plugin Vite da Cloudflare, aparece um prompt para abrir o Local Explorer, com acesso pelo atalho e
    • Ele oferece uma interface local para ver os bindings conectados ao Worker atual e os respectivos dados
  • Ao desenvolver com agentes, isso ajuda a entender como eles estão manipulando os dados, além de permitir validação de esquema, seed de registros de teste e reset com DROP TABLE
  • A Cloudflare também oferece um espelho da API da Cloudflare que modifica apenas dados locais, permitindo acessar recursos locais com a mesma API usada no remoto
    • Como o formato de API é idêntico entre local e remoto, ao passar a flag --local na CLI a requisição é redirecionada para a API espelhada local e continua funcionando da mesma forma
  • A API local fica disponível no caminho /cdn-cgi/explorer/api, permitindo que agentes descubram a especificação OpenAPI nesse endereço e gerenciem recursos locais

Pedido de feedback e próximos passos

  • A prévia técnica da CLI de próxima geração já pode ser usada com npx cf ou npm install -g cf
  • A Cloudflare pede feedback não apenas sobre os recursos atuais da prévia técnica, mas também sobre o que usuários gostariam de ver em uma CLI para toda a plataforma Cloudflare
    • Tarefas que hoje exigem vários cliques no dashboard, mas que deveriam funcionar com um comando de CLI de uma linha
    • Itens que usuários gostariam de configurar em wrangler.jsonc (como registros DNS e regras de cache)
    • Pontos em que agentes ficam travados e comandos que deveriam existir na CLI
  • O feedback está sendo recebido no Cloudflare Developers Discord

Leituras relacionadas

2 comentários

 
eoeoe 15 일 전

Seria bom se eles também ajudassem a corrigir o erro que ocorre ao tentar exportar um banco de dados D1 com tabela FTS configurada.
É a parte mais inconveniente ao usar o wrangler.
 
GN⁺ 16 일 전
Comentários do Hacker News

  • Seria bom se o Wrangler CLI mostrasse antecipadamente as permissões de token de API necessárias durante o desenvolvimento local
    Assim daria para saber claramente quais permissões são exigidas antes do deploy, e seria ideal ter um comando como cf permissions check para verificar permissões ausentes ou desnecessárias

    • Concordo totalmente. Se o ChatGPT configurar as permissões erradas no começo, no fim você acaba passando horas vasculhando a documentação ou tentando diferentes combinações de tokens
    • Um comando doctor com essa função seria realmente muito útil. Queria que mais serviços oferecessem isso
    • Já configurei um token errado por causa de um typo no passado, e um recurso assim teria ajudado muito
    • Indo além, acho que também seria bom se o CLI pudesse gerar chaves automaticamente
    • No fim, acho que o ponto principal é aumentar a discoverability da API
      GraphQL segue bem os princípios de HATEOAS, então é vantajoso para LLMs explorarem a API
      Em vez de problemas causados por versões de documentação incompatíveis, uma estrutura em que a própria API revela suas capacidades é muito melhor

  • Eu gostaria que adicionassem primeiro controle de permissões no nível de grupo de recursos
    Hoje só existem permissões baseadas em zone (domínio), então recursos como workers, que não pertencem a uma zone, podem ter o código substituído ou ser excluídos mesmo com permissões baixas
    Seria ainda melhor se suportassem uma estrutura de super account + sub account como no GitHub Enterprise. Ex.: ACME Corp / ACME Corp (Prod)

    • Fiquei curioso se isso seria o mesmo conceito do recurso Cloudflare Organization
    • Mesmo que não desse para compartilhar domínios, uma estrutura de superaccount + subaccount seria realmente muito útil
    • Concordo que o fato de worker não ser baseado em zone reduz bastante a utilidade

  • Ótimo texto, me inspirou bastante. Mas achei curioso TypeSpec não ter sido mencionado
    É uma linguagem de schema no estilo TypeScript, que costumo descrever como “como seria se o OpenAPI tivesse sido realmente bem feito”
    Imagino que tenham achado que uma implementação própria seria mais simples e flexível. Hoje em dia, com agents, o custo de BYO também caiu bastante

    • Gosto muito do TypeSpec. Escrever OpenAPI fica bem mais fácil
      Mas hoje em dia prefiro APIs no estilo aep.dev. Graças aos padrões consistentes, fica fácil usar aepcli imediatamente ou criar o seu próprio
      O Terraform também funciona direto, sem provider separado
    • Fiquei curioso sobre quais partes do OpenAPI ele melhora

  • Ultimamente, esse design CLI-first centrado em AI agents tem sido interessante
    Nós também, ao criar ferramentas para desenvolvedores, fizemos primeiro o CLI e a API e só depois acoplamos o dashboard
    A ideia do cf permissions check mencionada acima é especialmente boa
    Agents usam bem o CLI, mas são ruins em diagnosticar a causa de erros.
    Mensagens de erro claras como “faltando scope X, execute cf token add --scope X” são muito mais importantes

  • Disseram que dá para testar o preview técnico imediatamente com npx cf, e tenho algumas dúvidas
    Queria saber se é open source e se há planos de disponibilizá-lo como binário único, sem Node.js.
    Será que poderiam aproveitar algo como o Bun, adquirido recentemente?

    • Também não consegui encontrar o repositório, mas o pacote npm está sob licença MIT e inclui source maps, então parece que será publicado em breve

  • Espero que evitem tokens de longa duração.
    Em vez disso, seria bom se fosse fácil criar tokens de curta duração e restritos no CLI, gerenciá-los em arquivos ou renová-los automaticamente
    Outra opção seria ter um modo proxy, delegando permissão de acesso apenas a um domínio ou bucket específico

    • Gosto da abordagem do GitLab, que gera de uma vez só um PAT de curta duração por meio de um servidor SSH

  • Ironicamente, com a era dos AI agents, estamos voltando ao desenvolvimento centrado em CLI
    Toda vez que vou limpar o cache da Cloudflare, preciso clicar em várias etapas na UI web, mas seria ótimo simplesmente dar um comando ao OpenClaw agent

    • Nem precisa usar o OpenClaw. Basta chamar diretamente o comando CLI. Essa é a essência do CLI

  • O método de autenticação do Wrangler oferece apenas duas opções: OAuth (acesso total) e tokens estáticos criados manualmente no dashboard
    Mas isso não se encaixa quando humanos e AI agents precisam ter fronteiras de permissão diferentes
    Seria bom poder criar diretamente no CLI tokens com escopo e curta duração
    Isso também está em discussão na issue #13042 do GitHub.
    Os tokens deveriam ser detalhados não só por tipo de recurso, mas também por ID do recurso e ação

  • Em 1º de abril, a Cloudflare apresentou o EmDash com suporte a x402, e agora parece estar focando no CLI
    Dá a impressão de que a Cloudflare está reconstruindo silenciosamente um ecossistema de desenvolvedores em que agents, e não humanos, são os principais usuários

  • Disseram que definiram API, comandos CLI, argumentos e contexto com schemas TypeScript,
    então fiquei curioso por que essa ferramenta ou framework não foi apresentada aqui
    Gostaria de saber se tem uma estrutura parecida com o TypeSpec citado acima