У Cloudflare обширная API-поверхность. У нас более 100 продуктов и около 3000 HTTP-API операций.
Все чаще основными пользователями наших API становятся агенты. Разработчики используют своих кодирующих агентов для создания и развертывания приложений, агентов и платформ на Cloudflare, настройки своего аккаунта и запросов к нашим API для аналитики и логов.
Мы хотим сделать каждый продукт Cloudflare доступным всеми способами, которые нужны агентам. Например, теперь мы делаем весь API Cloudflare доступным в одном MCP-сервере Code Mode, который использует менее 1000 токенов. Однако предстоит охватить гораздо большую поверхность: Команды CLI. Workers Bindings — включая API для локальной разработки и тестирования. SDK на множестве языков. Наш конфигурационный файл. Terraform. Документация для разработчиков. API-документация и схемы OpenAPI. Agent Skills.
Сегодня многие из наших продуктов недоступны через каждый из этих интерфейсов. Это особенно касается нашего CLI — Wrangler. У многих продуктов Cloudflare нет команд CLI в Wrangler. А агенты обожают CLI.
Поэтому мы перестроили CLI Wrangler, чтобы сделать его CLI для всего Cloudflare. Он предоставляет команды для всех продуктов Cloudflare и позволяет настраивать их вместе с использованием инфраструктуры как кода.
Сегодня мы делимся ранней версией того, как будет выглядеть следующая версия Wrangler, в качестве технического предварительного просмотра. Это очень ранняя стадия, но мы получаем лучшую обратную связь, когда работаем открыто.
Вы можете попробовать Технический предварительный просмотр сегодня, выполнив npx cf. Или вы можете установить его глобально, выполнив npm install -g cf.
Прямо сейчас cf предоставляет команды лишь для небольшого подмножества продуктов Cloudflare. Мы уже тестируем версию cf, которая поддерживает всю API-поверхность Cloudflare — и мы намеренно будем проверять и настраивать команды для каждого продукта, чтобы вывод был эргономичным как для агентов, так и для людей. Чтобы было понятно, этот Технический предварительный просмотр — всего лишь небольшая часть будущего CLI Wrangler. В течение следующих месяцев мы объединим это с частями Wrangler, которые вы знаете и любите.
Чтобы построить это таким образом, чтобы успевать за быстрым темпом разработки продуктов в Cloudflare, нам пришлось создать новую систему, которая позволяет нам генерировать команды, конфигурацию, API привязок и многое другое.
Переосмысление схем и нашего конвейера генерации кода с первых принципов
Мы уже генерируем API SDK Cloudflare, провайдер Terraform и MCP-сервер Code Mode на основе схемы OpenAPI для API Cloudflare. Но обновление нашего CLI, Workers Bindings, конфигурации wrangler.jsonc, Agent Skills, панели управления и документации по-прежнему остается ручным процессом. Это уже было чревато ошибками, требовало слишком много согласований и не могло масштабироваться для поддержки всего API Cloudflare в следующей версии нашего CLI.
Для этого нам нужно было больше, чем можно выразить в схеме OpenAPI. Схемы OpenAPI описывают REST API, но у нас есть интерактивные команды CLI, которые включают несколько действий, сочетающих локальную разработку и API-запросы, Workers bindings, выраженные как RPC API, а также Agent Skills и документацию, которая все это связывает воедино.
Мы пишем много TypeScript в Cloudflare. Это лингва франка программной инженерии. И мы продолжаем обнаруживать, что просто лучше выражать API на TypeScript — как мы это делаем с Cap n’ Web, Code Mode и RPC-системой, встроенной в платформу Workers.
Поэтому мы представили новую схему TypeScript, которая может определять полный объем API, команд CLI и аргументов, а также контекст, необходимый для генерации любого интерфейса. Формат схемы — это «всего лишь» набор типов TypeScript с соглашениями, линтерами и ограничениями для обеспечения согласованности. Но поскольку это наш собственный формат, его можно легко адаптировать для поддержки любого интерфейса, который нам нужен сегодня или в будущем, при этом также имея возможность генерировать схему OpenAPI:
До сих пор большая часть нашего внимания была сосредоточена на этом уровне — создании необходимой нам машины, чтобы мы могли теперь начать создавать CLI и другие интерфейсы, которые мы годами хотели иметь возможность предоставлять. Это позволяет нам начать мечтать о большем в отношении того, что мы могли бы стандартизировать в Cloudflare и улучшить для Агентов — особенно когда дело доходит до контекстной инженерии нашего CLI.
Агенты и CLI — согласованность и контекстная инженерия
Агенты ожидают от CLI согласованности. Если одна команда использует синтаксис <command> info для получения информации о ресурсе, а другая использует <command> get, агент будет ожидать одну и вызывать несуществующую команду для другой. В крупной инженерной организации из сотен или тысяч людей и со множеством продуктов ручное обеспечение согласованности через ревью — это швейцарский сыр. И вы можете обеспечить ее на уровне CLI, но тогда наименования будут различаться между CLI, REST API и SDK, что, возможно, усугубляет проблему.
Одна из первых вещей, которые мы сделали, — начали создавать правила и ограничения, применяемые на уровне схемы. Всегда get, никогда info. Всегда --force, никогда --skip-confirmations. Всегда --json, никогда --format, и всегда поддерживается во всех командах.
CLI Wrangler также довольно уникален — он предоставляет команды и конфигурацию, которые могут работать как с симулированными локальными ресурсами, так и с удаленными, такими как базы данных D1, бакеты хранилища R2 и пространства имен KV. Это означает, что согласованные значения по умолчанию имеют еще большее значение. Если агент думает, что модифицирует удаленную базу данных, но на самом деле добавляет записи в локальную базу, а разработчик использует удаленные привязки для локальной разработки против удаленной базы данных, его агент не поймет, почему вновь добавленные записи не отображаются, когда агент делает запрос к локальному dev-серверу. Согласованные значения по умолчанию вместе с выводом, который четко указывает, применяются ли команды к удаленным или локальным ресурсам, гарантируют, что агенты получают явные указания.
Local Explorer — то, что вы можете сделать удаленно, теперь вы можете сделать локально
Сегодня мы также выпускаем Local Explorer, новую функцию, доступную в открытой бета-версии как в Wrangler, так и в плагине Cloudflare Vite.
Local Explorer позволяет интроспектировать симулированные ресурсы, которые ваш Worker использует при локальной разработке, включая KV, R2, D1, Durable Objects и Workflows. Все то, что вы можете делать через Cloudflare API и панель управления с каждым из них, вы также можете делать полностью локально, используя ту же базовую структуру API.
Годами мы делали ставку на полностью локальную разработку — не только для Cloudflare Workers, но и для всей платформы. Когда вы используете D1, даже несмотря на то, что D1 — это размещенный бессерверный продукт базы данных, вы можете запускать свою базу данных и общаться с ней через привязки полностью локально, без какой-либо дополнительной настройки или инструментов. Через Miniflare, наш эмулятор платформы локальной разработки, среда выполнения Workers предоставляет точно такие же API при локальной разработке, как и в production, и использует локальную базу данных SQLite для предоставления той же функциональности. Это упрощает написание и запуск тестов, которые работают быстро, без необходимости доступа к сети и работают офлайн.
Но до сих пор, чтобы понять, какие данные хранятся локально, требовалось реверс-инжиниринг, интроспекция содержимого директории .wrangler/state или установка сторонних инструментов.
Теперь всякий раз, когда вы запускаете приложение с помощью CLI Wrangler или плагина Cloudflare Vite, вам будет предложено открыть локальный обозреватель (сочетание клавиш e). Это предоставляет вам простой локальный интерфейс для просмотра того, какие привязки в данный момент подключены к вашему Worker, и какие данные в них хранятся.
При использовании Агентов для сборки, Local Explorer — отличный способ понять, что агент делает с данными, делая локальный цикл разработки гораздо более интерактивным. Вы можете обратиться к Local Explorer в любой момент, когда вам нужно проверить схему, добавить тестовые записи или просто начать заново и выполнить DROP TABLE.
Наша цель здесь — предоставить зеркальное отражение API Cloudflare, которое изменяет только локальные данные, чтобы все ваши локальные ресурсы были доступны через те же API, которые вы используете удалённо. И благодаря соответствию формы API в локальной и удалённой средах, когда вы запускаете команды CLI в предстоящей версии интерфейса командной строки и передаёте флаг --local, команды просто работают. Единственная разница в том, что команда отправляет запрос в это локальное зеркало API Cloudflare.
Начиная с сегодняшнего дня, этот API доступен по адресу /cdn-cgi/explorer/api в любом приложении, работающем на Wrangler или плагине Vite. Направив вашего агента на этот адрес, он найдёт спецификацию OpenAPI, которая позволит управлять вашими локальными ресурсами, просто общаясь с вашим агентом.
Расскажите нам о ваших надеждах и мечтах касательно единого CLI для Cloudflare
Теперь, когда мы построили механизм, пришло время взять лучшие части сегодняшнего Wrangler, объединить их с тем, что стало возможным, и сделать Wrangler лучшим CLI для использования всех возможностей Cloudflare.
Вы можете попробовать техническую предварительную версию уже сегодня, выполнив npx cf. Или вы можете установить её глобально, выполнив npm install -g cf.
С этой самой ранней версией мы хотим получить ваши отзывы — не только о том, что делает техническая предварительная версия сегодня, но и о том, что вы хотите от CLI для всей платформы Cloudflare. Расскажите нам, что, по вашему мнению, должно быть простой однострочной командой CLI, но сегодня требует несколько кликов в нашей панели управления. Что вы хотели бы настроить в wrangler.jsonc — например, DNS-записи или правила кеширования. И где вы замечали, что ваши агенты застревают, и какие команды, по вашему мнению, наш CLI должен предоставлять для использования вашим агентом.
Присоединяйтесь к Discord для разработчиков Cloudflare и расскажите нам, что бы вы хотели, чтобы мы добавили в CLI в первую очередь, и следите за новостями — скоро будет много обновлений.