Skip to main content

​
CLI Reference (kfl)

Complete reference for the Keyflare command-line interface.

​
Installation

npm install -g @keyflare/cli
Or use directly with npx: 
npx @keyflare/cli <command>

​
Global Options

OptionDescription
--api-url <url>Override API URL (default: from config)
--api-key <key>Override API key (default: from credentials file or $KEYFLARE_API_KEY)
--project <name>Override default project
--env <name>Override default environment
--helpShow help
--versionShow version

​
Commands

​
kfl init

Deploy or update Keyflare on your Cloudflare account. 
kfl init [-y] [--name <name>] [--d1id <uuid>] [--master-key <key>]
FlagDescription
-y, --yesSkip confirmation prompts (auto-accept)
--name <name>Worker and database name (default: keyflare). Must start with a lowercase letter, contain only lowercase letters, numbers, and hyphens, and be 63 characters or less.
--d1id <uuid>Bind to an existing D1 database by UUID. Creates new DB if not provided (or uses the existing binding if a worker exists already).
--master-key <key>Custom master key (base64-encoded 256-bit)
Authentication:
  • Reuses existing Wrangler session when available
  • Falls back to CLOUDFLARE_API_TOKEN environment variable
  • Prompts for OAuth browser login or API token if neither available
Preflight Check: Before creating a new bootstrap key, kfl init checks your local configuration:
  • If the new API URL differs from your stored URL, you’ll see a warning
  • If credentials exist locally and a new bootstrap key would be created, you’ll be prompted to confirm
If you decline the prompt:
  • The worker is still deployed/updated
  • Bootstrap is skipped (someone else can run it)
  • Your local config and credentials are preserved
Use -y to auto-accept all prompts. Multiple Instances: You can deploy multiple Keyflare instances by using different names: 
kfl init --name keyflare-prod
kfl init --name keyflare-staging
Using an Existing D1 Database: To bind Keyflare to an existing D1 database (e.g., for migration or disaster recovery): 
kfl init --d1id 12345678-1234-1234-1234-123456789abc
This skips database creation and binds the worker to the specified database. Migrations will run against it on first deploy.

​
kfl login

Log in to an existing Keyflare deployment. 
kfl login
Interactive prompts for:
  1. Keyflare API URL
  2. API key
Saves credentials to ~/.config/keyflare/.

​
kfl projects

Manage projects. 
# List all projects
kfl projects list

# Create a project (with dev and prod environments)
kfl projects create <name>

# Create a project without default environments
kfl projects create <name> --environmentless

# Delete a project
kfl projects delete <name>
FlagDescription
--environmentlessCreate project without default environments

​
kfl environments (alias: env)

Manage environments. 
# List environments in a project
kfl env list --project <name>

# Create an environment
kfl env create <env-name> --project <name>

# Delete an environment
kfl env delete <env-name> --project <name>

​
kfl secrets

Manage secrets. 
# Set secrets
kfl secrets set <KEY>=<VALUE> --project <name> --env <env>
kfl secrets set KEY1=val1 KEY2=val2 --project <name> --env <env>

# Get a secret
kfl secrets get <KEY> --project <name> --env <env>

# List secrets (values hidden)
kfl secrets list --project <name> --env <env>

# Delete a secret
kfl secrets delete <KEY> --project <name> --env <env>

# Upload from .env (full override)
kfl secrets upload <file> --project <name> --env <env>

# Download secrets
kfl secrets download --project <name> --env <env> [options]
Upload replaces ALL existing secrets in the target environment.
OptionDescription
--format <fmt>Output format: env (default), json, yaml, shell
--output <file>Write to file (default: stdout)
Legacy aliases are still available but deprecated: kfl upload, kfl download.

​
kfl run

Run a command with secrets injected as environment variables. The command is executed via the shell, so $VAR references, pipes, redirects, and && chains all work as expected. 
kfl run --project <name> --env <env> -- <command> [args...]
FlagDescription
--project <name>Project name (or set KEYFLARE_PROJECT)
--env <name>Environment name (or set KEYFLARE_ENV)
Examples: 
kfl run --project my-api --env production -- npm run build
kfl run --project my-api --env development -- npm run dev
kfl run -- npm run dev  # Uses defaults from config

# $VAR references work — expanded by the subprocess after secrets are injected
kfl run --project my-api --env Prod -- echo $MYSECRET
kfl run --project my-api --env Prod -- echo $DATABASE_URL | cut -d@ -f2

​
kfl keys

Manage API keys. 
# List all keys
kfl keys list

# Create a user key
kfl keys create --type user --label "backup-admin"

# Create a system key
kfl keys create --type system \
  --label "github-actions" \
  --scope "my-api:production" \
  --permission read

# Update a system key's scopes
kfl keys put <prefix> \
  --scope "my-api:production" \
  --scope "my-api:staging" \
  --permission readwrite

# Revoke a key
kfl keys revoke <prefix>
FlagDescription
--type <type>Key type: user or system
--label <label>Human-readable label
--scope <project:env>Scope for system keys. Repeatable. Use * for env wildcard.
--permission <perm>Permission: read or readwrite (system keys only)

​
Exit Codes

CodeMeaning
0Success
1General error
2Authentication error
3Authorization error
4Resource not found
5Network error