▲

Cloudflare, 전 제품을 아우르는 통합 CLI 구축

 (blog.cloudflare.com)
5P by GN⁺ | ★ favorite | 댓글 2개
  • Cloudflare가 100개 이상의 제품과 약 3,000개의 HTTP API를 하나의 통합 CLI(cf) 로 제공하기 위해 차세대 Wrangler를 재구축 중이며, 현재 기술 프리뷰를 npx cf로 사용 가능
  • 기존 OpenAPI 스키마만으로는 CLI 명령, Workers 바인딩, 에이전트 스킬 등 다양한 인터페이스를 표현할 수 없어 TypeScript 기반의 새로운 스키마 시스템을 도입
  • 에이전트가 CLI를 주요 소비자로 사용하는 추세에 맞춰, get/--force/--json 등 명령어 일관성 규칙과 가드레일을 스키마 수준에서 강제
  • 로컬 개발 시 시뮬레이션된 리소스를 쉽게 탐색할 수 있는 Local Explorer 기능을 오픈 베타로 출시하여 KV, R2, D1 등의 로컬 데이터를 직접 확인 가능
  • Cloudflare 전체 API를 CLI와 로컬 환경에서 동일한 API 형태로 일관되게 제공함으로써, 에이전트와 개발자 모두에게 최적화된 개발 경험 목표

Cloudflare의 API 규모와 에이전트 중심 전환

  • Cloudflare는 100개 이상의 제품과 약 3,000개의 HTTP API 오퍼레이션 보유
  • 에이전트가 API의 주요 소비자로 부상하고 있으며, 개발자들이 코딩 에이전트를 통해 애플리케이션, 에이전트, 플랫폼을 Cloudflare에 빌드 및 배포
  • Cloudflare의 전체 API를 1,000 토큰 미만의 단일 Code Mode MCP 서버로 제공 중이나, CLI 명령, Workers 바인딩, SDK, 설정 파일, Terraform, 개발자 문서, Agent Skills 등 더 많은 인터페이스 커버 필요
  • 기존 Wrangler CLI에는 많은 Cloudflare 제품의 CLI 명령이 누락되어 있었으며, 에이전트는 CLI를 선호하는 경향이 있음

차세대 Wrangler CLI 재구축

  • Wrangler CLI를 Cloudflare 전체를 위한 CLI로 재구축하여 모든 제품에 대한 명령 제공 및 infrastructure-as-code 방식의 통합 설정 가능
  • 기술 프리뷰를 npx cf 또는 npm install -g cf로 설치 가능
  • 현재는 일부 제품만 지원하지만, 내부적으로는 전체 Cloudflare API 표면을 지원하는 버전을 테스트 중
  • 각 제품별 명령을 에이전트와 사람 모두에게 인체공학적인 출력으로 검토 및 조율 중
  • 향후 몇 달에 걸쳐 기존 Wrangler의 장점과 결합 예정

TypeScript 기반 스키마와 코드 생성 파이프라인

  • 기존에는 OpenAPI 스키마를 기반으로 API SDK, Terraform 프로바이더, Code Mode MCP 서버를 자동 생성
  • CLI, Workers 바인딩, wrangler.jsonc 설정, Agent Skills, 대시보드, 문서 업데이트는 여전히 수동 프로세스로 진행되어 오류 발생이 잦고 확장 불가
  • OpenAPI 스키마는 REST API만 기술 가능하여, 로컬 개발과 API 요청을 결합하는 인터랙티브 CLI 명령이나 RPC 기반 Workers 바인딩, Agent Skills과 문서까지 표현 불가
  • Cloudflare 내부에서 TypeScript를 공용어로 사용하는 점에 착안하여, Cap n' Web, Code Mode, Workers 플랫폼의 RPC 시스템 등에서 TypeScript로 API 표현이 더 효과적임을 확인
  • 새로운 TypeScript 스키마를 도입하여 API, CLI 명령과 인수, 인터페이스 생성에 필요한 모든 컨텍스트를 정의
    • TypeScript 타입에 컨벤션, 린팅, 가드레일을 적용한 형태
    • 자체 포맷이므로 필요한 어떤 인터페이스든 유연하게 지원하면서도 OpenAPI 스키마 생성도 가능

에이전트와 CLI의 일관성 및 컨텍스트 엔지니어링

  • 에이전트는 CLI의 일관성을 기대하며, 한 명령이 info를 쓰고 다른 명령이 get을 쓰면 에이전트가 존재하지 않는 명령을 호출하는 문제 발생
  • 수백~수천 명의 엔지니어가 있는 대규모 조직에서 리뷰만으로 일관성을 유지하는 것은 스위스 치즈 모델처럼 구멍 발생 불가피
  • CLI 계층에서만 일관성을 강제하면 CLI, REST API, SDK 간 네이밍이 달라지는 문제가 오히려 악화
  • 스키마 수준에서 규칙과 가드레일을 적용: 항상 get(절대 info 아님), 항상 --force(절대 --skip-confirmations 아님), 항상 --json(절대 --format 아님) 등 모든 명령에서 일관되게 지원
  • Wrangler CLI는 로컬 시뮬레이션 리소스와 원격 리소스 모두에서 작동하는 특수한 구조
    • D1 데이터베이스, R2 스토리지 버킷, KV 네임스페이스 등이 로컬/원격 모두 지원
    • 에이전트가 원격 데이터베이스를 수정한다고 생각하지만 실제로는 로컬 데이터베이스에 레코드를 추가하는 혼란 가능
    • 일관된 기본값과 로컬/원격 여부를 명확히 알려주는 출력으로 에이전트에게 명시적 가이드 제공

Local Explorer — 로컬에서도 원격과 동일한 리소스 탐색

  • Local Explorer를 오픈 베타로 출시, Wrangler CLI와 Cloudflare Vite 플러그인 모두에서 사용 가능
  • 로컬 개발 시 Worker가 사용하는 시뮬레이션 리소스를 직접 탐색 가능: KV, R2, D1, Durable Objects, Workflows
  • Cloudflare API와 대시보드에서 할 수 있는 동일한 작업을 완전히 로컬 환경에서 동일한 API 구조로 수행
  • Cloudflare는 수년간 완전한 로컬 개발에 투자해 왔으며, D1 같은 호스팅 서버리스 데이터베이스도 별도 설정이나 도구 없이 바인딩을 통해 완전히 로컬에서 실행 가능
    • Miniflare(로컬 개발 플랫폼 에뮬레이터)가 프로덕션과 동일한 API를 제공하고 로컬 SQLite 데이터베이스를 사용
    • 네트워크 접근 없이 빠르게 테스트 작성·실행이 가능하며 오프라인에서도 동작
  • 기존에는 로컬에 어떤 데이터가 저장되었는지 확인하려면 .wrangler/state 디렉토리를 리버스 엔지니어링하거나 서드파티 도구를 설치해야 했음
  • Wrangler CLI 또는 Cloudflare Vite 플러그인으로 앱 실행 시 Local Explorer 열기 프롬프트가 표시되며 키보드 단축키 e로 접근
    • 현재 Worker에 연결된 바인딩과 해당 데이터를 확인할 수 있는 로컬 인터페이스 제공
  • 에이전트를 사용한 빌드 시 에이전트가 데이터를 어떻게 다루는지 파악하는 데 유용하며, 스키마 검증, 테스트 레코드 시딩, DROP TABLE 초기화 등이 가능
  • 로컬 데이터만 수정하는 Cloudflare API의 미러를 제공하여, 로컬 리소스를 원격과 동일한 API로 접근
    • 로컬과 원격의 API 형태가 동일하므로 CLI에서 --local 플래그를 전달하면 로컬 미러 API로 요청이 전환되어 그대로 동작
  • 로컬 API는 /cdn-cgi/explorer/api 경로에서 접근 가능하며, 에이전트가 이 주소를 통해 OpenAPI 스펙을 발견하고 로컬 리소스를 관리 가능

피드백 요청 및 향후 계획

  • 차세대 CLI 기술 프리뷰를 npx cf 또는 npm install -g cf로 사용 가능
  • 현재 기술 프리뷰의 기능뿐 아니라, Cloudflare 전체 플랫폼을 위한 CLI에서 무엇을 원하는지 피드백 요청
    • 대시보드에서 여러 번 클릭해야 하지만 한 줄 CLI 명령으로 원하는 작업
    • wrangler.jsonc에서 설정하고 싶은 항목(예: DNS 레코드, 캐시 규칙)
    • 에이전트가 막히는 지점과 CLI에서 제공되기를 바라는 명령
  • Cloudflare Developers Discord에서 피드백 접수 중

함께 보면 좋은 글 β

▲
eoeoe   [-]

FTS 테이블 설정해둔 D1 데이터베이스 내보내기 시도할때 발생하는 오류좀 같이 고쳐줬으면 좋겠네요.
wrangler 쓸때 제일 불편하거든요

답변달기
▲
GN⁺   [-]
Hacker News 의견들

  • Wrangler CLI가 로컬 개발 중 필요한 API 토큰 권한을 미리 보여주면 좋겠음
    배포 전에 어떤 권한이 필요한지 명확히 알 수 있고, cf permissions check 같은 명령으로 누락되거나 불필요한 권한을 확인할 수 있으면 이상적임

    • 완전 공감함. ChatGPT가 처음에 권한을 잘못 설정하면 결국 몇 시간 동안 문서를 뒤지거나 토큰 조합을 시도해야 함
    • 이런 기능을 하는 doctor 명령어가 있으면 정말 편리함. 더 많은 서비스가 이런 걸 제공했으면 함
    • 예전에 오타로 토큰을 잘못 설정한 적이 있는데, 이런 기능이 있었다면 큰 도움이 되었을 것임
    • 더 나아가면, CLI가 자동으로 키를 생성해주는 기능도 좋을 것 같음
    • 결국 핵심은 API의 발견 가능성(discoverability) 을 높이는 것이라 생각함
      GraphQL은 HATEOAS 원칙을 잘 따르기 때문에 LLM이 API를 탐색하기에 유리함
      문서 버전이 맞지 않아 생기는 문제보다, API 자체가 스스로 기능을 드러내는 구조가 훨씬 낫다고 봄

  • 리소스 그룹 단위로 권한 제어를 먼저 추가해줬으면 함
    지금은 zone(도메인) 기반 권한만 있어서, zone에 속하지 않는 worker 같은 리소스는 낮은 권한으로도 코드가 교체되거나 삭제될 수 있음
    GitHub Enterprise처럼 super account + sub account 구조를 지원하면 더 좋겠음. 예: ACME Corp / ACME Corp (Prod)

    • 혹시 이게 Cloudflare Organization 기능과 같은 개념인지 궁금함
    • 도메인을 공유하지 못하더라도 superaccount + subaccount 구조는 정말 유용할 것 같음
    • worker가 zone 기반이 아니라서 활용도가 떨어진다는 점에 동의함

  • 훌륭한 글이라 영감을 받았음. 다만 TypeSpec이 언급되지 않은 게 의외임
    TypeScript 스타일의 스키마 언어로, “OpenAPI가 진짜 잘 만들어졌다면 이런 느낌일 것”이라 설명하곤 함
    아마 자체 구현이 더 단순하고 유연하다고 판단했을 듯함. 요즘은 agent 덕분에 BYO 비용도 많이 줄었음

    • TypeSpec을 정말 좋아함. OpenAPI 작성이 훨씬 쉬워짐
      하지만 요즘은 aep.dev 스타일 API를 선호함. 일관된 패턴 덕분에 aepcli를 바로 쓰거나 직접 만들기 쉬움
      Terraform도 별도 provider 없이 바로 작동함
    • OpenAPI의 어떤 부분을 개선한 건지 궁금함

  • 요즘 AI agent 중심의 CLI-first 설계가 흥미로움
    우리도 개발자 도구를 만들 때 CLI와 API를 먼저 만들고, 대시보드는 나중에 붙였음
    위에서 언급된 cf permissions check 아이디어가 특히 좋음
    agent는 CLI 사용은 잘하지만 에러 원인 진단은 서툼.
    “scope X 누락, cf token add --scope X 실행” 같은 명확한 에러 메시지가 훨씬 중요함

  • npx cf로 기술 프리뷰를 바로 써볼 수 있다는데, 몇 가지 궁금한 점이 있음
    오픈소스인지, 그리고 Node.js 없이 단일 바이너리 형태로 제공될 계획이 있는지 알고 싶음.
    혹시 최근 인수한 Bun 같은 걸 활용할 수도 있을까?

    • 나도 리포지토리를 못 찾았지만, npm 패키지가 MIT 라이선스이고 소스맵이 포함되어 있어서 곧 공개될 것 같음

  • 장기 토큰은 피했으면 함.
    대신 CLI에서 짧은 수명의 제한된 토큰을 쉽게 만들고, 파일로 관리하거나 자동 갱신할 수 있으면 좋겠음
    또 다른 방법으로는 proxy 모드를 두어, 특정 도메인이나 버킷에만 접근 권한을 위임하는 구조도 괜찮을 듯함

    • GitLab처럼 SSH 서버를 통해 짧은 수명의 PAT를 한 번에 생성하는 방식이 마음에 듦

  • 아이러니하게도 AI agent 시대가 오면서 다시 CLI 중심 개발로 돌아가고 있음
    Cloudflare 캐시를 지울 때마다 웹 UI에서 여러 단계를 클릭해야 하는데, 그냥 OpenClaw agent에게 명령만 하면 좋겠음

    • 굳이 OpenClaw를 쓸 필요가 없음. CLI 명령을 직접 호출하면 됨. 그게 CLI의 본질임

  • Wrangler의 인증 방식은 OAuth(전체 권한)와 대시보드에서 수동 생성한 정적 토큰 두 가지뿐임
    하지만 사람과 AI agent가 서로 다른 권한 경계를 가져야 하는 경우엔 맞지 않음
    CLI에서 직접 scoped, short-lived 토큰을 만들 수 있으면 좋겠음
    GitHub issue #13042에서도 논의 중임.
    토큰은 리소스 타입뿐 아니라 리소스 ID와 액션 단위로 세분화되어야 함

  • 4월 1일에 Cloudflare가 EmDash를 x402 지원과 함께 공개했는데, 이제는 CLI에 집중하는 듯함
    Cloudflare가 인간이 아닌 agent를 주요 사용자로 삼는 개발자 생태계를 조용히 재구축 중인 것 같음

  • TypeScript 스키마로 API, CLI 명령, 인자, 컨텍스트를 정의했다는데,
    왜 그 도구나 프레임워크가 여기서 소개되지 않았는지 궁금함
    혹시 위에서 언급된 TypeSpec과 유사한 구조인지 알고 싶음

답변달기