CLI 환경에서 Cloudflare Wrangler 로그인 및 API 토큰 설정 상세 설명서

detail-manual • 2026-07-06 PM7:49:33 (GMT+9) • 👀 2 •

#Wrangler #Cloudflare #CLI #API Token #Login

🔑 CLI 환경에서 Cloudflare Wrangler 로그인 및 API 토큰 설정 상세 설명서

본 프로젝트는 단일 명령어로 Cloudflare의 데이터베이스, 저장소, 빌드 파이프라인을 구축해주는 자동화 셋업 스크립트를 제공합니다.

이 스크립트는 내부적으로 Cloudflare의 명령행 도구인 wrangler CLI를 사용합니다. 일반적인 로컬 개발 PC 환경에서는 웹 브라우저를 통한 대화형 로그인(npx wrangler login)이 즉시 실행되지만, **브라우저를 열 수 없는 완전한 CLI 환경(예: 원격 SSH Linux 서버, headless 가상 머신, CI/CD 배포 파이프라인)**에서는 로그인 세션을 대화형으로 수립할 수 없는 제약이 발생합니다.

본 매뉴얼은 이러한 환경 제약을 극복하기 위해 Cloudflare API 토큰을 활용하여 Wrangler의 비대화형 인증 세션을 안전하게 구축하는 방법을 상세히 안내합니다.

📂 1. 도메인 설정 전후에 따른 필수 최소 권한 구분

API 토큰을 발급받기 전에, 현재 본인의 인프라 배포 단계를 파악하는 것이 중요합니다. 불필요한 보안 위협을 낮추기 위해 도메인 연결 상태에 따라 필요한 권한을 분리하여 적용합니다.

🔌 1-1. 초기 배포 단계 (자체 도메인 연동 전)

프로젝트를 처음 배포하여 Cloudflare Pages가 제공하는 기본 도메인인 *.pages.dev 주소만 사용할 경우, 브라우저를 통해 연동하는 일반 로그인 상태와 동일하게 Zone(도메인) 수준의 어떠한 권한도 필요치 않습니다. 오직 계정(Account) 수준의 핵심 리소스 권한만으로 셋업 스크립트 실행과 D1 마이그레이션이 문제없이 가동됩니다.

필수 최소 권한 목록:
- D1 — Edit (D1 DB 생성, 스키마 마이그레이션 실행 및 쿼리 작동용)
- Workers KV Storage — Edit (블로그 미디어 업로드용 KV 네임스페이스 제어용)
- Cloudflare Pages — Edit (모노레포의 블로그 및 어드민 프로젝트 배포용)
- Workers Scripts — Edit (Workers 스크립트 및 CLI 설정 제어용)

🌐 1-2. 자체 도메인 연동 및 CDN 에지 캐시 사용 단계 (추후 설정)

블로그에 개인 도메인을 연결하고, 성능 고도화를 위해 에지 CDN 캐시를 강제 비우는(Purge) 기능 등을 활성화할 때 비로소 Zone 수준 권한이 요구됩니다.

추가 필수 권한:
- Zone: Cache Purge — Edit (배포 완료 시점이나 콘텐츠 갱신 시 CDN 에지 서버의 캐시를 즉시 제거하기 위해 필요)
보안 모범 사례: 토큰의 스코프를 제한할 때, Zone Resources를 'All Zones'로 열지 말고 사용 중인 특정 고유 도메인(Zone)으로 스코프를 한정하여 토큰을 발급받는 것이 안전합니다.
*참고: 자체 도메인 세팅 방법 및 캐시 제어 메커니즘의 세부 정보는 추후 별도로 발행될 **'자체 도메인 설정에 관한 상세 설명서'*에서 깊이 있게 다룰 예정이므로, 초기 구축 단계인 지금은 해당 설정을 생략하고 진행하셔도 무방합니다.

🛠️ 2. Cloudflare API 토큰 생성 절차

비대화형 로그인을 가능케 하는 토큰은 Cloudflare 대시보드에서 다음과 같은 순서로 간단히 생성할 수 있습니다.

Cloudflare 대시보드 로그인:
- Cloudflare Dashboard에 접속하여 로그인합니다.
토큰 생성 메뉴 진입:
- 우측 상단 프로필 아이콘을 클릭하고 **[My Profile] (프로필)**을 선택합니다.
- 좌측 메뉴에서 **[API Tokens] (API 토큰)**을 클릭하고, 우측의 [Create Token] (토큰 생성) 버튼을 클릭합니다.
사용자 지정 토큰 설정:
- 여러 템플릿 중 최하단의 [Create Custom Token] (사용자 지정 토큰 생성) 영역의 **[Get Started] (시작하기)**를 선택합니다.
권한(Permissions) 할당:
- Token Name: 구분이 쉬운 이름 입력 (예: sveltekit-blog-cli-token)
- Permissions:
  - 계정 (Account) -> D1 -> 편집 (Edit)
  - 계정 (Account) -> Workers KV 저장소 (Workers KV Storage) -> 편집 (Edit)
  - 계정 (Account) -> Cloudflare Pages -> 편집 (Edit)
  - 계정 (Account) -> Workers 스크립트 (Workers Scripts) -> 편집 (Edit)
스코프 제한:
- 계정 리소스 (Account Resources): 포함 (Include) -> 본인의 Cloudflare 계정 선택 (권한 범위를 내 계정 내부로만 좁혀 보안 위협을 격리합니다.)
생성 완료 및 보관:
- **[Continue to summary] (요약 계속)**를 누른 뒤 **[Create Token] (토큰 생성)**을 클릭하여 생성된 고유 토큰 값(알파벳과 기호로 구성된 긴 키 문자열)을 안전한 곳에 복사해 둡니다. (이 값은 재확인이 불가하므로 유실 시 다시 발급받아야 합니다.)

💻 3. 발급된 API 토큰 적용 및 환경변수 주입법

인터랙티브 브라우저 로그인 창을 띄울 수 없으므로, 시스템 환경변수에 발급받은 토큰 값을 주입하여 Wrangler가 자동으로 이를 조회하고 인증을 수립하게 유도해야 합니다.

3-1. OS 환경별 터미널 환경변수 주입 커맨드

셋업 스크립트를 구동할 터미널 콘솔 창에 OS 유형별로 아래의 명령어를 입력합니다.

Linux / macOS / Git Bash (Bash Shell):

export CLOUDFLARE_API_TOKEN="발급받은_토큰_값"

Windows Command Prompt (CMD):

set CLOUDFLARE_API_TOKEN=발급받은_토큰_값

Windows PowerShell:

$env:CLOUDFLARE_API_TOKEN="발급받은_토큰_값"

[!NOTE]
💻 macOS 환경에서의 실행 및 테스트 안내

본 가이드는 Windows 10/11 및 Linux(Ubuntu 22.04 LTS) 물리적 콘솔 환경에서 직접 명령행 구동 및 토큰 연동 유효성을 사전에 전수 검증하였습니다.

다만 작성자 개인의 개발 장비 부재로 인해 macOS(맥북 환경)에서의 실기기 테스트는 거치지 못했습니다. 크로스 플랫폼 CLI 동작 원리상 macOS에서도 Bash/Zsh 터미널을 통해 동일하게 export 구문으로 완벽히 정상 가동될 것으로 판단됩니다.

3-2. 로컬 개발 환경 파일 연동 및 CI/CD 연동

로컬 개발 (.dev.vars):
매번 터미널 창을 열 때마다 환경변수를 치기 번거롭다면, apps/blog/.dev.vars 및 apps/admin/.dev.vars 파일에 아래와 같이 등록해 두면 로컬 wrangler dev 구동 시 해당 파일에서 토큰을 자동으로 파싱하여 바인딩 처리합니다.
```
CLOUDFLARE_API_TOKEN="발급받은_토큰_값"
```
CI/CD 파이프라인 (GitHub Actions):
깃허브 레포지토리의 Settings -> Secrets and variables -> Actions -> Repository secrets 메뉴로 가셔서 CLOUDFLARE_API_TOKEN 이라는 이름으로 발급받은 토큰을 추가한 뒤, yaml 워크플로우 파일에서 아래와 같이 활용할 수 있습니다.
```
- name: Build and Deploy SvelteKit Apps
  env:
    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
  run: npm run deploy:blog
```

🔍 4. 토큰 인증 상태 검증 및 디버깅

토큰 환경변수가 시스템 세션 상에 안전하게 주입되어 정상적으로 바인딩되었는지 확인하기 위한 디버깅 커맨드입니다.

4-1. wrangler whoami

터미널에서 아래 명령을 내려 토큰이 유효한 계정을 매칭하고 있는지 검증합니다.

npx wrangler whoami

검증 통과 시: 현재 토큰이 소속된 계정 정보(Account Name, Account ID) 및 D1, KV 등의 제어 권한 바인딩 목록이 콘솔에 깔끔하게 성공 출력됩니다.
로그인 세션 정리 (wrangler logout):
만약 이전에 로컬 웹 브라우저 로그인 방식으로 맺어놓은 세션 찌꺼기가 남아 토큰과 간섭을 일으키는 것 같다면, 먼저 로그아웃 명령어를 수행하여 로컬 컴퓨터 내의 기존 인증 세션을 완전히 초기화한 후 환경변수를 다시 적용하는 것을 권장합니다.
```
npx wrangler logout
```

⚠️ 5. 자주 마주치는 문제 및 해결 방안 (Troubleshooting)

🚨 1. Authentication Error (Code: 10000)

원인: 셋업 스크립트 실행 중 Cloudflare 인증 실패 오류가 표시되는 상황입니다.
해결: 복사하여 주입한 CLOUDFLARE_API_TOKEN 값 내에 오탈자나 공백이 포함되었는지 확인하세요. 또한, 대시보드에서 토큰을 발급받을 때 지정한 Account Resources 스코프가 현재 접속 중인 계정과 일치하는지 재검토해야 합니다.

🚨 2. Forbidden (권한 거부 에러)

원인: D1 마이그레이션 중에는 에러가 없으나 Pages 배포 또는 KV 리소스 생성 중 에러가 발생하는 경우입니다.
해결: 생성한 토큰의 Permissions 리스트에 Cloudflare Pages -> Edit 또는 Workers KV Storage -> Edit 권한 중 누락된 권한이 없는지 대시보드 API 토큰 목록에서 확인하고 권한을 추가 수정한 뒤 다시 환경변수 주입을 시도하세요.

Share this post on social networks

0 Comments

This post is written in English.

CLI 환경에서 Cloudflare Wrangler 로그인 및 API 토큰 설정 상세 설명서

detail-manual • 2026-07-06 PM7:49:33 (GMT+9) • 👀 2 •

#Wrangler #Cloudflare #CLI #API Token #Login

🔑 CLI 환경에서 Cloudflare Wrangler 로그인 및 API 토큰 설정 상세 설명서

본 프로젝트는 단일 명령어로 Cloudflare의 데이터베이스, 저장소, 빌드 파이프라인을 구축해주는 자동화 셋업 스크립트를 제공합니다.

📂 1. 도메인 설정 전후에 따른 필수 최소 권한 구분

🔌 1-1. 초기 배포 단계 (자체 도메인 연동 전)

필수 최소 권한 목록:
- D1 — Edit (D1 DB 생성, 스키마 마이그레이션 실행 및 쿼리 작동용)
- Workers KV Storage — Edit (블로그 미디어 업로드용 KV 네임스페이스 제어용)
- Cloudflare Pages — Edit (모노레포의 블로그 및 어드민 프로젝트 배포용)
- Workers Scripts — Edit (Workers 스크립트 및 CLI 설정 제어용)

🌐 1-2. 자체 도메인 연동 및 CDN 에지 캐시 사용 단계 (추후 설정)

추가 필수 권한:
- Zone: Cache Purge — Edit (배포 완료 시점이나 콘텐츠 갱신 시 CDN 에지 서버의 캐시를 즉시 제거하기 위해 필요)
보안 모범 사례: 토큰의 스코프를 제한할 때, Zone Resources를 'All Zones'로 열지 말고 사용 중인 특정 고유 도메인(Zone)으로 스코프를 한정하여 토큰을 발급받는 것이 안전합니다.
*참고: 자체 도메인 세팅 방법 및 캐시 제어 메커니즘의 세부 정보는 추후 별도로 발행될 **'자체 도메인 설정에 관한 상세 설명서'*에서 깊이 있게 다룰 예정이므로, 초기 구축 단계인 지금은 해당 설정을 생략하고 진행하셔도 무방합니다.

🛠️ 2. Cloudflare API 토큰 생성 절차

비대화형 로그인을 가능케 하는 토큰은 Cloudflare 대시보드에서 다음과 같은 순서로 간단히 생성할 수 있습니다.

Cloudflare 대시보드 로그인:
- Cloudflare Dashboard에 접속하여 로그인합니다.
토큰 생성 메뉴 진입:
- 우측 상단 프로필 아이콘을 클릭하고 **[My Profile] (프로필)**을 선택합니다.
- 좌측 메뉴에서 **[API Tokens] (API 토큰)**을 클릭하고, 우측의 [Create Token] (토큰 생성) 버튼을 클릭합니다.
사용자 지정 토큰 설정:
- 여러 템플릿 중 최하단의 [Create Custom Token] (사용자 지정 토큰 생성) 영역의 **[Get Started] (시작하기)**를 선택합니다.
권한(Permissions) 할당:
- Token Name: 구분이 쉬운 이름 입력 (예: sveltekit-blog-cli-token)
- Permissions:
  - 계정 (Account) -> D1 -> 편집 (Edit)
  - 계정 (Account) -> Workers KV 저장소 (Workers KV Storage) -> 편집 (Edit)
  - 계정 (Account) -> Cloudflare Pages -> 편집 (Edit)
  - 계정 (Account) -> Workers 스크립트 (Workers Scripts) -> 편집 (Edit)
스코프 제한:
- 계정 리소스 (Account Resources): 포함 (Include) -> 본인의 Cloudflare 계정 선택 (권한 범위를 내 계정 내부로만 좁혀 보안 위협을 격리합니다.)
생성 완료 및 보관:
- **[Continue to summary] (요약 계속)**를 누른 뒤 **[Create Token] (토큰 생성)**을 클릭하여 생성된 고유 토큰 값(알파벳과 기호로 구성된 긴 키 문자열)을 안전한 곳에 복사해 둡니다. (이 값은 재확인이 불가하므로 유실 시 다시 발급받아야 합니다.)

💻 3. 발급된 API 토큰 적용 및 환경변수 주입법

3-1. OS 환경별 터미널 환경변수 주입 커맨드

셋업 스크립트를 구동할 터미널 콘솔 창에 OS 유형별로 아래의 명령어를 입력합니다.

Linux / macOS / Git Bash (Bash Shell):

export CLOUDFLARE_API_TOKEN="발급받은_토큰_값"

Windows Command Prompt (CMD):

set CLOUDFLARE_API_TOKEN=발급받은_토큰_값

Windows PowerShell:

$env:CLOUDFLARE_API_TOKEN="발급받은_토큰_값"

[!NOTE]
💻 macOS 환경에서의 실행 및 테스트 안내

본 가이드는 Windows 10/11 및 Linux(Ubuntu 22.04 LTS) 물리적 콘솔 환경에서 직접 명령행 구동 및 토큰 연동 유효성을 사전에 전수 검증하였습니다.

다만 작성자 개인의 개발 장비 부재로 인해 macOS(맥북 환경)에서의 실기기 테스트는 거치지 못했습니다. 크로스 플랫폼 CLI 동작 원리상 macOS에서도 Bash/Zsh 터미널을 통해 동일하게 export 구문으로 완벽히 정상 가동될 것으로 판단됩니다.

3-2. 로컬 개발 환경 파일 연동 및 CI/CD 연동

로컬 개발 (.dev.vars):
매번 터미널 창을 열 때마다 환경변수를 치기 번거롭다면, apps/blog/.dev.vars 및 apps/admin/.dev.vars 파일에 아래와 같이 등록해 두면 로컬 wrangler dev 구동 시 해당 파일에서 토큰을 자동으로 파싱하여 바인딩 처리합니다.
```
CLOUDFLARE_API_TOKEN="발급받은_토큰_값"
```
CI/CD 파이프라인 (GitHub Actions):
깃허브 레포지토리의 Settings -> Secrets and variables -> Actions -> Repository secrets 메뉴로 가셔서 CLOUDFLARE_API_TOKEN 이라는 이름으로 발급받은 토큰을 추가한 뒤, yaml 워크플로우 파일에서 아래와 같이 활용할 수 있습니다.
```
- name: Build and Deploy SvelteKit Apps
  env:
    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
  run: npm run deploy:blog
```

🔍 4. 토큰 인증 상태 검증 및 디버깅

토큰 환경변수가 시스템 세션 상에 안전하게 주입되어 정상적으로 바인딩되었는지 확인하기 위한 디버깅 커맨드입니다.

4-1. wrangler whoami

터미널에서 아래 명령을 내려 토큰이 유효한 계정을 매칭하고 있는지 검증합니다.

npx wrangler whoami

검증 통과 시: 현재 토큰이 소속된 계정 정보(Account Name, Account ID) 및 D1, KV 등의 제어 권한 바인딩 목록이 콘솔에 깔끔하게 성공 출력됩니다.
로그인 세션 정리 (wrangler logout):
만약 이전에 로컬 웹 브라우저 로그인 방식으로 맺어놓은 세션 찌꺼기가 남아 토큰과 간섭을 일으키는 것 같다면, 먼저 로그아웃 명령어를 수행하여 로컬 컴퓨터 내의 기존 인증 세션을 완전히 초기화한 후 환경변수를 다시 적용하는 것을 권장합니다.
```
npx wrangler logout
```

⚠️ 5. 자주 마주치는 문제 및 해결 방안 (Troubleshooting)

🚨 1. Authentication Error (Code: 10000)

원인: 셋업 스크립트 실행 중 Cloudflare 인증 실패 오류가 표시되는 상황입니다.
해결: 복사하여 주입한 CLOUDFLARE_API_TOKEN 값 내에 오탈자나 공백이 포함되었는지 확인하세요. 또한, 대시보드에서 토큰을 발급받을 때 지정한 Account Resources 스코프가 현재 접속 중인 계정과 일치하는지 재검토해야 합니다.

🚨 2. Forbidden (권한 거부 에러)

원인: D1 마이그레이션 중에는 에러가 없으나 Pages 배포 또는 KV 리소스 생성 중 에러가 발생하는 경우입니다.
해결: 생성한 토큰의 Permissions 리스트에 Cloudflare Pages -> Edit 또는 Workers KV Storage -> Edit 권한 중 누락된 권한이 없는지 대시보드 API 토큰 목록에서 확인하고 권한을 추가 수정한 뒤 다시 환경변수 주입을 시도하세요.

Share this post on social networks

0 Comments

This post is written in English.

Categories

Popular Posts

Recent Posts

Tags

Buy me a Coffee

🔑 CLI 환경에서 Cloudflare Wrangler 로그인 및 API 토큰 설정 상세 설명서

📂 1. 도메인 설정 전후에 따른 필수 최소 권한 구분

🔌 1-1. 초기 배포 단계 (자체 도메인 연동 전)

🌐 1-2. 자체 도메인 연동 및 CDN 에지 캐시 사용 단계 (추후 설정)

🛠️ 2. Cloudflare API 토큰 생성 절차

💻 3. 발급된 API 토큰 적용 및 환경변수 주입법

3-1. OS 환경별 터미널 환경변수 주입 커맨드

3-2. 로컬 개발 환경 파일 연동 및 CI/CD 연동

🔍 4. 토큰 인증 상태 검증 및 디버깅

4-1. wrangler whoami

⚠️ 5. 자주 마주치는 문제 및 해결 방안 (Troubleshooting)

🚨 1. Authentication Error (Code: 10000)

🚨 2. Forbidden (권한 거부 에러)

Share this post on social networks

0 Comments

Tags

🔑 CLI 환경에서 Cloudflare Wrangler 로그인 및 API 토큰 설정 상세 설명서

📂 1. 도메인 설정 전후에 따른 필수 최소 권한 구분

🔌 1-1. 초기 배포 단계 (자체 도메인 연동 전)

🌐 1-2. 자체 도메인 연동 및 CDN 에지 캐시 사용 단계 (추후 설정)

🛠️ 2. Cloudflare API 토큰 생성 절차

💻 3. 발급된 API 토큰 적용 및 환경변수 주입법

3-1. OS 환경별 터미널 환경변수 주입 커맨드

3-2. 로컬 개발 환경 파일 연동 및 CI/CD 연동

🔍 4. 토큰 인증 상태 검증 및 디버깅

4-1. wrangler whoami

⚠️ 5. 자주 마주치는 문제 및 해결 방안 (Troubleshooting)

🚨 1. Authentication Error (Code: 10000)

🚨 2. Forbidden (권한 거부 에러)

Share this post on social networks

0 Comments

인기 포스트

태그

커피 한 잔 사주기