🔥 Cloudflare `cf` CLI와 Local Explorer: Wrangler를 다시 짓는 이유

#Cloudflare#Wrangler#CLI#에이전트#로컬 개발

1103자

14분

강의 목차

무슨 일이 벌어지고 있나
로컬 개발의 블랙박스를 여는 Local Explorer
에이전트는 일관성을 기대한다
뒷편의 기계, TypeScript 스키마
Miniflare에서 이어지는 로컬 개발의 긴 흐름
Agents Week 2026 안에서의 위치
내가 생각하는 것
참고 자료

Building a CLI for all of Cloudflare 발표 이미지
출처: Cloudflare Blog

오늘 Cloudflare 블로그에서 "Building a CLI for all of Cloudflare"라는 제목을 보고 커피를 한 모금 삼킨 채 멈췄다. Wrangler가 뭔가 바뀐다는 얘기는 종종 들어왔지만, 이번엔 결이 조금 달랐다. npx cf 한 줄로 Cloudflare 전체 플랫폼을 다룰 수 있는 CLI를 새로 짓고 있다고 한다. 그것도 사람이 아니라 에이전트를 먼저 염두에 두고.

무슨 일이 벌어지고 있나

Cloudflare는 100개가 넘는 제품과 약 3,000개의 HTTP API 오퍼레이션을 가지고 있다. 이 규모에서 CLI를 일관되게 유지하는 건 쉽지 않다. 어떤 명령은 info, 다른 명령은 get, 세 번째는 describe라면 사람도 헷갈리고 에이전트는 더 쉽게 엇나간다.

그래서 Cloudflare가 Wrangler를 새로 짓기 시작했다. 지금의 Wrangler는 Workers 중심으로 자라났고, 아직 상당수의 Cloudflare 제품은 CLI로 다룰 수 없다. 새 버전은 이름도 단순하게 cf다. 설치는 이렇게 한다.

bash

npx cf
# 또는 전역 설치
npm install -g cf

bash

npx cf
# 또는 전역 설치
npm install -g cf

오늘 공개된 건 기술 프리뷰라 아직 소수 제품만 지원한다. 다만 내부에서는 Cloudflare 전체 API 표면을 지원하는 버전을 이미 테스트하고 있고, 몇 달 안에 지금의 Wrangler와 합쳐 내놓을 계획이라고 한다.

같은 포스트에서 Local Explorer라는 기능도 오픈 베타로 공개됐다. Wrangler와 Cloudflare Vite 플러그인 양쪽에서 쓸 수 있다.

로컬 개발의 블랙박스를 여는 Local Explorer

Local Explorer가 해결하려는 건 오래된 불편함이다. 로컬 개발을 할 때 내 Worker가 어떤 바인딩에 연결돼 있고 그 안에 어떤 데이터가 들어있는지 보려면, 지금까지는 .wrangler/state 디렉터리를 뒤지거나 서드파티 도구를 설치해야 했다. D1에 INSERT를 했는데 정말 들어갔는지 궁금하면 매번 SQL을 짜서 확인하는 식이었다.

Local Explorer는 Wrangler CLI나 Vite 플러그인으로 앱을 띄우면 e 단축키로 바로 열린다. 연결된 바인딩 목록과 그 안의 데이터를 브라우저처럼 둘러볼 수 있다. 지원 범위도 꽤 넓다.

KV 네임스페이스
R2 버킷
D1 데이터베이스
Durable Objects
Workflows

Local Explorer 인터페이스 스크린샷
출처: Cloudflare Blog

스키마를 확인하거나, 테스트 데이터를 시드하거나, 판을 갈아엎고 DROP TABLE을 한 번 쳐야 할 때 쓰라고 한다. 에이전트가 만진 데이터를 사람이 눈으로 확인하는 창구이기도 하다.

재밌는 건 이게 단순한 UI가 아니라는 점이다. 오늘부터 모든 Wrangler/Vite 플러그인 앱에서 /cdn-cgi/explorer/api에 OpenAPI 스펙이 노출된다. 에이전트에게 이 주소를 넘겨주면 로컬 리소스를 API로 직접 조작할 수 있다. 원격 Cloudflare API와 모양이 같아서, 조만간 나올 cf CLI에 --local 플래그가 붙으면 같은 명령이 로컬 미러에 그대로 꽂힌다.

에이전트는 일관성을 기대한다

포스트에서 가장 오래 눈이 머문 문장은 이거였다. "Agents expect CLIs to be consistent."

한 명령은 info를 쓰고 다른 명령은 get을 쓰면, 사람은 tab 자동완성에 기대면 된다. 그런데 에이전트는 존재하지 않는 명령을 그냥 호출한다. 그러고는 에러 메시지를 읽고 당황한 말투로 사과한다. 대규모 조직에서 코드 리뷰로 이 일관성을 강제하는 건 구멍 숭숭 뚫린 스위스 치즈 같은 방식이라는 지적이 꽂혔다.

그래서 Cloudflare는 스키마 레이어에 규칙을 못 박기 시작했다. 옮겨 보면(verified 2026-04-19):

조회 동사는 항상 get, info 금지
강제 실행은 항상 --force, --skip-confirmations 같은 변형 금지
출력 포맷은 항상 --json 지원, --format 같은 변형 금지

Wrangler CLI의 성격상 로컬과 원격 리소스를 모두 다룰 수 있다는 점 때문에 기본값도 중요해진다. 에이전트가 원격 DB에 레코드를 넣었다고 믿는데 실제로는 로컬에 들어간 상태라면, 리모트 바인딩으로 개발 중인 개발자는 왜 자기가 방금 조회한 값이 안 보이는지 한참 헤매게 된다. 그래서 명령 출력에 로컬인지 원격인지를 명시적으로 찍어주는 것도 이번 작업의 일부다.

뒷편의 기계, TypeScript 스키마

사실 이번 포스트에서 내게 더 흥미로웠던 건 CLI 자체보다 그걸 만들기 위해 먼저 지은 "기계"였다.

Cloudflare는 예전부터 OpenAPI 스키마로부터 SDK, Terraform 프로바이더, Code Mode MCP 서버를 생성해 왔다. 문제는 OpenAPI로 잘 표현되지 않는 영역이 있다는 점이었다. 여러 단계를 조합하는 인터랙티브 CLI, RPC로 표현되는 Workers 바인딩, Agent Skills, 문서 같은 것들이 그렇다.

TypeScript 스키마에서 여러 인터페이스로 코드가 생성되는 파이프라인 다이어그램
출처: Cloudflare Blog

그래서 Cloudflare는 TypeScript 기반의 자체 스키마를 새로 정의했다. 포스트 표현을 그대로 옮기면, "API, CLI 명령과 인자, 그리고 모든 인터페이스 생성에 필요한 문맥을 한자리에서 정의"할 수 있는 스키마다. 관례와 린팅, 가드레일로 일관성을 강제하면서 필요하면 OpenAPI도 뽑아낼 수 있게 설계했다.

이 방향은 Cloudflare가 최근에 꾸준히 밀고 있는 흐름과 맞닿아 있다. Cap'n Web은 JSON 기반의 JavaScript 네이티브 RPC고, Code Mode MCP는 같은 아이디어를 MCP에 적용해 Cloudflare API 전체를 약 1,000 토큰 안에 에이전트에게 노출한다. 기존 MCP 대비 입력 토큰을 99.9% 줄였다고 한다(verified 2026-04-19). "TypeScript가 잘 돼 있으니까 API도 TypeScript로 표현하는 게 제일 잘 먹히더라"는 관찰이 이번 CLI 재설계의 뿌리처럼 읽힌다.

Miniflare에서 이어지는 로컬 개발의 긴 흐름

Local Explorer만 떼놓고 보면 "로컬 대시보드 하나 만든 거네"로 끝날 수 있다. 그런데 이 기능이 왜 지금 나왔는지는 Miniflare의 역사를 같이 보면 더 선명해진다.

Cloudflare는 몇 년 전부터 "로컬이 원격과 똑같이 동작해야 한다"는 원칙을 밀어왔다. Miniflare는 Workers 런타임 workerd를 그대로 써서 같은 API 모양을 로컬에서 재현한다. D1은 호스팅 서버리스 DB지만, 로컬에서는 SQLite로 돌아가며 바인딩만 동일하게 맞춘다. 덕분에 네트워크 없이 빠르게 테스트를 돌리고, 비행기 안에서도 Worker를 짤 수 있다.

Local Explorer는 그 원칙을 한 겹 더 밀어 올렸다. 로컬 리소스가 원격과 API까지 똑같이 생기도록 맞추는 것이다. /cdn-cgi/explorer/api 엔드포인트는 단순히 UI용이 아니라 "원격 Cloudflare API의 로컬 미러"를 지향한다. 이 설계가 굳어지면, cf CLI는 로컬과 원격을 플래그 하나로 전환하는 도구가 된다.

Agents Week 2026 안에서의 위치

이번 발표는 Agents Week 2026(4월 13~17일) 기간 중 하나다. 같은 주에 Cloudflare는 에이전트를 위한 샌드박스 GA, Durable Object Facets, Agent Memory, Artifacts 같은 걸 한꺼번에 쏟아냈다. 이 맥락에서 cf CLI와 Local Explorer를 보면, 개별 기능보다 "에이전트를 1급 고객으로 보고 플랫폼을 다시 짜는" 큰 그림의 한 조각으로 읽힌다.

개인적으로는 이 방향이 맞다고 생각한다. 요즘 내 코딩의 상당 부분이 에이전트에게 명령을 내리는 쪽으로 흘러가고 있고, 에이전트가 자주 쓰는 인터페이스가 CLI다. 그런데 CLI들은 대체로 사람을 위해 조금씩 다르게 자라 왔다. info, describe, show, list -v가 섞여 있는 세계에서 에이전트는 존재하지 않는 명령을 호출하고 사과한다. 스키마 레이어에서 규칙을 박는 시도는 이 문제를 정면으로 본다.

내가 생각하는 것

솔직히 처음엔 "또 CLI 이름 바꾸는 건가" 싶었다. Wrangler에서 cf로.

포스트를 다 읽고 나니 생각이 조금 바뀌었다. 지금까지 Wrangler는 Workers를 쓰는 사람들의 도구였다. cf는 Cloudflare 전체 플랫폼을 쓰려는 사람, 그리고 에이전트의 도구로 설계됐다. 이름을 두 글자로 줄인 것도 "매번 타이핑하는" 에이전트의 토큰 효율과 무관해 보이지 않는다.

아직 확신은 없다. 기술 프리뷰라 지원 제품이 적고, Wrangler와 합쳐지기 전까지는 혼란이 있을 것 같다. cf라는 이름이 너무 일반적이라 자동완성에서 다른 도구와 꼬일 가능성도 떠오른다.

그래도 이번 주말에는 한 번 띄워볼 생각이다. npx cf로 시작해서, Local Explorer를 e 단축키로 열어 D1에 쌓인 찌꺼기 데이터를 직접 털어내 보는 정도. 그리고 /cdn-cgi/explorer/api에 Claude Code를 붙여서 로컬 D1 스키마를 대화로 수정할 수 있는지 확인해 보고 싶다. 그게 된다면 "로컬 개발"이라는 단어의 의미 자체가 지금과 조금 달라질 것 같다.