FlipFlag CLI

FlipFlag CLI is a lightweight command-line tool for managing feature flags and tracking development tasks directly in your repository.

Key Features

• 📋 Task Management: Start and stop work sessions with time tracking
• 🔄 Flag Synchronization: Upload feature flags to FlipFlag platform
• 🌿 Git Integration: Automatically create/switch Git branches
• ⏱️ Time Tracking: Record when features are being worked on
• 👥 Team Collaboration: Store contributor information from Git
• 🚀 CI/CD Ready: Integrate with GitLab, GitHub Actions, CircleCI, and more

FlipFlag CLI stores all data in a local .flipflag.yml file, making it easy to version control your feature flags alongside your code.

---

🚀 Installation

Install globally:

npm install -g @flipflag/cli

Or install locally:

npm install @flipflag/cli --save-dev

Run with:

flipflag

---

📄 .flipflag.yml Format

This file is created automatically when you run the first flipflag start command.

Example:

TASK-1:
  description: ""
  contributor: "dev@example.com"
  type: "feature"
  times:
    - started: "2025-01-01T10:00:00.000Z"
      finished: "2025-01-01T12:30:00.000Z"
    - started: "2025-01-02T09:00:00.000Z"
      finished: null

---

🧭 Commands

FlipFlag CLI provides three main commands:

1. start - Start working on a task
2. stop - Stop working on a task
3. sync - Upload feature flags to FlipFlag API

---

▶️ Start a Task

flipflag start TASK-1

If TASK-ID is missing, the CLI will ask you to enter it interactively.

During startup, you may be prompted to choose:

• task type (feature or bugfix)
• whether to create/switch to a Git branch
• whether to enable time tracking

Start with flags (non-interactive)

flipflag start TASK-2 --type=bugfix --branch --time

Start without time tracking

flipflag start TASK-3 --no-time

---

⏹ Stop a Task

Stops the last open time interval:

flipflag stop TASK-1

If the ID is omitted, you will be asked to enter it.

---

🌿 Git Branching Rules

If the --branch flag is enabled:

• feature → creates/uses branch: feature/TASK-ID
• bugfix → creates/uses branch: bugfix/TASK-ID

Behavior:

• if branch exists → switches to it
• if branch does not exist → creates it and switches to it

---

🕒 Time Tracking

If --time is enabled, then flipflag start will:

1. create a time entry with { started, finished: null };
2. wait until you press Enter;
3. write the finished timestamp.

Example:

flipflag start TASK-5
# ...work...
# press Enter to stop tracking

---

🧩 Start Command Flags

Flag	Description
--type=feature / --type=bugfix	Task type
--branch	Create/switch Git branch
--no-branch	Do not touch Git branches
--time	Enable time tracking
--no-time	Disable time tracking

---

🛠 Stop Command

flipflag stop TASK-ID

Closes the latest unfinished time interval.

---

🔄 Sync Command

Upload feature flags from .flipflag.yml to FlipFlag platform:

flipflag sync --private-key "your_private_key"

Using Environment Variables (Recommended)

export FLIPFLAG_PRIVATE_KEY="your_private_key"
flipflag sync

Sync Command Options

Option	Environment Variable	Description	Required
--private-key KEY	FLIPFLAG_PRIVATE_KEY	Private API key	✅ Yes
--public-key KEY	FLIPFLAG_PUBLIC_KEY	Public API key	❌ No
--api-url URL	FLIPFLAG_API_URL	API endpoint	❌ No
--config PATH	-	Config file path	❌ No

Sync Examples

# Basic sync
export FLIPFLAG_PRIVATE_KEY="priv_abc123..."
flipflag sync

# Custom config file
flipflag sync --config .flipflag.production.yml

# Self-hosted API
flipflag sync --api-url "https://flipflag.your-company.com"

CI/CD Integration

GitLab CI/CD:

sync-features:
  stage: sync
  image: node:20-alpine
  only:
    - main
  script:
    - npm install -g @flipflag/cli
    - flipflag sync --private-key "$FLIPFLAG_PRIVATE_KEY"

GitHub Actions:

- name: Sync Feature Flags
  run: |
    npm install -g @flipflag/cli
    flipflag sync --private-key "${{ secrets.FLIPFLAG_PRIVATE_KEY }}"

📚 Complete CI/CD Guide: See CLI_SYNC.md for detailed integration examples with GitLab, GitHub Actions, CircleCI, Jenkins, and Azure Pipelines.

---

🆘 Help

flipflag help

---

📌 Examples

Typical workflow

flipflag start TASK-10 --type=feature --branch --time
# press Enter when done...
flipflag stop TASK-10

Create a task without time tracking

flipflag start TASK-21 --no-time --no-branch

---

🔧 Environment Variables

If Git email is not configured, Flipflag will use:

FLIPFLAG_USER="myname@example.com"

---

📦 Using Locally via npx

npx flipflag start TASK-1

---

📚 Documentation

• Feature Flag Sync Guide - Complete guide for syncing flags and CI/CD integration
• CI/CD Examples - Ready-to-use configurations for various platforms
• FlipFlag SDK - Client SDK for feature flag management

---

🔗 Links

• Website: https://flipflag.dev
• Dashboard: https://cloud.flipflag.dev
• Documentation: https://docs.flipflag.dev
• GitHub: https://github.com/flipflag-dev/cli
• NPM: https://www.npmjs.com/package/@flipflag/cli

---

📝 License

MIT

---

Made with ❤️ by the FlipFlag team