{"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,"search_vec":"'0.2.3':72 '12.0.0':105 'addit':90 'api':25 'applic':46,113 'as-need':77 'bake':43 'basi':80 'bug':83 'built':94 'case':29 'ci/cd':61 'cli':2,6,92 'code':54 'command':10 'command-lin':9 'compon':111 'configur':21 'crucial':110 'current':68 'data':121 'default':48 'defens':53 'depend':85 'design':14 'enabl':52 'environ':20,104 'facilit':60 'featur':17,64,89 'fetch':16 'file':36 'fix':84 'flag':18,49,65,120 'flagsmith':1,5,24,115 'flagsmith-c':4 'flagsmith.json':38 'focus':81 'generat':32 'integr':62 'interfac':12 'javascript':122 'json':35 'leverag':114 'line':11 'local':34 'manag':66 'minor':88 'need':79 'node.js':103 'occur':74 'oclif':96,123 'offlin':57 'practic':55 'primari':27 'provid':56 'releas':73 'requir':118 'scenario':117 'serv':107 'ship':98 'stabl':69 'state':50 'static':119 'support':58 'target':102 'tool':13 'type':101 'typescript':100,124 'typic':37 'updat':86 'use':28 'version':70","created_at":"2026-04-22T17:41:44.574118+00:00","updated_at":"2026-04-22T17:41:44.574118+00:00","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,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"flagsmith","cli_version":null,"type":"library","homepage":"https://flagsmith.com","github":"https://github.com/Flagsmith/flagsmith-cli","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/flagsmith-cli","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-21","install_tag":null}}