cf — единый CLI от Cloudflare для всего публичного API

· 3 мин чтения
cloudflare cli ai-agents devops workers
📂 Исходный код на GitHub

Единый CLI от Cloudflare, сгенерированный из публичного OpenAPI-описания платформы. Покрывает Workers, Pages, R2, D1, KV, Queues, Durable Objects, туннели и Zero Trust. Конфиг проекта переехал в cloudflare.config.ts, Vite стал сборщиком по умолчанию, есть локальный режим через Miniflare. Открытая бета 1.0, лицензия MIT или Apache-2.0.

cf — единый CLI от Cloudflare для всего публичного API

Cloudflare выпустил cf — единый CLI ко всему публичному API платформы. Отличие от привычных инструментов в том, что им можно пользоваться не только человеку, но и AI-агенту: нужную команду агент находит поиском, а ответ по умолчанию получает в JSON. Ставится пакетом cf из npm, требует Node.js 22 или новее. Сейчас это открытая бета-версия 1.0.

Что внутри

cf — не набор команд, написанных вручную, а результат генерации из публичного OpenAPI-описания Cloudflare. Отсюда два практических свойства:

  • покрытие платформы большое: Workers, Pages, R2, D1, KV, Queues, Durable Objects, Vectorize, туннели, Zero Trust, AI Gateway, аналитика, WAF, DNS;
  • набор команд меняется вместе с привязанной версией OpenAPI, поэтому список лучше смотреть через cf --help, а не запоминать.

Формат команд единый: cf <продукт> [группа…] <операция>. Секреты Workers лежат в cf workers secrets, туннели — в cf tunnels.

Установка

npm install -g cf

Пакет ставится глобально и даёт две равнозначные команды — cf и cloudflare. Нужен Node.js 22 или новее.

Автодополнение для shell подключается так:

cf complete bash >> ~/.bashrc

Первые шаги

cf auth login        # login into Cloudflare
cf --help            # list all commands
cf <command> --help  # help for a single command

Отдельная команда cf cli search ищет по всему каталогу команд, включая скрытые, и возвращает пять подходящих вариантов с короткими пояснениями. Если CLI понимает, что перед ним агент, он показывает подсказки по поиску команд перед выводом справки. Точные детали запроса по API-командам лежат в cf schema.

Аутентификация

Ключи берутся в таком порядке:

  1. переменная окружения CLOUDFLARE_API_TOKEN;
  2. OAuth-профиль, выбранный флагом --profile, привязанный к ближайшему каталогу либо профиль по умолчанию — он обновляется автоматически.

Именованные профили создаются и переключаются командами cf auth create, cf auth activate, cf auth deactivate, cf auth list и cf auth delete. Профиль по умолчанию живёт под cf auth login и cf auth logout.

Телеметрию можно отключить переменными DO_NOT_TRACK=1 и CF_QUIET=1.

Проекты и cloudflare.config.ts

cloudflare.config.ts — новый формат конфигурации Cloudflare. Файл написан на TypeScript, поэтому редактор и языковой сервер подсказывают поля, а агент читает готовые типы вместо того, чтобы угадывать названия.

Команда cf init my-worker создаёт заготовку: Worker на hello-world, файлы cloudflare.config.ts, vite.config.ts, src/index.ts, tsconfig.json, package.json и .gitignore. Дальше она ставит зависимости тем пакетным менеджером, который вы выбрали (--package-manager, либо --no-install, чтобы пропустить установку), и генерирует типы в .cloudflare/types/index.d.ts. С флагом --no-install типы создаются позже — их сделает cf dev или скрипт typecheck в новом проекте, который выполняет cf workers types && tsc.

Если в каталоге уже есть файлы, cf init не создаёт новый проект, а автоматически настраивает существующий. В README этот режим называется autoconfig.

Пример конфигурации с контейнером и Durable Object:

import {
  bindings,
  defineConfig,
  defineContainer,
  exports as configExports,
} from "cf/config";
import * as entrypoint from "./src/worker" with { type: "cf-worker" };

const workerName = "cf-vite-container-fixture";

const fixtureContainer = defineContainer({
  name: "cf-vite-container-fixture-app",
  image: {
    dockerfile: "./Dockerfile",
  },
  instanceType: "lite",
  maxInstances: 1,
});

export default defineConfig({
  worker: {
    name: workerName,
    entrypoint,
    compatibilityDate: "2026-09-12",
    exports: {
      ContainerDO: configExports.durableObject({
        storage: "sqlite",
        container: fixtureContainer,
      }),
    },
    env: {
      CONTAINER: bindings.durableObject({
        worker: workerName,
        exportName: "ContainerDO",
      }),
    },
    observability: { enabled: true },
  },
  containers: [fixtureContainer],
});

Команды cf dev и cf build сами определяют тип проекта, при необходимости запускают настройку и вызывают штатную команду фреймворка или установленную реализацию Cloudflare. Успешная сборка даёт стандартный Build Output.

Деплой, версии и триггеры

cf deploy                        # build, then upload
cf workers versions create       # upload a version without deploying
cf workers triggers deploy       # apply routes and cron schedules

К любой из этих команд можно добавить --prebuilt, чтобы взять уже готовый Build Output и не пересобирать.

Для проектов на wrangler есть cf migrate: команда переводит конфиг wrangler (JSON, JSONC или TOML) в cloudflare.config.ts через @cloudflare/codemods. Поддерживает Vite и Wrangler как сборщики, пробный запуск и защиту от изменений при нечистом рабочем дереве, а в конце перечисляет, что осталось поправить руками.

Локальные ресурсы

К поддерживаемым командам можно добавить флаг --local — тогда команда выполняется против недолговещего экземпляра Miniflare, который работает поверх сохранённого локального состояния. Прямо из состояния на диске работают операции KV (получить, список, обновить, удалить и массовое получение), D1 (сырой запрос и применение миграций) и R2 (получить, загрузить, список объектов и массовое удаление по массиву). Часть операций Durable Objects и Workflow дополнительно требует совместимый живой узел реестра, который объявляет нужные биндинги.

Каталог состояния меняется флагом --persist-to <directory>; он имеет смысл только вместе с --local. У команды без локального аналога вы получите ошибку, а не неожиданный запрос к боевому окружению.

Вывод в терминал

Структурированные ответы API печатаются в stdout как JSON с отступами. Ответы типов binary и text пишутся в stdout напрямую, чтобы бинарный вывод можно было перенаправить в файл; у части команд есть флаг --text для расшифровки в UTF-8. Служебные отметки об успехе с пустым результатом уходят в stderr.

Если нужно отфильтровать вывод:

cf d1 execute my-db --command "select 1" --local | jq '.result[0]'

Анимация прогресса идёт через stdout на интерактивном терминале с цветом и отключается для пайпов, для терминалов без цвета и при CF_QUIET=1. Цвета отключаются переменной NO_COLOR=1. В поддерживаемых терминалах прогресс дублируется в названии вкладки и в панели задач — это выключается через CF_NO_OSC_PROGRESS=1 и включается принудительно через CF_FORCE_OSC_PROGRESS=1.

Статус и лицензия

Проект в открытой бете 1.0: версии выходят под тегом beta в npm. Перед сборкой CLI требует Vite-плагин второй версии, тоже в бете; первая версия плагина больше не подходит как локальная реализация для запуска. Лицензия двойная — MIT или Apache-2.0, на ваш выбор.

Подробное описание команд и состав телеметрии собраны в README пакета CLI и в файле про телеметрию.

Ссылки

Источник: https://github.com/cloudflare/cf

Похожие материалы