🔑 Cloudflare Wrangler Login and API Token Configuration Guide in CLI Environments

This project provides an automated setup script that provisions Cloudflare databases, storage, and build pipelines in a single execution.

While this script internally runs the Cloudflare wrangler CLI, local development environments typically trigger an interactive web browser login (npx wrangler login). However, in headless CLI-only environments (such as remote SSH Linux servers, headless virtual machines, or CI/CD build pipelines), establishing an interactive browser session is impossible.

This manual explains how to bypass this limitation and safely configure a non-interactive Wrangler session using a Cloudflare API Token.

📂 1. Permission Scopes: Before vs. After Domain Setup

Before issuing a token, it is crucial to understand your current deployment stage. To follow security best practices, separate your permissions based on your custom domain connection state.

🔌 1-1. Initial Deployment (Before Custom Domain Setup)

If you are deploying for the first time and only using the default *.pages.dev domains provided by Cloudflare Pages, you do not need any Zone (domain) level permissions. The setup script, database migrations, and resource bindings will function perfectly with only Account-level permissions.

• Required Minimum Permissions:
  • D1 — Edit (Required to create, query, and migrate D1 databases)
  • Workers KV Storage — Edit (Required to manage KV namespaces for media uploads)
  • Cloudflare Pages — Edit (Required to build and deploy SvelteKit applications)
  • Workers Scripts — Edit (Required for CLI script management)

🌐 1-2. Custom Domain Mapping & CDN Edge Cache Purging (Future Setup)

When you bind a custom domain to your blog and enable edge CDN cache purging for better performance, you will then require Zone-level permissions.

• Additional Required Permission:
  • Zone: Cache Purge — Edit (Required to invalidate CDN edge caches when content changes)
• Security Best Practice: When limiting token scopes, do not set Zone Resources to "All Zones". Restrict it to the specific custom domain (Zone) you are currently using.
• *Note: The custom domain setup and edge CDN cache configuration will be discussed in detail in the upcoming 'Custom Domain Setup Detailed Manual'. You can safely skip these settings during your initial setup.*

🛠️ 2. Cloudflare API Token Creation Steps

You can generate a token for non-interactive logins in the Cloudflare dashboard by following these steps:

1. Log in to the Cloudflare Dashboard:
   • Navigate to the Cloudflare Dashboard and log in.
2. Access the API Tokens Menu:
   • Click the user icon in the top right corner of the dashboard and select My Profile.
   • In the left-hand navigation sidebar, click API Tokens.
   • Click the Create Token button on the right.
3. Select Custom Token:
   • Under the templates list, locate the Create Custom Token section at the bottom and click Get Started.
4. Configure Permissions:
   • Token Name: Enter a descriptive name (e.g., sveltekit-blog-cli-token).
   • Permissions:
     • Account -> D1 -> Edit
     • Account -> Workers KV Storage -> Edit
     • Account -> Cloudflare Pages -> Edit
     • Account -> Workers Scripts -> Edit
5. Restrict Resources (Scope):
   • Account Resources: Set to Include -> Select your Cloudflare Account (Restricts the token's scope to your account only to isolate security risks).
6. Generate and Save:
   • Click Continue to summary, then click Create Token.
   • Copy the generated API token (a long alphanumeric string) and store it in a secure location. (Note: You cannot view this token again after leaving the page. If lost, you must generate a new one.)

💻 3. Setting the Environment Variable

Since the browser login is bypassed, you must inject the token value into your system's environment variables. Wrangler will automatically detect it and establish an active session.

3-1. Terminal Command by Operating System

Run the appropriate command in your terminal session before executing any setup script:

• Linux / macOS / Git Bash (Bash/Zsh Shell):

  export CLOUDFLARE_API_TOKEN="your_generated_api_token"
  

• Windows Command Prompt (CMD):

  set CLOUDFLARE_API_TOKEN=your_generated_api_token
  

• Windows PowerShell:

  $env:CLOUDFLARE_API_TOKEN="your_generated_api_token"
  

[!NOTE]
💻 Compatibility and macOS Testing Note

• This guide has been fully verified and tested on Windows 10/11 and Linux (Ubuntu 22.04 LTS) console environments.
• Due to the author's lack of physical macOS hardware, a hands-on verification on macOS (MacBook) was not performed. However, since Node.js CLI executes cross-platform binaries identically, this will work seamlessly on macOS using the standard Zsh/Bash export command.

3-2. Local Development (.dev.vars) and CI/CD Integrations

• Local Development:
  To avoid typing the variable in every terminal session, add the token to the .dev.vars files in apps/blog/ and apps/admin/. Wrangler will parse it automatically:

  CLOUDFLARE_API_TOKEN="your_generated_api_token"
  

• CI/CD Pipelines (GitHub Actions):
  Register the token under Settings -> Secrets and variables -> Actions -> Repository secrets as CLOUDFLARE_API_TOKEN and map it in your workflow file:

  - name: Build and Deploy SvelteKit Apps
    env:
      CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
    run: npm run deploy:blog
  

🔍 4. Verification and Debugging

You can verify that the environment variable has been correctly injected and linked to your Cloudflare account using the following diagnostic tools.

4-1. wrangler whoami

Run this command in your terminal:

npx wrangler whoami

• Success Output: If valid, the CLI will output your account details (Account Name, Account ID) and the list of permitted bindings (D1, KV, Pages, etc.).
• Clearing Sessions (wrangler logout):
  If an existing interactive browser session interferes with your token environment variable, clear the local cache and reset the state using the logout command:

  npx wrangler logout
  

⚠️ 5. Troubleshooting

🚨 1. Authentication Error (Code: 10000)

• Symptom: The CLI prints authentication errors when executing the provisioning scripts.
• Solution: Double-check for typos or leading/trailing spaces in your CLOUDFLARE_API_TOKEN string. Verify that the Account Resources scope matches the account ID of the active project.

🚨 2. Forbidden (Access Denied)

• Symptom: D1 migrations work fine, but Pages deployments or KV namespace creations fail with access denied errors.
• Solution: Ensure your token has all four required edit permissions (Pages -> Edit, Workers KV -> Edit, etc.) in the Cloudflare API Tokens dashboard. If any are missing, update the token permissions and try again.