{"id":17438,"library":"flagsmith-cli","title":"Flagsmith CLI","description":"The `flagsmith-cli` is a command-line interface tool designed to fetch feature flags and environment configurations from the Flagsmith API. Its primary use case is to generate a local JSON file, typically `flagsmith.json`, which can then be baked into an application as default flag state. This enables defensive coding practices, provides offline support, and facilitates CI/CD integration for feature flag management. The current stable version is `0.2.3`. Releases occur on an as-needed basis, focusing on bug fixes, dependency updates, and minor feature additions. The CLI is built on Oclif and ships with TypeScript types, targeting Node.js environments `>=12.0.0`. It serves as a crucial component for applications leveraging Flagsmith in scenarios requiring static flag data.","status":"active","version":"0.2.3","language":"javascript","source_language":"en","source_url":"https://github.com/Flagsmith/flagsmith-cli","tags":["javascript","oclif","typescript"],"install":[{"cmd":"npm install flagsmith-cli","lang":"bash","label":"npm"},{"cmd":"yarn add flagsmith-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add flagsmith-cli","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { flagsmith } from 'flagsmith-cli'","symbol":"flagsmith","correct":"npx flagsmith get"},{"note":"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.","wrong":"const state = require('./flagsmith.json')","symbol":"FlagsmithState","correct":"import state from './flagsmith.json'"},{"note":"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.","wrong":"import { Flagsmith } from 'flagsmith'","symbol":"flagsmith","correct":"import flagsmith from 'flagsmith'"}],"quickstart":{"code":"// 1. Install the CLI as a dev dependency\n// npm install flagsmith-cli --save-dev\n\n// 2. In your CI/CD or package.json \"postinstall\" script,\n//    set the environment key and run the CLI to fetch flags.\n//    (Replace 'YOUR_FLAGSMITH_ENVIRONMENT_KEY' with your actual key or use process.env)\n\n// Example using a shell command (e.g., in a CI script or `npm run get-flags`):\n// export FLAGSMITH_ENVIRONMENT=\"${process.env.FLAGSMITH_ENVIRONMENT_KEY ?? 'YOUR_FLAGSMITH_ENVIRONMENT_KEY'}\"\n// npx flagsmith get --output ./src/flagsmith.json --pretty\n\n// 3. In your application code (e.g., src/main.ts or src/App.tsx):\nimport flagsmith from 'flagsmith'; // Flagsmith client SDK (install separately: npm install flagsmith)\nimport state from './flagsmith.json'; // The JSON file generated by flagsmith-cli\n\nasync function initializeFlagsmith() {\n  await flagsmith.init({\n    state, // Initial state fetched by the CLI\n    environmentID: state.environmentID, // Extracted from the generated JSON\n    // If you need the SDK to fetch live flags later, ensure API URL is correct:\n    // apiUrl: 'https://edge.api.flagsmith.com/api/v1/', // Default Flagsmith API\n  });\n\n  console.log('Flagsmith initialized with default state.');\n\n  // Example: Check a feature flag\n  const myFeatureEnabled = flagsmith.hasFeature('example_feature_name');\n  console.log(`Is 'example_feature_name' enabled? ${myFeatureEnabled}`);\n\n  // Get a flag value\n  const welcomeMessage = flagsmith.getValue('welcome_message');\n  console.log(`Welcome message: ${welcomeMessage}`);\n}\n\ninitializeFlagsmith();","lang":"typescript","description":"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."},"warnings":[{"fix":"Ensure `FLAGSMITH_ENVIRONMENT` is set in your shell/CI environment, or use `flagsmith get YOUR_ENVIRONMENT_KEY`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Include `-i <value>` or `--identity=<value>` when using any `-t <trait_key>=<trait_value>` flag.","message":"When fetching flags for a specific identity using the `--trait` flag, you must also provide the `--identity` flag. Traits cannot be fetched in isolation.","severity":"gotcha","affected_versions":">=0.1.2"},{"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/`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Use the `-o <value>` or `--output=<value>` flag to set the desired output file path, e.g., `--output ./src/flagsmith.ts`.","message":"The default output file is `./flagsmith.json`. If this file path is not suitable for your project structure, ensure you specify a different output.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Add the `-i <identity_value>` or `--identity=<identity_value>` flag when using `-t <trait_key>=<trait_value>`.","cause":"Attempting to fetch flags with traits without specifying an identity.","error":"Missing required flag: --identity when using --trait"},{"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.","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.","error":"Error: Cannot find module './flagsmith.json'"},{"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`.","cause":"The Flagsmith environment key was neither provided as an argument to the `get` command nor set in the `FLAGSMITH_ENVIRONMENT` environment variable.","error":"Error: No environment key provided. Please set FLAGSMITH_ENVIRONMENT or pass it as an argument."}],"ecosystem":"npm","meta_description":null}