FlagPilot setup CLI

Prepare an existing Node.js backend for FlagPilot feature controls. The CLI installs the SDK and gives your developer or coding agent instructions to wire it into your application. It does not automatically find features or rewrite business logic.

Requires Node.js 22.13+ and a backend directory containing package.json.

cd path/to/your/backend
npx @mayankatri/cli init

What happens during setup

1. Choose whether to install @mayankatri/node. Setup uses npm; decline if you already installed it or use another package manager.
2. Choose connect now or later. To connect now, get the FlagPilot API origin and a Testing environment key from Developer setup in your FlagPilot dashboard. Enter the key in the masked prompt; never put it in a shell command.
3. Setup saves .env.flagpilot with owner-only permissions and adds it to .gitignore. It checks configuration connectivity.
4. Setup generates .flagpilot/features.mjs and FLAGPILOT_INTEGRATION.md. These are an example declaration and implementation instructions—not a completed integration.

The managed FlagPilot dashboard/API deployment is pending. Use your own reachable FlagPilot API now, or choose connect later. The standard local API origin is http://localhost:4000, not dashboard port 3000. A deployed backend cannot reach your Mac through its own localhost.

What you or your coding agent must implement next

Read the generated FLAGPILOT_INTEGRATION.md and the full integration guide.

• Replace example-feature with a real feature name, stable key, description, and deliberate backup behavior. Declare only trusted user attributes your backend can supply; none are required for a simple switch.
• Load .env.flagpilot through your environment loader (the SDK does not load it itself).
• Initialize one SDK client and reuse it. Place flags.isEnabled(featureKey, context) after existing authentication/authorization and before the feature's work.
• Implement the false branch: preserve the old implementation, skip optional work, or return a normal unavailable response. Installation alone changes no application behavior.
• Close the SDK during shutdown. Start the backend, accept its discovered declaration, and enable it in Testing. New accepted features start off everywhere.
• Prove off/on/off behavior on your actual feature without restarting the backend. Then configure production secrets and deploy your integration normally.

For agent-assisted implementation, hand over this instruction:

Read FLAGPILOT_INTEGRATION.md and inspect this backend. Identify the requested feature and all its entry points. Declare it, initialize FlagPilot once, guard it using trusted context, preserve existing authorization and business logic, and verify both branches plus outage behavior. Ask me only for feature choices or backup behavior you cannot infer. Do not invent API keys or deploy without authorization.

Connect later and check

Run npx @mayankatri/cli init again when you have your origin and key. Existing generated files and existing connection files are preserved, not overwritten. If you need to change a saved connection, edit your ignored .env.flagpilot securely and restart the backend.

npx @mayankatri/cli check

This checks the saved local file against the API. Success proves configuration connectivity, not declaration acceptance, receipt delivery, or route integration. Ensure the key has config:read, declarations:write, and receipts:write capabilities for the complete workflow.

Configure FLAGPILOT_URL and FLAGPILOT_SERVER_KEY separately in your backend host's secret settings. Never commit the key, include it in frontend code, or use a NEXT_PUBLIC_ variable. The CLI does not upload your credentials or deploy your backend.

Files setup creates

| File | Purpose | Commit? | | ------------------------------- | ------------------------------------------- | ----------------- | | .env.flagpilot | Local API origin and secret key | No | | .gitignore addition | Prevents accidental key commits | Yes | | .flagpilot/features.mjs | Feature metadata you customize | Yes, after review | | FLAGPILOT_INTEGRATION.md | Developer/agent implementation instructions | Yes | | Dependency and lockfile changes | Installs the SDK if selected | Yes |

For a complete runnable example and SDK API reference, read the Node SDK documentation.