Skip to content

overview.mdx

Latest commit

 

History

History
260 lines (180 loc) · 7.66 KB

overview.mdx

File metadata and controls

260 lines (180 loc) · 7.66 KB
title CLI Reference
description Complete reference for the kfl CLI
sidebar_position 1

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. 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...]
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

# $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>
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