VoidFlag CLI

  ┌────────────────────────────────────────────────────────────────────┐
  │                                                                    │
  │   ██╗   ██╗ ██████╗ ██╗██████╗ ███████╗██╗      █████╗  ██████╗    │
  │   ██║   ██║██╔═══██╗██║██╔══██╗██╔════╝██║     ██╔══██╗██╔════╝    │
  │   ██║   ██║██║   ██║██║██║  ██║█████╗  ██║     ███████║██║  ███╗   │
  │   ╚██╗ ██╔╝██║   ██║██║██║  ██║██╔══╝  ██║     ██╔══██║██║   ██║   │
  │    ╚████╔╝ ╚██████╔╝██║██████╔╝██║     ███████╗██║  ██║╚██████╔╝   │
  │     ╚═══╝   ╚═════╝ ╚═╝╚═════╝ ╚═╝     ╚══════╝╚═╝  ╚═╝ ╚═════╝    │
  │                                                                    │
  │                                                                    │
  │   schema-first feature flags                                       │
  │   https://voidflag.vercel.app/                                     │
  │                                                                    │
  └────────────────────────────────────────────────────────────────────┘

VoidFlag is a schema-first feature flagging tool designed for developers who want type-safety, local-first development, and seamless environment synchronization.

By defining your flags in a .vf schema file, VoidFlag generates type-safe SDK clients and provides a local dashboard to toggle flags during development without ever hitting a remote API.

Quick Start

1. Installation

Install the CLI globally or as a dev dependency:

npm install -g voidflag-cli
# or
npm install --save-dev voidflag-cli

2. Initialize

Run the init command to create your initial schema.vf file:

vf init

3. Define Flags

Edit schema.vf to define your features. The syntax is clean and strictly typed:

flag darkMode {
  type bool
  fallback false
}

flag apiTimeout {
  type number
  fallback 5000
}

flag theme {
  type string
  fallback "system"
}

4. Generate Types

Generate the type-safe client and configuration files:

vf generate src/voidflag --lang ts

Commands

vf dev

Starts a local development server and dashboard.

• Real-time: Uses SSE (Server-Sent Events) to push flag changes to your application instantly.
• Local UI: Provides a web interface at http://localhost:47211 to toggle flags, adjust rollouts, and change values.
• Persistence: Saves your local tweaks to voidflag.state.json so they persist across restarts.

vf generate [dir] [lang]

Parses your schema.vf and generates:

• voidflag.schema.ts: The raw definition of your flags.
• voidflag.client.ts: A pre-configured VoidClient ready for use in your app.
• voidflag.config.json: Project settings (path to schema, language, etc.).

vf push

Synchronizes your local schema with the VoidFlag cloud. This registers your flag keys and types so they appear in your project dashboard.

Note: Requires VOIDFLAG_PROJECT_KEY environment variable.

vf apply --env [env_name]

Promotes your current local flag states (from your dev session) to a specific remote environment (e.g., staging or production).

vf env sync

Fetches the environment names configured in your cloud dashboard and maps them to environment variable keys in your voidflag.config.json.

Usage in Code

Once generated, using flags in TypeScript is fully type-safe:

import { vf } from './voidflag/voidflag.client';

const { darkMode, apiTimeout } = vf.flags;

// 'darkMode' is autocompleted and typed as boolean
if (darkMode) {
  enableDarkStyles();
}

// 'apiTimeout' is typed as number
const timeout = apiTimeout;

Features

• Schema-First: Your code stays in sync with your definitions. No more "magic strings" for flag keys.
• Zero Latency: During development, flags are served from a local server. In production, the SDK uses optimized delivery.
• Type Safety: Catch errors at compile time if you change a flag type or delete a key in the schema.
• Beautiful CLI: Designed with a modern, readable terminal experience.

Configuration

The voidflag.config.json file manages your project link:

{
  "voidflagDir": "src/voidflag",
  "lang": "ts",
  "schemaPath": "schema.vf",
  "devPort": 47211,
  "environments": {
    "production": "VF_PRODUCTION_KEY",
    "staging": "VF_STAGING_KEY"
  }
}

Documentation • Report Bug