Практическое руководство по новому CLI cf от Cloudflare

cf — это инструмент командной строки Cloudflare, охватывающий весь API Cloudflare. Открытая бета-версия вышла 28 сентября 2026 года. Устанавливается он командой npm i -g cf и требует Node.js 22.18 или новее.

Если вы деплоите Workers с помощью Wrangler, то, скорее всего, всё равно открываете дашборд, чтобы управлять DNS, зонами и настройками, которые Wrangler никогда не поддерживал. cf закрывает обе задачи: и ресурсы аккаунта, и проекты Workers — в одном бинарнике. В этом руководстве мы разберём установку, чтение вывода, написание нового конфига на TypeScript, деплой и перенос существующего Worker. Если нужно сначала освежить знания о Workers, начните с этого руководства по Cloudflare Workers для начинающих.

Чем cf отличается от Wrangler?

cf приходит на смену CLI, который разрастался по одной команде за раз, и генерируется из OpenAPI-схем Cloudflare. Согласно анонсу запуска, cf поддерживает более 3000 операций API против примерно 280 в Wrangler. В документации cf считают иначе: более 2900 команд. Cloudflare разрабатывала cf с прицелом на ИИ-агентов для программирования, но каждая команда работает точно так же, когда вы вводите её вручную.

В записи в changelog предупреждают, что команды, конфигурация и формат Build Output ещё могут измениться до стабильного релиза.

Как установить cf и войти в аккаунт?

Установите пакет cf из npm, затем авторизуйтесь с помощью cf auth login. Команду с именем cf устанавливают и другие инструменты, поэтому убедитесь, что у вас официальный пакет — он ссылается на репозиторий cloudflare/cf.

npm i -g cf
cf --version

cf auth login     # add --no-browser over SSH or in a container
cf auth whoami

Согласно документации Get started, пакет предоставляет один и тот же CLI под двумя именами — cf и cloudflare. Если в вашем PATH на cf уже откликается что-то другое, используйте имя cloudflare. При входе cf показывает ссылку и одноразовый код, а затем открывает эту ссылку в браузере, чтобы вы подтвердили доступ. cf хранит собственные учётные данные, поэтому авторизация в Wrangler на него не распространяется.

В CI вместо этого задайте CLOUDFLARE_API_TOKEN и CLOUDFLARE_ACCOUNT_ID. Токен, заданный таким образом, имеет приоритет над любым сохранённым входом.

Начните с команды, которая только читает данные:

cf zones list

Как читать и фильтровать JSON-вывод cf?

Большинство команд cf записывают результаты в stdout в формате JSON, а сообщения о ходе выполнения и статусе — в stderr. Поэтому результаты можно сохранить в файл или передать в jq без дополнительных флагов.

cf zones list > zones.json        # results only; status stays on stderr
cf zones list | jq .              # inspect the shape
cf zones list | jq '.[].id'       # print each zone's id
cf zones list --name example.com  # look up one domain

Как показано в документации по управлению ресурсами, cf zones list возвращает JSON-массив, в котором у каждой зоны есть поле id. Команды, работающие внутри зоны, принимают флаг --zone или его краткую форму -z и понимают как ID зоны, так и доменное имя:

cf dns records list --zone example.com
cf dns records list -z example.com

Поиск команд с помощью cf cli search

Чтобы найти нужную команду, выполните cf cli search с описанием задачи на естественном языке, а затем откройте справку по предложенной команде. Согласно документации для агентов, cf cli search возвращает до пяти совпадений в виде JSON-массива, начиная с наиболее подходящего. Поиск выполняется локально на вашей машине, поэтому входить в аккаунт не нужно.

cf cli search "create a DNS record"
cf dns --help
cf complete zsh >> ~/.zshrc   # shell completion

--help работает на любом уровне дерева команд.

Как настроить Workers с помощью cloudflare.config.ts?

cloudflare.config.ts — это конфигурационный файл cf для Workers на TypeScript. Он импортирует defineConfig из cf/config, экспортирует результат по умолчанию и объявляет биндинги и триггеры через типизированные хелперы, для которых редактор предлагает автодополнение. В справочнике по программной конфигурации подчёркивается, что файл является обычным TypeScript-модулем, поэтому в нём можно использовать импорты, функции, переменные окружения и асинхронные значения.

В первом примере из анонса модуль Worker импортируется с атрибутом импорта with { type: "cf-worker" }, после чего задаются name, entrypoint и compatibilityDate. В приведённых ниже фрагментах эти поля заменены на // .... В этом сокращённом фрагменте примера bindings из анонса в defineConfig передаётся функция, чтобы значения могли зависеть от mode:

import { bindings, defineConfig } from "cf/config";

export default defineConfig(({ mode }) => ({
  worker: {
    // ...
    env: {
      API_TOKEN: bindings.secret(),
      DATABASE: bindings.d1({ name: `example-${mode}-database` }),
      UPLOADS: bindings.r2({ name: `example-${mode}-uploads` }),
      JOBS: bindings.queue<{ userId: string }>({
        name: `example-${mode}-jobs`,
      }),
      AI: bindings.ai(),
    },
  },
}));

В полной версии примера также используются bindings.text, bindings.kv, bindings.vectorize и bindings.worker. Триггеры задаются в одном массиве. В этом фрагменте в defineConfig передаётся обычный объект:

import { defineConfig, triggers } from "cf/config";

export default defineConfig({
  worker: {
    // ...
    triggers: [
      triggers.fetch({ pattern: "example.com/*" }),
      triggers.scheduled({ schedule: "0 * * * *" }),
      triggers.queue({ name: "jobs", maxBatchSize: 10 }),
    ],
  },
});

В версии из анонса добавлен ещё элемент triggers.email. В справочнике также указан triggers.connect для работы с raw-сокетами. В анонсе Cloudflare сообщает, что планирует позволить настраивать в этом файле также зоны и DNS. Пока что экспорт по умолчанию описывает Worker, приложения Containers и настройки аккаунта.

Инициализация, деплой и миграция

Используйте cf init для нового проекта, cf deploy — для его выкатки и cf migrate — для существующего проекта Wrangler.

cf init my-worker      # or `cf init .` inside an existing app
cf deploy

cf init создаёт cloudflare.config.ts и vite.config.ts, а в существующем Vite-приложении устанавливает @cloudflare/vite-plugin. При запуске без аргументов команда останавливается и запрашивает директорию. Согласно документации по деплою, один вызов cf deploy собирает и проверяет проект, определяет, какие учётные данные и аккаунт использовать, затем загружает новую версию Worker (Worker Version) и делает её активной. Статическому сайту перед первым cf deploy конфигурационный файл не нужен.

Если в проекте есть wrangler.toml, wrangler.json или wrangler.jsonc, выполните миграцию до запуска cf dev, cf build или cf deploy. Эти три команды учитывают только cloudflare.config.ts и игнорируют любые конфигурационные файлы Wrangler.

cf migrate --dry-run
cf migrate

cf migrate читает TOML напрямую, поэтому предварительно конвертировать старые файлы не нужно. Если вам просто нужно представление устаревшего wrangler.toml в JSON, воспользуйтесь конвертером TOML в JSON. В руководстве cf для пользователей Wrangler поясняется, что при миграции сохраняется бандлер Wrangler, если только проект уже не использует Cloudflare Vite plugin, так что переход на Vite необязателен. Если бандлер Wrangler сохраняется, создаётся файл wrangler.config.ts, и, согласно документации по миграции, в пакете Worker должен быть установлен Wrangler версии 4.136.0 или новее. В анонсе также уточняется, что Workers на Rust и Python по-прежнему делегируются Wrangler.

Что будет с Wrangler?

Пока Wrangler продолжает работать, но срок его жизни уже определён. После окончания открытой беты cf Cloudflare планирует выпустить последнюю мажорную версию Wrangler, которая будет перенаправлять пользователей на cf, и затем поддерживать Wrangler в течение 18 месяцев с этого момента. Cloudflare не объявляла, когда закончится бета, поэтому у этих 18 месяцев пока нет конкретной календарной даты.

То, что Vite становится сборщиком по умолчанию, вписывается в более широкий переход экосистемы Workers на Vite.

Заключение

cf можно установить параллельно с Wrangler: его команды для работы с ресурсами выполняются и в немигрированном проекте, а переход имеет значение только тогда, когда вы переносите на него сборку Worker. Установите официальный пакет, выполните cf zones list | jq ., чтобы своими глазами увидеть вывод, а затем протестируйте cf migrate --dry-run в отдельной ветке некритичного Worker — до того, как закончится бета и начнётся период поддержки Wrangler.

Часто задаваемые вопросы

Как использовать cf с несколькими аккаунтами Cloudflare?

Используйте именованные профили. Выполните cf auth create work, чтобы создать профиль и войти в него, затем cf auth activate work, чтобы привязать его к текущей папке и всем вложенным папкам. Чтобы использовать профиль для одной команды, передайте --profile work, а чтобы увидеть все профили, выполните cf auth list. Переменная окружения CLOUDFLARE_API_TOKEN переопределяет любой профиль и, пока она задана, блокирует команды управления профилями.

Может ли cf читать учётные данные из файла .env?

Да. API-команды могут подхватывать CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID и CLOUDFLARE_ZONE_ID из файла .env в папке, из которой они запускаются. cf смотрит только в .env, но не в .env.local, поэтому убедитесь, что .env указан в .gitignore. Токен, загруженный таким образом, имеет приоритет над любым профилем или сохранённым входом. cf не поддерживает Global API Key, поэтому используйте API-токен с ограниченными правами.

Как мигрировать проект Wrangler внутри монорепозитория?

Передайте в cf migrate путь к конфигурационному файлу, например cf migrate packages/api/wrangler.jsonc --dry-run, а затем выполните ту же команду без --dry-run. Без указания пути cf migrate ожидает, что в текущей директории будет ровно один файл wrangler.json, wrangler.jsonc или wrangler.toml. Команда создаёт файлы рядом с конфигурационным файлом, выбирает бандлер на основе package.json, если не передан флаг --bundler vite или --bundler wrangler, и требует флаг --force, если рабочее дерево Git не чистое.

Что произойдёт, если выполнить cf deploy в проекте Wrangler до миграции?

cf игнорирует wrangler.jsonc и wrangler.toml, поэтому может самостоятельно настроить проект и изменить такие файлы, как package.json. Чтобы откатить изменения, выполните git status, восстановите каждый изменённый файл с помощью git restore и удалите новые файлы, например cloudflare.config.ts, wrangler.config.ts и директорию .cloudflare. Затем выполните cf migrate — эта команда не запускается, пока существует cloudflare.config.ts.