Markdown-first experiment files
Each flag, holdout, staged rollout, or A/B test is represented as a single `.md` file in `dif/`, making the configuration readable, diffable, and easy to review in pull requests.
dif.sh
dif.sh manages feature flags, A/B tests, holdouts, and staged rollouts in Markdown. Use its CLI to build, validate, and review experiments.
Feature flags and experiments in your repo
Dif.sh is a developer tool for feature flags, A/B tests, holdouts, and staged rollouts that live in your repository as Markdown files. The core workflow is built around a small CLI, a `dif/` folder checked into git, and generated runtime artifacts that your app can import.
The product is designed for teams that want experiment definitions, rollout rules, and experiment history to stay close to code review. The local workflow runs from the terminal, while Dif Cloud adds a shared live view of metrics, confidence intervals, and decision proposals for teams that want centralized analysis without moving the source of truth out of the repo.
Core features
Repo-based CLI workflow
`dif init`, `dif new`, `dif validate`, `dif build`, `dif qa`, and `dif conclude` cover the full lifecycle from scaffolding to cleanup without leaving the terminal.
Generated runtime artifacts
`dif build` compiles active experiments into a typed client and `dif/context.json`, so the app can render variants locally while the agent reads the shared experiment context on session start.
Runtime audience targeting
Audience rules are declared in config and resolved at runtime from user attributes such as country, plan, or returning_visitor, rather than from a committed customer list.
Validation and conflict detection
Build-time checks catch conflicts, missing tests, invalid frontmatter, and exclusion-group collisions before changes reach production.
Cloud analytics and review flow
Dif Cloud adds team-facing metrics, lift calculations, confidence intervals, and pull-request-based decision proposals while keeping git as the source of truth.
Practical ways teams use dif.sh
Keep experiment definitions close to code
Store active experiments in `dif/experiments/active/`, review them in pull requests, and keep concluded work in the repo for later reference.
Catch rollout mistakes before release
Draft, validate, and compile an experiment before rollout so conflicts, missing tests, and invalid frontmatter fail in CI rather than in production.
Target variants with runtime attributes
Use audience attributes such as country, plan, or returning_visitor to target a variant without committing a customer list to the repository.
Share experiment context with agents
Generate `dif/context.json` and let coding agents read the current experiment state on session start so prior learnings carry into the next change.
Coordinate decisions across a team
Use Dif Cloud when a team wants exposure counts, lift over time, confidence intervals, and a proposed decision written back as a pull request.
Pros and Cons
Pros
- Experiment definitions stay in git as Markdown, which makes them reviewable in PRs and easy to version alongside code.
- The CLI supports the full lifecycle: setup, drafting, validation, build, QA preview, and concluding experiments.
- `dif build` checks for conflicts and exclusion-group collisions before deployment, helping catch unsafe combinations in CI.
- The runtime client is generated from the repo, so production does not need to call a separate service to pick a variant.
- Dif Cloud can summarize lift, confidence intervals, exposure data, and decisions for the wider team while preserving the repo as the system of record.
Cons
- The pricing page content in the collected sources did not provide a full plan breakdown, so exact paid-plan details are unclear from the evidence provided.
- Cloud-specific analytics and team views appear to be separate from the core repo/CLI workflow, so teams that want lift calculations or shared metrics need to use Dif Cloud.
- The shell installer is limited to macOS and Linux, and the framework packages require Node 20.6+.
FAQ
How do you get started with dif.sh?
Dif.sh is set up from the repo root with the CLI. The docs show `dif init` creating the `dif/` workspace, then `dif new`, `dif validate`, `dif build`, and `dif qa` as the main workflow. The CLI is designed to run in a repo and does not open a browser or require logging in for the core local workflow.
What does Dif Cloud cost?
The source pages describe two layers: the CLI and SDK stay free, while Dif Cloud is a paid service for shared metrics, lift calculations, and a team view of experiments. The pricing page shown in the collected text did not contain plan details, but the Cloud page states that $50 a month includes 1 million events and every seat.
Where does dif.sh keep experiments?
Dif.sh stores experiments as Markdown files in a `dif/` folder checked into git. Active experiments live under `dif/experiments/active/`, concluded experiments move to `dif/experiments/concluded/`, and surfaces and context are tracked alongside them in the repo.
What does Dif Cloud add beyond the repo-only workflow?
Dif Cloud reads the repository and turns each Markdown experiment into a live view with exposures, lift, confidence intervals, and a ready-to-conclude flag. It also writes proposed decisions back as pull requests so the repo remains the source of truth.
What platforms does dif.sh support?
The docs indicate support for the npm wrapper, which works anywhere Node 18+ runs, and the SDK and framework packages require Node 20.6+. The shell installer is available for macOS and Linux, and Homebrew is also supported on macOS and Linux.
Quick Facts
- Category
- Developer Tool
- Core model
- Feature flags and A/B tests stored as Markdown in git
- Primary interface
- CLI plus generated SDK/runtime client
- Repo layout
- `dif/` folder with experiments, surfaces, audiences, config, context, and generated files
- Supported install paths
- Shell installer, Homebrew, and npm wrapper
- Platform notes
- Shell installer: macOS/Linux; npm wrapper: Node 18+; SDK/framework packages: Node 20.6+
dif.sh Alternatives
OpenFlags
OpenFlags is an open-source, self-hosted feature flag platform for JavaScript teams, with local evaluation, targeted rollouts, and controlled launches.
ByteAsk
ByteAsk is a terminal-first AI coding agent for C and C++ that edits repos and verifies changes with compilers, debuggers, sanitizers, and tests.
CreateOS Sandbox
CreateOS Sandbox is an isolated compute environment for running code and agent workloads in Firecracker micro-VMs with private networking and SDK, CLI, or MCP control.
Codex Plugins
Codex Plugins bundle reusable skills, app integrations, and MCP servers into workflows you can install in the Codex app or use from Codex CLI.
Struere
Struere turns spreadsheet data into structured operational software with dashboards, alerts, and automations for teams replacing manual spreadsheet workflows.
hob
hob is an independent workspace for coding agents, with local control over sessions, terminals, history, routing, and follow-up work.