{"id":17060,"library":"secretlint","title":"Secretlint CLI for Secret Detection","description":"Secretlint is a powerful CLI tool designed for scanning codebases to detect and prevent the leakage of sensitive data like API keys, credentials, and private information. The current stable version is 12.2.0, with minor and patch releases occurring frequently, and major versions introducing breaking changes like Node.js engine requirements. It offers a highly extensible architecture through pluggable rules and presets (e.g., `@secretlint/secretlint-rule-preset-recommend`), supporting various file formats and offering multiple output formatters including `stylish`, `mask-result`, and `github` annotations. Key differentiators include its focus on precise secret detection, a flexible configuration system using `.secretlintrc` files, and the ability to mask secrets in output, making it suitable for CI/CD pipelines and pre-commit hooks.","status":"active","version":"12.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/secretlint/secretlint","tags":["javascript","secretlint","cli","typescript"],"install":[{"cmd":"npm install secretlint","lang":"bash","label":"npm"},{"cmd":"yarn add secretlint","lang":"bash","label":"yarn"},{"cmd":"pnpm add secretlint","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary function for programmatic execution of the Secretlint CLI logic. Typically used in scripts or custom runners.","wrong":"const run = require('secretlint').run;","symbol":"run","correct":"import { run } from 'secretlint';"},{"note":"TypeScript type for the structured result object returned by linting operations, useful for programmatic analysis. Re-exported from `@secretlint/core`.","symbol":"SecretlintCoreResult","correct":"import { SecretlintCoreResult } from 'secretlint';"},{"note":"Function to programmatically load Secretlint configuration files (e.g., `.secretlintrc.json`). Re-exported from `@secretlint/config-loader`.","symbol":"loadConfig","correct":"import { loadConfig } from 'secretlint';"},{"note":"TypeScript type defining the structure of options that can be passed to the `run` function, mirroring CLI arguments. Re-exported from `@secretlint/shared-type`.","symbol":"SecretlintCLIOptions","correct":"import { SecretlintCLIOptions } from 'secretlint';"}],"quickstart":{"code":"import { run } from 'secretlint';\nimport * as fs from 'node:fs/promises';\nimport * as path from 'node:path';\n\nconst tempDir = path.join(process.cwd(), '.secretlint-temp');\nconst tempFile = path.join(tempDir, 'example.js');\nconst configFile = path.join(tempDir, '.secretlintrc.json');\n\nasync function quickstart() {\n  await fs.mkdir(tempDir, { recursive: true });\n  await fs.writeFile(tempFile, 'const secretKey = \"sk_live_YOUR_SECRET_KEY_123\";');\n  await fs.writeFile(configFile, JSON.stringify({\n    \"rules\": [\n      {\n        \"id\": \"@secretlint/secretlint-rule-preset-recommend\",\n        \"rule\": \"@secretlint/secretlint-rule-preset-recommend\"\n      }\n    ]\n  }, null, 2));\n\n  try {\n    console.log('Running secretlint CLI via npx:');\n    // Using child_process for CLI demo, or `run` for programmatic\n    const { execa } = await import('execa'); // Using dynamic import for execa\n    const cliResult = await execa('npx', [\n      'secretlint',\n      tempFile,\n      '--secretlintrc', configFile,\n      '--format=stylish'\n    ], { reject: false, cwd: tempDir });\n    console.log(cliResult.stdout);\n    if (cliResult.exitCode === 1) {\n      console.log('CLI detected secrets and exited with code 1.');\n    } else {\n      console.log('CLI finished, no secrets detected or --output was used.');\n    }\n\n    console.log('\\nRunning secretlint programmatically with `run` function:');\n    const programmaticResult = await run([tempFile], {\n      cwd: tempDir,\n      secretlintrc: configFile,\n      format: 'mask-result'\n    });\n    console.log(programmaticResult.output);\n\n    if (programmaticResult.ok === false) {\n      console.log('Programmatic run detected secrets.');\n    } else {\n      console.log('Programmatic run finished, no secrets detected.');\n    }\n\n  } catch (error) {\n    console.error('An error occurred:', error);\n  } finally {\n    await fs.rm(tempDir, { recursive: true, force: true });\n  }\n}\n\nquickstart();","lang":"typescript","description":"Demonstrates initializing a basic `.secretlintrc.json` and then running `secretlint` both via the command line (using `npx`) and programmatically using the `run` function, showing secret detection and output masking."},"warnings":[{"fix":"Upgrade your Node.js environment to version 22 or newer.","message":"Secretlint v12.0.1 and later require Node.js version 22 or higher. Earlier Node.js versions are not supported and will cause runtime errors.","severity":"breaking","affected_versions":">=12.0.1"},{"fix":"Review your `secretlint` configuration and findings after upgrading. Add new `allow` rules or custom `.secretlintrc.json` configurations to suppress false positives or ignore newly detected secrets.","message":"Starting with Secretlint v12.0.0, new rules were added to the default `@secretlint/secretlint-rule-preset-recommend`. This means existing projects updating to v12 might suddenly report new secrets or issues that were not previously detected.","severity":"breaking","affected_versions":">=12.0.0"},{"fix":"Always quote glob patterns: `secretlint \"source/**/*.js\"` instead of `secretlint source/**/*.js`.","message":"When using glob patterns in shell commands (e.g., `bash`, `zsh`), you must wrap the patterns in double quotes (e.g., `secretlint \"**/*\"`). Failure to do so will cause your shell to expand the glob, potentially leading to errors like 'no matches found' or incorrect file processing.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"In CI/CD, if `--output` is used, explicitly check the output file for detected secrets or use a custom formatter that returns a non-zero exit code upon finding secrets if you need the pipeline to fail.","message":"The `--output` option fundamentally alters `secretlint`'s exit status. If `--output` is specified, `secretlint` will exit with status `0` (success) even if secrets are found. This can hide issues in CI/CD pipelines.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Thoroughly review initial scan results. Use the `allow` configuration in `.secretlintrc.json` to explicitly ignore known false positives. Customize rule sets to be more precise for your codebase.","message":"Secret detection inherently comes with a risk of false positives. Generic patterns can flag legitimate, non-secret data. Relying solely on default presets without review can lead to unnecessary alerts.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Upgrade your Node.js environment to version 22 or higher using `nvm install 22 && nvm use 22` or similar version management tools.","cause":"Running secretlint with an unsupported Node.js version.","error":"Error: Node.js v18.17.1 is not supported. secretlint requires Node.js v22.0.0 or later."},{"fix":"Ensure glob patterns are enclosed in double quotes when used in the terminal: `secretlint \"**/*\"`.","cause":"The shell attempted to expand the glob pattern before passing it to secretlint, and found no matches, or interpreted it incorrectly.","error":"zsh: no matches found: \"**/*\""},{"fix":"Run `npx secretlint --init` to create a default configuration, or carefully check your `.secretlintrc.json` file for syntax errors.","cause":"The `.secretlintrc.json` file is either missing, has incorrect JSON syntax, or is not accessible.","error":"Failed to load config file: .secretlintrc.json. Error: Failed to parse JSON file"},{"fix":"Ensure you are using `import { SecretlintCoreResult } from 'secretlint';` for TypeScript or CommonJS equivalent when using programmatically.","cause":"Attempting to use a type or function from the `secretlint` package programmatically without a proper ES module import statement.","error":"ReferenceError: SecretlintCoreResult is not defined"}],"ecosystem":"npm","meta_description":null}