@hauses/flags-cli

CLI tool for Flags SDK to generate TypeScript type definitions from your feature flags.

🌐 Website: flags.hauses.dev

Installation

``bash
npm install -D @hauses/flags-cli


or

yarn add -D @hauses/flags-cli

or

pnpm add -D @hauses/flags-cli

or

bun add -D @hauses/flags-cli
`

Features

- 🎯 Type-safe - Generate TypeScript definitions for your flags
- ⚡ Fast - Quick flag fetching and type generation
- 🔐 Secure - Multiple ways to provide API keys
- 📝 Simple - One command to sync your flags
- 🔄 CI-friendly - Works great in CI/CD pipelines

Quick Start

$3

`json
{
"scripts": {
"flags:pull": "flags-cli pull --env VITE_FLAGS_KEY --out src/flags.d.ts"
}
}
`

$3

`bash
npm run flags:pull
`

This generates a flags.d.ts file with type definitions for all your flags.

Usage

$3

`bash
flags-cli pull [options]
`

$3

- -k, --key - Publishable key (supports $VARIABLE syntax)
- -e, --env - Environment variable name containing the key
- -o, --out - Output file path (default: ./flags.d.ts)
- -V, --version - Output the version number
- -h, --help - Display help information

Examples

$3

`bash
flags-cli pull --env VITE_FLAGS_KEY
`

This reads the key from the VITE_FLAGS_KEY environment variable.

$3

`bash
flags-cli pull --key $VITE_FLAGS_KEY
`

This also reads from the VITE_FLAGS_KEY environment variable.

$3

`bash
flags-cli pull --key pk_123456789
`

⚠️ Not recommended for production - Use environment variables instead.

$3

`bash
flags-cli pull --env FLAGS_KEY --out types/flags.d.ts
`

$3

`json
{
"scripts": {
"flags:dev": "flags-cli pull --env VITE_FLAGS_DEV_KEY --out src/flags.d.ts",
"flags:prod": "flags-cli pull --env VITE_FLAGS_PROD_KEY --out src/flags.d.ts"
}
}
`

Generated Output

The CLI generates a TypeScript declaration file that extends the SDK types:

`typescript
import "react-sdk";

declare module "react-sdk" {
export interface FlagValues {
"dark-mode": boolean;
"new-dashboard": boolean;
"beta-features": boolean;
"experimental-ui": boolean;
}
}
`

This provides autocomplete and type checking in your IDE:

`tsx
import { useFlags } from '@hauses/react-sdk';

// ✅ TypeScript knows about these flags
useFlags('dark-mode');
useFlags('new-dashboard');

// ❌ TypeScript error - flag doesn't exist
useFlags('unknown-flag');
`

Framework Integration

$3

`json
{
"scripts": {
"flags:pull": "flags-cli pull --env VITE_FLAGS_KEY"
}
}
`

`env
VITE_FLAGS_KEY=pk_your_key_here
`

$3

`json
{
"scripts": {
"flags:pull": "flags-cli pull --env REACT_APP_FLAGS_KEY"
}
}
`

`env
REACT_APP_FLAGS_KEY=pk_your_key_here
`

$3

`json
{
"scripts": {
"flags:pull": "flags-cli pull --env NEXT_PUBLIC_FLAGS_KEY"
}
}
`

`env
NEXT_PUBLIC_FLAGS_KEY=pk_your_key_here
`

$3

`json
{
"scripts": {
"flags:pull": "flags-cli pull --env VITE_FLAGS_KEY"
}
}
`

CI/CD Integration

$3

`yaml
name: Update Flag Types

on:
schedule:
- cron: '0 /6 ' # Every 6 hours
workflow_dispatch:

jobs:
update-flags:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: '18'
- run: npm install
- run: npm run flags:pull
env:
VITE_FLAGS_KEY: ${{ secrets.FLAGS_KEY }}
- name: Create Pull Request
uses: peter-evans/create-pull-request@v5
with:
commit-message: 'chore: update flag types'
title: 'Update feature flag types'
branch: update-flags
`

$3

`yaml
update-flags:
stage: update
script:
- npm install
- npm run flags:pull
artifacts:
paths:
- src/flags.d.ts
only:
- schedules
`

$3

`json
{
"husky": {
"hooks": {
"pre-commit": "npm run flags:pull && git add src/flags.d.ts"
}
}
}
`

Development Workflow

$3

Go to flags.hauses.dev and create your flags.

$3

`bash
npm run flags:pull
`

$3

`tsx
const myFlag = useFlags('my-new-flag'); // Autocomplete works!
`

$3

`bash
git add src/flags.d.ts
git commit -m "chore: update flag types"
`

Best Practices

$3

`json
{
"scripts": {
"prebuild": "npm run flags:pull",
"build": "vite build"
}
}
`

$3

`bash


✅ Good

flags-cli pull --env VITE_FLAGS_KEY

❌ Bad - exposes key in command history

flags-cli pull --key pk_123456789
`

$3

If you prefer to generate types locally only:

`gitignore


.gitignore


src/flags.d.ts
`

Or commit it for team consistency:

`bash


Keep flags.d.ts in version control


git add src/flags.d.ts
`

$3

Automate flag type updates with scheduled workflows.

Troubleshooting

$3

`bash
❌ Error: Environment variable VITE_FLAGS_KEY is not set.
`

Solution: Make sure the environment variable exists:

`bash
echo $VITE_FLAGS_KEY
`

$3

`bash
❌ Error: Publishable Key is missing.
`

Solution: Provide the key using one of these methods:

`bash
flags-cli pull --key pk_123
flags-cli pull --env FLAGS_KEY
flags-cli pull --key $FLAGS_KEY
`

$3

`bash
❌ Error generating types: Failed to fetch flags: 401 Unauthorized
`

Solution: Check that your publishable key is valid and has the correct permissions.

$3

`bash
Warning: No flags found.
✅ Successfully generated types at ./flags.d.ts
Found 0 flags:
`

Solution: Create some flags in your dashboard at flags.hauses.dev.

API

$3

Fetches flags from the API and generates TypeScript definitions.

`bash
flags-cli pull [options]
`

Options:

| Option | Alias | Description | Required | Default |
|--------|-------|-------------|----------|---------|
| --key | -k | Publishable key | Yes* | - |
| --env | -e | Environment variable name | Yes* | - |
| --out | -o | Output file path | No | ./flags.d.ts |

\* Either --key or --env is required

Version

Check the CLI version:

`bash
flags-cli --version
`

Help

Display help information:

`bash
flags-cli --help
flags-cli pull --help
``

Related Packages

- @hauses/flags-core - Core SDK
- @hauses/react-sdk - React SDK

License

MIT

Support

- 📧 Email: jordi.casas004@gmail.com
- 🌐 Website: flags.hauses.dev
- 📖 Documentation: flags.hauses.dev/docs
- 🐛 Issues: GitHub Issues

---

Part of the Flags SDK monorepo.