Flagsmith CLI

Common errors

• Missing required flag: --identity when using --trait

  cause Attempting to fetch flags with traits without specifying an identity.
  fix Add the `-i <identity_value>` or `--identity=<identity_value>` flag when using `-t <trait_key>=<trait_value>`.

• Error: Cannot find module './flagsmith.json'

  cause The generated `flagsmith.json` file is not found at the specified import path, or your module resolver is not configured to handle JSON imports.
  fix Verify the `--output` path used during CLI execution matches your import path. Ensure your build tool (e.g., webpack, esbuild, TypeScript) is configured to handle JSON file imports.

• Error: No environment key provided. Please set FLAGSMITH_ENVIRONMENT or pass it as an argument.

  cause The Flagsmith environment key was neither provided as an argument to the `get` command nor set in the `FLAGSMITH_ENVIRONMENT` environment variable.
  fix Set the `FLAGSMITH_ENVIRONMENT` environment variable (e.g., `export FLAGSMITH_ENVIRONMENT='your_key'`) or pass the key directly as an argument: `flagsmith get your_key`.

Warnings

• gotcha The Flagsmith environment key is mandatory. It must either be provided via the `FLAGSMITH_ENVIRONMENT` environment variable or passed directly as an argument to the `flagsmith get` command.
  Fix: Ensure `FLAGSMITH_ENVIRONMENT` is set in your shell/CI environment, or use `flagsmith get YOUR_ENVIRONMENT_KEY`.
• gotcha When fetching flags for a specific identity using the `--trait` flag, you must also provide the `--identity` flag. Traits cannot be fetched in isolation.
  Fix: Include `-i <value>` or `--identity=<value>` when using any `-t <trait_key>=<trait_value>` flag.
• gotcha The CLI defaults to `https://edge.api.flagsmith.com/api/v1/` for the API URL. If you are self-hosting Flagsmith or using a different region, you must specify the correct API URL.
  Fix: Use the `-a <value>` or `--api=<value>` flag to specify your custom Flagsmith API endpoint, e.g., `--api https://your.custom.flagsmith.com/api/v1/`.
• gotcha The default output file is `./flagsmith.json`. If this file path is not suitable for your project structure, ensure you specify a different output.
  Fix: Use the `-o <value>` or `--output=<value>` flag to set the desired output file path, e.g., `--output ./src/flagsmith.ts`.

Install

• npm install flagsmith-cli npm
• yarn add flagsmith-cli yarn
• pnpm add flagsmith-cli pnpm

Imports

• flagsmith
  wrong:

  import { flagsmith } from 'flagsmith-cli'

  correct:

  npx flagsmith get

  This package is a command-line interface tool; its primary interaction is via terminal commands, not JavaScript imports. `npx` is recommended for running local installations of the CLI.
• FlagsmithState
  wrong:

  const state = require('./flagsmith.json')

  correct:

  import state from './flagsmith.json'

  The CLI generates a JSON file. This is how you import its contents into a JavaScript/TypeScript application, assuming your build setup supports JSON imports.
• flagsmith
  wrong:

  import { Flagsmith } from 'flagsmith'

  correct:

  import flagsmith from 'flagsmith'

  This refers to the separate `flagsmith` client SDK package, which consumes the output of `flagsmith-cli`. You must install `flagsmith` separately if you intend to use it in your application.

Quickstart

Demonstrates installing the CLI, fetching flags into a `flagsmith.json` file, and then importing and initializing the Flagsmith client with these default flags for application use.

// 1. Install the CLI as a dev dependency
// npm install flagsmith-cli --save-dev

// 2. In your CI/CD or package.json "postinstall" script,
//    set the environment key and run the CLI to fetch flags.
//    (Replace 'YOUR_FLAGSMITH_ENVIRONMENT_KEY' with your actual key or use process.env)

// Example using a shell command (e.g., in a CI script or `npm run get-flags`):
// export FLAGSMITH_ENVIRONMENT="${process.env.FLAGSMITH_ENVIRONMENT_KEY ?? 'YOUR_FLAGSMITH_ENVIRONMENT_KEY'}"
// npx flagsmith get --output ./src/flagsmith.json --pretty

// 3. In your application code (e.g., src/main.ts or src/App.tsx):
import flagsmith from 'flagsmith'; // Flagsmith client SDK (install separately: npm install flagsmith)
import state from './flagsmith.json'; // The JSON file generated by flagsmith-cli

async function initializeFlagsmith() {
  await flagsmith.init({
    state, // Initial state fetched by the CLI
    environmentID: state.environmentID, // Extracted from the generated JSON
    // If you need the SDK to fetch live flags later, ensure API URL is correct:
    // apiUrl: 'https://edge.api.flagsmith.com/api/v1/', // Default Flagsmith API
  });

  console.log('Flagsmith initialized with default state.');

  // Example: Check a feature flag
  const myFeatureEnabled = flagsmith.hasFeature('example_feature_name');
  console.log(`Is 'example_feature_name' enabled? ${myFeatureEnabled}`);

  // Get a flag value
  const welcomeMessage = flagsmith.getValue('welcome_message');
  console.log(`Welcome message: ${welcomeMessage}`);
}

initializeFlagsmith();