Cloudflare CLI 사용법: cf 설치부터 Worker 마이그레이션까지

실질적인 이점은 명령어가 짧아졌다는 데 있지 않습니다. 연동 작업 자체가 줄어듭니다. 창업자는 대시보드를 뒤지지 않고 계정을 점검할 수 있고, 플랫폼 팀은 에이전트에 기계가 읽을 수 있는 결과를 제공할 수 있습니다. 에이전시는 제품마다 별도의 API 래퍼를 유지하지 않고도 여러 고객 계정의 Cloudflare 작업을 표준화할 수 있습니다.

cf를 쓰기 위해 별도 라이선스를 살 필요는 없습니다. 저장소는 오픈 소스이고, 작은 Worker는 Cloudflare Free 플랜에서 시작할 수 있으며, Workers Paid의 월 최소 요금은 $5입니다. 예산의 반대편에는 Starter+ 티어가 $20,000인 Spacelift 같은 범용 인프라 거버넌스 플랫폼이 있습니다. cf는 이 두 선택지 사이에서 API 연동에 드는 수고를 크게 덜어 줍니다. 하지만 승인 절차, 감사 추적, 세심한 권한 설계까지 없애 주는 것은 아닙니다.

새로운 cf CLI는 정확히 무엇인가

cf는 Cloudflare API 전체를 명령으로 다룰 수 있게 자동 생성된 인터페이스에, Worker 생성·빌드·마이그레이션·배포 같은 작업을 위해 직접 설계한 프로젝트 워크플로를 더한 툴입니다. Wrangler가 Worker를 위한 전문 작업대라면, cf는 Cloudflare라는 건물 전체를 안내하는 디렉터리이자 서비스 데스크에 가깝습니다. 다만 Wrangler가 더 안정적인 작업은 계속 Wrangler로 넘깁니다.

이 차이는 이번 릴리스와 Cloudflare의 4월 13일 기술 프리뷰를 가르는 기준이기도 합니다. 4월 빌드는 일부 제품만 지원했습니다. 9월 오픈 베타에는 API 전체 범위, 기본 JSON 출력, 명령 검색, TypeScript Worker 설정, 그리고 기본 Worker 경로로서의 Vite가 포함됐습니다.

워크플로를 바꾸는 핵심은 다음 4가지입니다.

• API 전체 범위: 자동 생성된 명령은 3,000개가 넘는 작업에 걸쳐 cf <product> [group…] <operation> 형식을 따릅니다.
• 명령 검색: cf cli search에 자연어로 할 일을 입력하면 관련도가 높은 5개 명령을 JSON으로 돌려줍니다. 명령 트리를 외울 필요가 없습니다.
• 기본 출력은 JSON: API 결과가 보기 좋게 정리된 JSON으로 표준 출력에 전달되므로 사람, 스크립트, 코딩 에이전트가 같은 응답을 필터링할 수 있습니다.
• 타입이 적용된 Worker 설정: cloudflare.config.ts 덕분에 에디터와 코딩 에이전트가 TypeScript 피드백을 받을 수 있습니다. 현재는 Workers부터 지원합니다. DNS, zone, 정책을 아우르는 계정 전체 설정은 향후 방향이며, 지금 제공되는 기능은 아닙니다.

Cloudflare CLI 설치, 인증, 읽기 테스트

먼저 읽기 전용 작업부터 실행합니다. 스크립트에 변경 권한을 주기 전에 패키지, 인증 정보, 계정 선택, 명령 검색, JSON 처리 경로가 모두 제대로 동작하는지 확인할 수 있습니다.

공식 패키지는 Node.js 22 이상이 필요합니다. 사람이 터미널에서 사용할 때는 cf auth login이 기본 OAuth 프로필을 관리합니다. CI에서는 권한 범위를 좁힌 CLOUDFLARE_API_TOKEN을 설정합니다. cf는 저장된 OAuth 프로필보다 이 환경 변수를 먼저 확인합니다. 고객사나 회사 계정을 오갈 때는 이름이 있는 프로필을 만들고 각각 다른 디렉터리에 연결할 수 있습니다.

cf cli search에 넘기는 문장은 일반적으로 작성합니다. 도메인, 이메일 주소, 계정 ID, 토큰을 넣지 말고 작업과 리소스 유형만 설명합니다.

node --version
npm i -g cf
cf --version

cf auth login
cf auth whoami

cf cli search "list zones in an account"
cf zones list | jq -e 'type == "array" and all(.[]; has("name") and has("status"))'

현재 이 작업을 검색하면 cf zones list가 첫 번째로 나옵니다. 마지막 줄이 실제 검증 단계입니다. 읽기 전용 API를 호출하고, 결과가 name과 status를 포함한 항목으로 구성된 JSON 배열일 때만 성공으로 종료합니다. 계정이 여러 개라면 --profile로 이름이 있는 프로필을 고르거나 --account-id로 명령 대상을 제한합니다.

토큰을 셸 기록에 직접 붙여 넣으면 안 됩니다. 범위가 제한된 토큰을 CI 프로세스 환경에 두고, 작업에 꼭 필요한 읽기 또는 쓰기 권한만 부여합니다. 개인이 터미널에서 작업할 때는 cf가 선택된 프로필을 갱신할 수 있으므로 OAuth가 더 편한 기본값입니다.

일회용 테스트에서 확인한 범위

9월 29일, 새로 분리한 환경에 설치했을 때 cf v1.0.0-beta.5가 반환됐습니다. 명령 검색은 유효한 5개 항목의 JSON 배열을 돌려줬고, cf init은 타입이 적용된 Worker 프로젝트를 생성했습니다. 새 프로젝트와 마이그레이션한 Vite 픽스처 모두 로컬 빌드에 성공했습니다. 이 환경에는 Cloudflare 테스트 계정 인증 정보가 없었으므로, 인증이 필요한 zone 읽기와 배포는 완료된 테스트에 포함하지 않았습니다.

이 경계는 중요합니다. 로컬 빌드 성공은 프로젝트 경로가 정상이라는 뜻입니다. 토큰에 올바른 프로덕션 권한이 있는지, 실제 배포가 Cloudflare에 도달했는지까지 증명하지는 않습니다.

작은 Worker를 만들고 cf가 생성한 파일 확인하기

cf init은 새 프로젝트 워크플로를 가장 빠르고 깔끔하게 시험하는 방법입니다. 빈 디렉터리에서 실행하면 TypeScript 소스, cloudflare.config.ts, vite.config.ts, 패키지 스크립트, 생성된 Worker 타입이 만들어집니다. 이어서 cf build를 실행하면 Cloudflare Vite Plugin에 빌드를 맡기고 표준화된 Build Output을 생성합니다.

cf init hello-cf --package-manager npm
cd hello-cf
npm run build

# In a copied existing Vite Worker:
cf migrate --dry-run
cf migrate
npm run build

어느 경로를 택하든 완료 후에는 cloudflare.config.ts를 열어 봅니다. 기본 Worker라면 이름, 호환성 날짜, 진입점, 타입이 적용된 바인딩을 포함하는 worker 블록이 있어야 합니다. 텍스트 바인딩은 여러 환경 블록에 복사하는 대신 설정 API를 통해 선언합니다. 여기서 TypeScript의 가치가 드러납니다. 필드 이름을 잘못 입력했을 때 배포 실패가 아니라 에디터 피드백으로 먼저 발견할 수 있습니다.

생성된 Vite 설정은 장식이 아닙니다. 이제 Vite는 cf의 기본 로컬 개발 및 빌드 경로이며, Cloudflare는 프런트엔드와 백엔드 API 모두에 Vite plugin을 권장합니다. 일회용 프로젝트에서는 npm run build가 Vite에 작업을 넘겨 완료됐습니다. 배포는 의도적으로 제외했습니다. 검토와 계정 테스트가 끝나면 문서에 안내된 cf deploy 명령이 기본적으로 빌드와 업로드를 수행합니다.

Wrangler를 계속 써야 하는 경우

cf 설치가 성공했다는 이유만으로 Wrangler를 제거하면 안 됩니다. 올바른 마이그레이션 판단은 프로젝트의 빌드 경로에 달려 있습니다.

기존 Vite Worker에서는 cf migrate로 Wrangler JSON, JSONC, TOML을 cloudflare.config.ts로 변환할 수 있습니다. 이 명령은 Wrangler 설정 옆에서 Cloudflare Vite Plugin을 찾아 Vite 경로를 선택합니다. 플러그인이 선언돼 있지 않으면 현재 베타 릴리스는 Wrangler 번들러를 선택합니다. 실제 프로젝트를 건드리기 전에 dry-run 미리보기를 실행하고, 모든 후속 항목을 읽은 뒤, 복사본이나 변경 사항이 없는 브랜치에서 마이그레이션합니다.

Wrangler의 esbuild 동작에 계속 의존하는 JavaScript Workers라면 cf는 개발과 배포를 Wrangler에 맡깁니다. Rust와 Python Workers도 마찬가지입니다. 이는 마이그레이션 실패가 아니라 호환성을 위한 설계입니다. 팀은 cf를 단일 진입점으로 쓰면서도 검증된 빌더를 작업 경로에 남겨 둘 수 있습니다.

Cloudflare의 지원 일정도 오해하기 쉽습니다. Wrangler 유지보수는 오픈 베타가 끝난 뒤 18개월 동안 이어질 예정이며, 9월 28일 출시일부터 18개월이 아닙니다. 이번 주에 Rust, Python, esbuild 프로젝트를 억지로 Vite로 전환할 이유는 없습니다.

먼저 효과를 볼 7가지 워크플로

초기 활용 사례로는 반복되는 검색과 출력 형식 변환을 줄이면서도 처음부터 광범위한 쓰기 권한을 주지 않는 작업이 가장 좋습니다.

1. 에이전시의 계정 점검 표준화

에이전시 운영자는 고객 디렉터리마다 이름이 있는 OAuth 프로필을 연결하고, 필요한 읽기 명령을 검색한 뒤, 동일한 형태의 JSON을 검토 스크립트로 보낼 수 있습니다. 한 엔지니어는 대시보드를 클릭하고 다른 엔지니어는 별도 curl 명령을 관리하면서 생기는 편차를 줄일 수 있습니다. 특히 DNS, zone, 계정 설정, 보안 검토 등 고객별 작업을 반복할 때 효과가 큽니다.

2. 플랫폼 팀이 코딩 에이전트에 안전한 Cloudflare 인터페이스 제공

플랫폼 책임자는 AGENTS.md에 cf cli search 사용 규칙을 두고, 읽기 명령은 기본 허용하되 변경 작업에는 사람의 승인을 요구할 수 있습니다. 검색 기능은 에이전트가 예전 Wrangler 문법을 추측하지 않게 하고, JSON은 출력을 간결하고 필터링하기 쉽게 만듭니다. 팀이 이미 에이전트에 빌드 상태, 로그, 큐, 계정 리소스 점검을 맡기고 있으며 하나의 예측 가능한 인터페이스를 원할 때 특히 유용합니다.

3. 당직 엔지니어의 장애 상황 정보 수집

장애가 발생하면 운영자는 여러 제품 패널을 돌아다니는 대신 필요한 로그, zone, 규칙 세트, 분석 데이터 읽기 명령을 검색할 수 있습니다. 정확한 명령은 여전히 중요하고 권한도 그대로 적용되지만, 이제 로컬에서 명령을 찾고 곧바로 jq로 응답을 처리할 수 있습니다. Cloudflare Browser Run 같은 작업을 운영하는 팀이라면 실패한 작업에서 주변 계정 상태까지 더 빠르게 확인할 수 있습니다.

4. 창업자가 툴체인 설계 없이 Worker 하나 시작하기

웹훅, 리디렉션 서비스, 소규모 내부 API를 만드는 창업자는 cf init을 실행하고 생성된 Worker와 바인딩을 확인한 뒤, 패키지를 하나씩 고르지 않고 Vite 빌드를 사용할 수 있습니다. 프로젝트는 Workers Free에서 시작할 수 있습니다. 유료 플랜이 필요해지면 현재 최소 요금은 계정당 월 $5입니다. 핵심 가치는 검토 가능한 로컬 결과물까지 빠르게 도달하는 데 있지, 프로덕션 운영이 무료가 된다는 약속에 있지 않습니다.

5. Vite 팀이 앱 재작성 없이 설정 변환하기

Vite 기반 Worker를 운영하는 엔지니어링 팀은 복사본에서 cf migrate --dry-run을 실행하고, 생성된 TypeScript를 검토한 다음, 배포 방식을 바꾸기 전에 빌드할 수 있습니다. 환경 블록의 반복이 늘어난 프로젝트에서 특히 유용합니다. 새 형식은 공통 기반 설정에서 값을 계산할 수 있지만, 팀이 옮겨야 할 것은 단순한 파일 문법이 아니라 기존 동작입니다.

6. 데이터·운영 팀이 Cloudflare 읽기 결과를 보고서에 연결하기

구조화된 결과가 기본적으로 JSON이므로 운영자는 Unicode 표를 스크래핑하지 않고 읽기 결과를 jq, 데이터 웨어하우스 로더, 예약 보고서로 보낼 수 있습니다. 비즈니스 측면의 효과는 좋은 의미로 단순합니다. 출력 어댑터와 깨지기 쉬운 파싱 규칙이 줄어듭니다. 범위가 제한된 읽기 토큰을 사용하고, 명령 출력이 공개 CI 로그에 남지 않게 합니다.

7. Worker 팀이 프로덕션 변경 전 로컬 리소스 점검하기

지원되는 명령은 --local을 받아 로컬 상태를 기반으로 잠시 실행되는 Miniflare 인스턴스와 통신합니다. KV, D1, R2에서 정의된 작업도 포함됩니다. 로컬 대응 기능이 없으면 cf는 조용히 프로덕션으로 넘어가지 않고 오류를 반환합니다. Cloudflare AI Search Worker를 만드는 팀은 이 경계를 이용해 개발 명령이 원격 쓰기로 바뀔 걱정 없이 보조 로컬 데이터를 테스트할 수 있습니다.

cf를 기반으로 만들 만한 제품 2가지

CLI 자체가 곧 제품 기회인 것은 아닙니다. 폭넓은 API를 실제 업무에 쓰려면 여전히 필요한 제어 계층에 기회가 있습니다.

가장 유망한 기회: 에이전시용 Cloudflare 변경 통제

여러 Cloudflare 계정을 관리하는 에이전시나 소규모 플랫폼 팀을 위해 승인과 증적에 집중한 계층을 만듭니다. 사용자가 DNS, zone, WAF, Worker 변경을 제안하면 제품이 cf로 현재 JSON 상태를 수집하고, 사람이 읽기 쉬운 차이를 보여 주며, 승인을 요청합니다. 이후 범위가 제한된 프로필로 변경을 실행하고 결과를 저장합니다.

수요 신호는 크지 않지만 상업성은 있습니다. cloudflare dns management는 미국에서 월간 검색량이 약 170회이고 CPC는 $6이며, 페이지 상단 입찰가는 $3.85에서 $36.64입니다. 범용 인프라 거버넌스에도 실제 예산이 배정됩니다. Spacelift의 Starter+ 가격은 $20,000입니다. Cloudflare 전용 제품은 모든 클라우드를 관리할 필요가 없으므로 더 저렴하고 도입하기 쉽게 만들 수 있습니다.

최소 판매 가능 버전은 DNS와 Worker 변경을 다루는 GitHub app 또는 호스팅형 검토 큐입니다. 프로필 격리, 명령 허용 목록, 변경 전후 JSON, 그리고 기반 API가 지원하는 경우 원클릭 롤백을 포함합니다. 문제는 방어력입니다. 명령 범위는 이미 cf가 제공하므로, 차별화해야 할 부분은 정책, 증적, 권한, 에이전시 워크플로입니다. 단순한 GUI 래퍼는 빠르게 복제될 수 있습니다.

유용한 기능: Worker 마이그레이션 준비도

저장소가 네이티브 Vite, Wrangler 기반 esbuild, Python, Rust 가운데 어디에 속하는지 분류하고, 안전한 마이그레이션 미리보기를 실행한 뒤, 후속 항목을 pull request 체크리스트로 바꿔 주는 스캐너를 만듭니다. 구매자는 작은 프로젝트 하나를 옮기는 개인 개발자가 아니라 여러 Worker를 보유한 팀입니다.

이 기능만으로 회사를 세우기에는 수요가 너무 작습니다. cloudflare worker deployment의 미국 월간 검색량은 약 10회에 불과하지만, 검색 의도는 거래형입니다. 합리적인 MVP는 Cloudflare 운영 제품이나 마이그레이션 서비스의 유료 기능입니다. 저장소 스캔, cf migrate --dry-run, 빌드 검증, 명확한 Wrangler 대체 경로 보고서를 제공합니다. 문제는 베타 기간의 릴리스 변동입니다. 스캐너가 cf와 Cloudflare Vite Plugin 버전을 면밀히 따라가지 못하면 프로젝트보다 조언이 더 빨리 낡습니다.

한계와 현실적인 선택

지금 cf가 잘 맞는 용도는 명령 검색, JSON 중심의 계정 읽기, 새 Vite Workers, 신중한 마이그레이션 시험입니다. cf가 작업을 Wrangler에 맡기는 프로젝트에서는 Wrangler를 계속 설치해 두고, 프로덕션 쓰기는 명시적인 권한 범위와 검토 절차 뒤에 둡니다.

현재 오픈 베타에서 cloudflare.config.ts는 계정 전체를 관리하는 단일 기준 정보가 아닙니다. 시작점은 Workers입니다. 또한 Cloudflare API 작업을 모두 안전한 비즈니스 워크플로로 바꿔 주지도 않습니다. 전체 API를 다룰 수 있다는 것은 토큰이 접근 가능한 범위도 넓어진다는 뜻이므로, 최소 권한과 명령 검토는 덜 중요한 것이 아니라 더 중요해집니다.

로컬 옵션의 범위는 의도적으로 제한돼 있습니다. 지원되는 KV, D1, R2, Durable Object, Workflow 작업은 로컬 상태를 사용할 수 있지만, 로컬 탐색 기능에 대응 항목이 없는 작업은 오류를 냅니다. 안전 측면에서는 바람직한 속성이지만, --local이 Cloudflare 전체를 재현하는 범용 오프라인 미러라는 뜻은 아닙니다.

마지막으로 베타 릴리스는 빠르게 바뀝니다. 팀 작업에서는 프로젝트 의존성에 cf 버전을 고정하고, 생성된 설정을 검토하며, CI가 프로젝트 로컬 버전을 사용하게 합니다. 전역 설치는 명령을 탐색할 때 편리하지만, 협업자 모두가 같은 동작을 얻으려면 버전을 고정해야 합니다.

팀에 맞는 안전한 Cloudflare 자동화 경로를 설계하고 구축하려면 AI production systems를 확인하세요.