Cloudflare 전체를 위한 CLI 구축

본 콘텐츠는 사용자의 편의를 고려해 자동 기계 번역 서비스를 사용하였습니다. 영어 원문과 다른 오류, 누락 또는 해석상의 미묘한 차이가 포함될 수 있습니다. 필요하시다면 영어 원문을 참조하시기를 바랍니다.

Cloudflare에는 방대한 API 노출 영역이 있습니다. Cloudflare는 100가지 이상의 제품과 거의 3,000가지의 HTTP API 작업을 보유하고 있습니다.

Cloudflare API의 주요 고객이 되는 에이전트가 늘어나고 있습니다. 개발자는 코딩 에이전트를 가져와 애플리케이션, 에이전트 및 플랫폼을 구축하고 Cloudflare에 배포하며, 계정을 구성하고, 분석 및 로그를 위해 Cloudflare API를 쿼리합니다.

우리는 에이전트가 필요로 하는 모든 방식으로 모든 Cloudflare 제품을 이용할 수 있게 만들고자 합니다. 예를 들어, 저희는 이제 Cloudflare의 전체 API를 1,000개 미만의 토큰을 사용하는 단일 코드 모드 MCP 서버에서 사용할 수 있도록 했습니다. 하지만 CLI 명령으로 다루어야 할 표면 영역이 훨씬 더 많습니다. Workers 바인딩 — 로컬 개발 및 테스트용 API 포함. 다양한 언어의 SDK. 구성 파일입니다. Terraform. 개발자 문서. API 문서 와 OpenAPI 스키마. 상담원 기술.

현재는 많은 제품이 이러한 인터페이스 모두에서 사용 가능한 것은 아닙니다. Cloudflare의 CLI인 Wrangler의 경우 특히 그렇습니다. 많은 Cloudflare 제품에는 Wrangler에 CLI 명령이 없습니다. 그리고 상담원은 CLI를 좋아합니다.

그래서 우리는 Wrangler CLI를 모든 Cloudflare를 위한 CLI로 재구축하고 있습니다. 이 제품은 모든 Cloudflare 제품에 대한 명령을 제공하며, 코드형 인프라를 사용하여 함께 구성할 수 있습니다.

오늘 우리는 기술 미리 보기로 다음 Wrangler 버전이 어떤 모습으로 보일지 초기 버전을 공유합니다. 아직 초기 단계이지만, 공개적으로 작업할 때 가장 좋은 피드백을 받고 있습니다.

오늘 npx cf를 실행하여 기술 미리 보기를 시험해 볼 수 있습니다. 또는 npm install -g cf를 실행하여 전역적으로 설치할 수 있습니다.

현재 cf는 Cloudflare 제품의 일부에 대해서만 명령을 제공합니다. 이미 Cloudflare API 표면 전체를 지원하는 cf 버전을 테스트하고 있으며, 에이전트와 사람 모두가 인체 공학적으로 사용할 수 있도록 의도적으로 각 제품의 명령을 검토하고 조정하겠습니다. 명확히 하자면, 이번 기술 미리 보기는 향후 Wrangler CLI의 일부일 뿐입니다. 앞으로 몇 달 동안 여러분이 알고 사랑하는 Wrangler의 일부를 통합할 예정입니다.

Cloudflare에서는 제품 개발의 빠른 속도에 발맞추어 이를 구축하기 위해 명령, 구성, 바인딩 API 등을 생성할 수 있는 새로운 시스템을 생성해야 했습니다.

Cloudflare API용 OpenAPI 스키마를 기반으로 Cloudflare API SDK, Terraform 공급자, 코드 모드 MCP 서버 를 이미 생성했습니다. 하지만 CLI, Workers 바인딩, wrangler.jsonc 구성, 에이전트 기술, 대시보드, 문서를 업데이트하는 작업은 여전히 수동으로 진행됩니다. 이 작업은 이미 오류가 발생하기 쉽고, 반복 작업이 너무 많이 필요했으며, 다음 CLI 버전에서는 전체 Cloudflare API를 지원하기 위해 확장될 수 없었습니다.

이를 위해서는 OpenAPI 스키마로 표현할 수 있는 것 이상의 것이 필요했습니다. OpenAPI 스키마는 REST API를 설명하지만, 로컬 개발과 API 요청을 결합하는 여러 작업을 포함하는 대화형 CLI 명령, RPC API로 표현되는 Workers 바인딩, 이 모든 것을 하나로 묶는 에이전트 기술, 문서가 있습니다.

우리는 Cloudflare에서 많은 TypeScript를 작성합니다. 이는 소프트웨어 엔지니어링 분야에서 통용되는 용어입니다. 저희는 Cap n’ Web, 코드 모드, Workers 플랫폼에 내장된 RPC 시스템 과 마찬가지로 API를 TypeScript로 표현하는 것이 더 잘 작동한다는 사실을 계속 발견하고 있습니다.

그래서 Cloudflare에서는 API, CLI 명령 및 인수, 그리고 인터페이스를 생성하는 데 필요한 컨텍스트를 정의할 수 있는 새로운 TypeScript 스키마를 도입했습니다. 스키마 형식은 일관성을 보장하기 위해 규칙, 린팅, 가드레일이 포함된 TypeScript 유형의 집합에 불과합니다. 하지만 Cloudflare의 자체 형식이므로 현재나 미래에 필요한 모든 인터페이스를 지원하도록 쉽게 조정할 수 있으며 또한 OpenAPI 스키마를 생성할 수도 있습니다.

지금까지 우리는 이 계층에 가장 중점을 두었으며, 즉 우리가 여러 해 동안 제공하고자 했던 CLI 및 기타 인터페이스의 구축을 이제 시작할 수 있는 필요한 시스템을 구축하는 것이었습니다. 이렇게 하면 Cloudflare에서 표준화하고 에이전트를 위해 더 개선할 수 있는 것, 특히 CLI 컨텍스트 엔지니어링에 대해 더 큰 꿈을 꾸기 시작할 수 있습니다.

에이전트는 CLI에 일관성을 기대합니다. 한 명령에서 리소스에 대한 정보를 가져오기 위한 구문으로 <command> info 를 사용하고 다른 명령에서 <command> get을 사용하는 경우, 에이전트는 하나를 기대하고 다른 것에 대해 존재하지 않는 명령을 호출합니다. 수백 또는 수천 명이 있고 많은 제품을 사용하는 대규모 엔지니어링 조직에서 검토를 통해 일관성을 수동으로 적용하는 것은 정말 어려운 일입니다. 이를 CLI 계층에서 적용할 수도 있지만, CLI, REST API, SDK 간에 이름이 다르면 문제가 더 악화될 수 있습니다.

가장 먼저 한 일 중 하나는 스키마 계층에서 시행할 규칙과 가드레일을 만들기 시작한 것입니다. 항상 get이고, info는 아닙니다. 항상 --force를 사용하고, 절대 --skip-confirmations를 사용하지 않습니다. 항상 --json을 사용하고, 절대 --format을 사용하지 않으며, 모든 명령에서 항상 지원됩니다. 

Wrangler CLI도 상당히 독특해서, 시뮬레이션된 로컬 리소스 또는 D1 데이터베이스, R2 스토리지 버킷, KV 네임스페이스와 같은 원격 리소스 모두에서 작동할 수 있는 명령과 구성을 제공합니다. 즉, 일관된 기본값이 더욱 중요합니다. 에이전트가 원격 데이터베이스를 수정한다고 생각하지만, 실제로는 로컬 데이터베이스에 레코드를 추가하고, 개발자가 원격 바인딩을 사용하여 원격 데이터베이스에 로컬로 개발하는 경우, 에이전트는 새로 추가된 레코드가 표시되지 않는 이유를 이해하지 못합니다. 로컬 개발 서버에 요청하면 명령이 원격 또는 로컬 리소스에 적용되는지 여부를 명확하게 나타내는 출력과 함께 일관된 기본값을 통해 에이전트는 명시적인 지침을 받을 수 있습니다.

오늘 Cloudflare는 Wrangler와 Cloudflare Vite 플러그인 모두에서 오픈 베타로 이용할 수 있는 새로운 기능인 Local Explorer도 출시합니다.

Local Explorer를 사용하면 KV, R2, D1, Durable Objects, Workflows등 로컬에서 개발할 때 Worker가 사용하는 시뮬레이션 리소스를 살펴볼 수 있습니다. Cloudflare API와 Dashboard를 통해 이들 각각의 작업을 수행할 때와 동일한 작업을 동일한 기본 API 구조에 따라 전적으로 로컬에서 수행할 수 있습니다.

수년간 우리는 Cloudflare Workers뿐만 아니라 전체 플랫폼을 위해 완전한 로컬 개발에 전념해 왔습니다. D1을 사용하면 D1이 호스팅된 서버리스 데이터베이스 제품이더라도 추가 설정이나 도구 없이 전적으로 로컬에서 바인딩을 통해 데이터베이스를 실행하고 바인딩을 통해 통신할 수 있습니다. 로컬 개발 플랫폼 에뮬레이터인 Miniflare를 통해 Workers 런타임은 로컬 개발에서도 프로덕션과 정확히 동일한 API를 제공하며, 로컬 SQLite 데이터베이스를 사용해 동일한 기능을 제공합니다. 따라서 네트워크에 액세스할 필요 없이 빠르게 실행되는 테스트를 쉽게 작성하고 실행하며 오프라인으로 작업할 수 있습니다.

하지만 지금까지는 로컬에 저장된 데이터를 확인하려면 역설계하고 .wrangler/state 의 내용을 검사해야 했습니다. 디렉터리 또는 타사 도구를 설치합니다.

이제 Wrangler CLI 또는 Cloudflare Vite 플러그인으로 앱을 실행할 때마다 로컬 익스플로러(키보드 단축키 e)를 열라는 메시지가 나타납니다. 이를 통해 간단한 로컬 인터페이스를 통해 Worker가 현재 어떤 바인딩을 연결했는지, 어떤 데이터가 이에 저장되어 있는지 확인할 수 있습니다.

에이전트를 사용하여 구축하는 경우 로컬 익스플로러를 사용하면 에이전트가 데이터로 무엇을 하는지 이해할 수 있으므로 로컬 개발 주기가 훨씬 더 대화형이 됩니다. 스키마를 확인하거나, 일부 테스트 레코드를 시드해야 하거나, 다시 시작하여 DROP TABLE해야 할 때는 언제든지 Local Explorer를 사용할 수 있습니다.

여기에서 Cloudflare의 목표는 로컬 데이터만 수정하는 Cloudflare APIs를 모방한 기능을 제공하여, 원격으로 사용하는 것과 동일한 APIs를 통해 모든 로컬 리소스를 사용할 수 있도록 하는 것입니다. 또한 로컬과 원격에서 API 형태가 일치하게 함으로써, CLI의 다음 버전에서 CLI 명령을 실행하고 --local 플래그를 전달하면 명령이 그대로 작동합니다. 유일한 차이점은 명령이 대신 Cloudflare API의 이 로컬 미러로 요청을 생성한다는 것입니다.

오늘부터 이 API는 모든 Wrangler 또는 Vite 플러그인으로 구동되는 애플리케이션의 /cdn-cgi/explorer/api 에서 사용할 수 있습니다. 에이전트가 이 주소로 가리키게 하면 OpenAPI 사양을 찾도록 하여 에이전트와 대화하는 것만으로도 로컬 리소스를 관리할 수 있습니다.

기본 구성 작업을 완료했으니 이제 Wrangler의 가장 중요한 부분을 가져와 현재 가능한 기능과 결합하여 Wrangler를 모든 Cloudflare를 사용하는 최고의 CLI로 만들 차례입니다.

npx cf를 실행하여 지금 기술 미리 보기를 시험해 볼 수 있습니다. 또는 npm install -g cf를 실행하여 전역적으로 설치할 수 있습니다.

이 초기 버전에 대한 여러분의 피드백을 기다립니다. 오늘 테크니컬 프리뷰의 결과뿐만 아니라 Cloudflare의 전체 플랫폼에 대한 CLI를 통해 원하는 사항에 대한 피드백도 필요합니다. 한 줄의 CLI 명령만 가능하면서도 지금 Cloudflare 대시보드에서 몇 번만 클릭하면 됩니다. DNS 레코드나 캐시 규칙처럼 wrangler.jsonc에 구성하고 싶은 것. 에이전트가 어느 위치에서 멈췄는지 확인하고, 에이전트를 위해 CLI에서 제공했으면 하는 명령은 무엇인지 파악하십시오.

Cloudflare Developers Discord 에 참여하여 CLI에 가장 먼저 추가하고 싶은 기능을 알려주세요. 곧 더 많은 업데이트가 있을 예정이니 기대해 주세요.

Local Explorer 프로젝트를 시작하는 데 귀중한 기여를 해준 Emily Shen 에게 감사드립니다.