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.

How Environments Work

When you activate an environment, wfapi looks for a config file with that environment’s name:

• default environment → .wfapi
• dev environment → .wfapi.dev
• staging environment → .wfapi.staging
• prod environment → .wfapi.prod

View Current Environment

Check which environment is active:

wfapi env

Switch Environments

Activate a specific environment:

wfapi env dev

This switches to the dev environment, using .wfapi.dev for configuration.

Switch back to default:

wfapi env default

Environment Badges

When an environment is active, a colored badge appears at the top of command output:

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

Example Workflow

Set up multiple environments:

# Create development environment config
echo "API_TOKEN=dev_token_here" > .wfapi.dev
 
# Create staging environment config
echo "API_TOKEN=staging_token_here" > .wfapi.staging
 
# Create production environment config
echo "API_TOKEN=prod_token_here" > .wfapi.prod
 
# Switch to dev
wfapi env dev
 
# All commands now use .wfapi.dev
wfapi sites              # Shows DEV badge
 
# Switch to staging
wfapi env staging
wfapi sites              # Shows STAGING badge
 
# Switch to production
wfapi env prod
wfapi sites              # Shows PROD badge (red warning)
 
# Switch back to default
wfapi env default

Environment-Specific Context

Each environment can have its own site and collection context:

# In dev environment
wfapi env dev
wfapi use site dev-site-id
wfapi use cms dev-collection
 
# Switch to prod environment
wfapi env prod
wfapi use site prod-site-id
wfapi use cms prod-collection

The SITE_ID and COLLECTION_ID are saved per environment in the respective config files.

Global vs Local Environments

Both global and local environment configs are supported:

• Global: ~/.wfapi.dev, ~/.wfapi.staging, etc.
• Local: ./.wfapi.dev, ./.wfapi.staging, etc.

Local environment configs take precedence over global ones, following the same hierarchy as standard configs.

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)

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

./.wfapi.dev:

API_TOKEN=wfp_dev_token
SITE_ID=dev_site_id_here

./.wfapi.prod:

API_TOKEN=wfp_prod_token
SITE_ID=prod_site_id_here

Next Steps