Configuration

wfapi offers flexible configuration options to support various workflows, from single projects to complex multi-environment setups.

Configuration Hierarchy

wfapi checks for configuration in the following priority order (highest to lowest):

1. Local .wfapi file (current directory) — highest priority
2. Environment variable WEBFLOW_API_TOKEN
3. Global .wfapi file (home directory) — lowest priority

This hierarchy allows you to override global settings on a per-project basis.

Managing Your API Token

Set Global Token (Recommended)

The easiest way to get started is to set a global token:

wfapi config set your_api_token_here

This saves your token to ~/.wfapi in your home directory.

View Current Token

Check which token is currently active:

wfapi config get

Or use the alias:

wfapi config show

Delete Token

Remove your global token:

wfapi config delete

Configuration File Format

The .wfapi file uses a simple key-value format:

API_TOKEN=your_actual_api_token_here
SITE_ID=68f81168c2a32ba4ce25cfc3
COLLECTION_ID=6611b3f9f3b1f1e2c0a12345

Available Keys

• API_TOKEN — Your Webflow API token (required)
• SITE_ID — Current site context (optional, set via wfapi use site)
• COLLECTION_ID — Current collection context (optional, set via wfapi use cms)

Environment Variables

Set the API token via environment variable:

PowerShell:

$env:WEBFLOW_API_TOKEN="your_api_token_here"

Command Prompt:

set WEBFLOW_API_TOKEN=your_api_token_here

Bash/Linux/macOS:

export WEBFLOW_API_TOKEN=your_api_token_here

Environment variables are useful for:

• CI/CD pipelines
• Temporary token overrides
• Containerized environments

Local Project Configuration

Create a .wfapi file in your project directory for project-specific settings:

# Create local config
echo "API_TOKEN=your_project_token" > .wfapi

Benefits:

• Different tokens per project
• Share configuration with team members
• Override global settings locally

Multi-Environment Support

wfapi supports multiple named environments (dev, staging, prod, etc.) for managing different deployment stages using a section-based configuration format within a single .wfapi file.

How Environments Work

Environments are defined as sections within your .wfapi file using INI-style [SECTION] headers. The configuration without a section header (at the top of the file) is the PROD (production) section and serves as the default.

Section-Based Configuration:

# Webflow API Configuration
# This is the PROD section (default)
ENV=PROD
API_TOKEN=prod_token
SITE_ID=prod_site_id
 
[DEV]
API_TOKEN=dev_token
SITE_ID=dev_site_id
 
[TEST]
API_TOKEN=test_token
SITE_ID=test_site_id
 
[STAGING]
API_TOKEN=staging_token
SITE_ID=staging_site_id

When you run wfapi env dev, the CLI updates the ENV= setting in the PROD section to ENV=DEV. The configuration system then merges the [DEV] section with the PROD section as fallback for any missing values.

Custom Environments

You can create any custom environment by adding a section with brackets [NAME]. Environment names:

• Are case-insensitive (staging, STAGING, Staging all resolve to STAGING)
• Can contain letters, numbers, underscores, and hyphens
• Must exist as a section in the config file before you can switch to them

Example with custom environments:

ENV=PROD
API_TOKEN=prod_token
 
[DEV]
API_TOKEN=dev_token
 
[STAGING]
API_TOKEN=staging_token
 
[QA]
API_TOKEN=qa_token
 
[DEV-2]
API_TOKEN=dev2_token

If you try to switch to an environment that doesn’t exist, you’ll get an error:

Error: Environment "NONEXISTENT" not found in configuration file

View Current Environment

Check which environment is active:

wfapi env

This displays the current environment setting and which section is active.

Temporary Overrides

Use --env <name> on most commands (sites, cms, items, schema, use) to run a single command against a specific environment without changing the saved ENV= value. Both --env test and --env=test are supported.

The --env override validates that the environment exists in your config file.

Switch Environments

Activate a specific environment:

wfapi env dev

This switches to the dev environment by updating ENV=DEV in your .wfapi file.

Switch back to production:

wfapi env prod

Environment names are case-insensitive, so wfapi env DEV, wfapi env dev, and wfapi env Dev all work identically.

Environment Badges

When a non-PROD environment is active, a colored badge appears at the top and bottom of command output:

This visual indicator helps prevent accidental operations on the wrong environment.

Example Workflow

Create a .wfapi file with multiple environments:

# Create .wfapi with multiple environment sections
cat > .wfapi << 'EOF'
# Webflow API Configuration
ENV=PROD
API_TOKEN=prod_token_here
SITE_ID=prod_site_id
 
[DEV]
API_TOKEN=dev_token_here
SITE_ID=dev_site_id
 
[STAGING]
API_TOKEN=staging_token_here
SITE_ID=staging_site_id
 
[QA]
API_TOKEN=qa_token_here
EOF
 
# Switch to dev
wfapi env dev
 
# All commands now use [DEV] section
wfapi sites              # Shows DEV badge (yellow)
 
# Switch to staging
wfapi env staging
wfapi sites              # Shows STAGING badge (blue)
 
# Switch to production
wfapi env prod
wfapi sites              # No badge shown (PROD is default)
 
# Use temporary override without changing saved ENV
wfapi sites --env qa     # Shows QA badge (magenta)

Environment-Specific Context

Each environment section can have its own site and collection context:

# Edit .wfapi to add site context per environment
cat > .wfapi << 'EOF'
ENV=PROD
API_TOKEN=prod_token
SITE_ID=prod_site_id
COLLECTION_ID=prod_collection_id
 
[DEV]
API_TOKEN=dev_token
SITE_ID=dev_site_id
COLLECTION_ID=dev_collection_id
 
[STAGING]
API_TOKEN=staging_token
SITE_ID=staging_site_id
COLLECTION_ID=staging_collection_id
EOF
 
# Switch to dev environment
wfapi env dev
 
# Commands automatically use dev site and collection
wfapi items              # Uses dev_collection_id
 
# Switch to staging
wfapi env staging
wfapi items              # Uses staging_collection_id

The SITE_ID and COLLECTION_ID values are merged from the active environment section with PROD as fallback.

Context Management

Context settings (site and collection) are saved to the same config file as your token:

• If a local .wfapi exists, context is saved there
• Otherwise, context is saved to the global ~/.wfapi

This allows project-specific context while maintaining a global default.

View Current Context

wfapi use

Shows:

• Current environment (if any)
• Active site (ID and name)
• Active collection (ID and name)

For one-off runs without changing saved context, most commands accept --site <id|slug> and --cms <id|slug> to temporarily point at a different site or collection.

Set Site Context

# By site ID
wfapi use site 68f81168c2a32ba4ce25cfc3
 
# By short name
wfapi use site my-site-shortname

Set Collection Context

Requires site context to be set first:

# By slug
wfapi use cms blog-posts
 
# By ID
wfapi use cms 6611b3f9f3b1f1e2c0a12345

OAuth Authentication (Future)

When available, OAuth will support:

# Global OAuth (saves to ~/.wfapi)
wfapi login
 
# Local OAuth (saves to ./.wfapi)
wfapi login local

Best Practices

Security

• Never commit .wfapi files to version control
• Use read-only API tokens when possible
• Rotate tokens regularly
• Use environment-specific tokens for production

Team Collaboration

• Share .wfapi.example files with placeholder values
• Document required permissions in your README
• Use local configs for project-specific settings
• Leverage environments for deployment stages

CI/CD Integration

• Use environment variables in CI/CD pipelines
• Never log or expose API tokens
• Use separate tokens for automation
• Implement token rotation policies

Example Configuration Files

Basic Global Config

~/.wfapi:

API_TOKEN=wfp_abc123xyz789

Local Project Config with Context

./.wfapi:

API_TOKEN=wfp_project_specific_token
SITE_ID=68f81168c2a32ba4ce25cfc3
COLLECTION_ID=6611b3f9f3b1f1e2c0a12345

Multi-Environment Setup (Section-Based)

./.wfapi:

# Webflow API Configuration
ENV=PROD
API_TOKEN=wfp_prod_token
SITE_ID=prod_site_id_here
 
[DEV]
API_TOKEN=wfp_dev_token
SITE_ID=dev_site_id_here
 
[STAGING]
API_TOKEN=wfp_staging_token
SITE_ID=staging_site_id_here

Next Steps