CLI Reference

Complete reference for the kfl CLI

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

Option	Description
--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
--help	Show help
--version	Show version

Commands

kfl init

Deploy or update Keyflare on your Cloudflare account.

kfl init [-y] [--name <name>] [--d1id <uuid>] [--master-key <key>]

Flag	Description
-y, --yes	Skip 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>

Flag	Description
--environmentless	Create 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.

Option	Description
--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. Commands are executed directly (argv-preserving), so quoting works reliably for cases like node -e '...'.

If you need shell features ($VAR expansion, pipes, redirects, &&), run an explicit shell command such as sh -c 'echo $MYSECRET | cut -d@ -f2'.

kfl run --project <name> --env <env> -- <command> [args...]

Flag	Description
--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

# Quoting is preserved for argv-based tools
kfl run --project my-api --env Prod -- node -e 'console.log(process.env.MYSECRET)'

# Use an explicit shell when you need shell operators / expansion
kfl run --project my-api --env Prod -- sh -c 'echo $MYSECRET'
kfl run --project my-api --env Prod -- sh -c '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>

Flag	Description
--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

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