Secretlint CLI for Secret Detection

Common errors

• Error: Node.js v18.17.1 is not supported. secretlint requires Node.js v22.0.0 or later.

  cause Running secretlint with an unsupported Node.js version.
  fix Upgrade your Node.js environment to version 22 or higher using `nvm install 22 && nvm use 22` or similar version management tools.

• zsh: no matches found: "**/*"

  cause The shell attempted to expand the glob pattern before passing it to secretlint, and found no matches, or interpreted it incorrectly.
  fix Ensure glob patterns are enclosed in double quotes when used in the terminal: `secretlint "**/*"`.

• Failed to load config file: .secretlintrc.json. Error: Failed to parse JSON file

  cause The `.secretlintrc.json` file is either missing, has incorrect JSON syntax, or is not accessible.
  fix Run `npx secretlint --init` to create a default configuration, or carefully check your `.secretlintrc.json` file for syntax errors.

• ReferenceError: SecretlintCoreResult is not defined

  cause Attempting to use a type or function from the `secretlint` package programmatically without a proper ES module import statement.
  fix Ensure you are using `import { SecretlintCoreResult } from 'secretlint';` for TypeScript or CommonJS equivalent when using programmatically.

Warnings

• breaking 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.
  Fix: Upgrade your Node.js environment to version 22 or newer.
• breaking 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.
  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.
• gotcha 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.
  Fix: Always quote glob patterns: `secretlint "source/**/*.js"` instead of `secretlint source/**/*.js`.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install secretlint npm
• yarn add secretlint yarn
• pnpm add secretlint pnpm

Imports

• run
  wrong:

  const run = require('secretlint').run;

  correct:

  import { run } from 'secretlint';

  The primary function for programmatic execution of the Secretlint CLI logic. Typically used in scripts or custom runners.
• SecretlintCoreResult

  import { SecretlintCoreResult } from 'secretlint';

  TypeScript type for the structured result object returned by linting operations, useful for programmatic analysis. Re-exported from `@secretlint/core`.
• loadConfig

  import { loadConfig } from 'secretlint';

  Function to programmatically load Secretlint configuration files (e.g., `.secretlintrc.json`). Re-exported from `@secretlint/config-loader`.
• SecretlintCLIOptions

  import { SecretlintCLIOptions } from 'secretlint';

  TypeScript type defining the structure of options that can be passed to the `run` function, mirroring CLI arguments. Re-exported from `@secretlint/shared-type`.

Quickstart

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.

import { run } from 'secretlint';
import * as fs from 'node:fs/promises';
import * as path from 'node:path';

const tempDir = path.join(process.cwd(), '.secretlint-temp');
const tempFile = path.join(tempDir, 'example.js');
const configFile = path.join(tempDir, '.secretlintrc.json');

async function quickstart() {
  await fs.mkdir(tempDir, { recursive: true });
  await fs.writeFile(tempFile, 'const secretKey = "sk_live_YOUR_SECRET_KEY_123";');
  await fs.writeFile(configFile, JSON.stringify({
    "rules": [
      {
        "id": "@secretlint/secretlint-rule-preset-recommend",
        "rule": "@secretlint/secretlint-rule-preset-recommend"
      }
    ]
  }, null, 2));

  try {
    console.log('Running secretlint CLI via npx:');
    // Using child_process for CLI demo, or `run` for programmatic
    const { execa } = await import('execa'); // Using dynamic import for execa
    const cliResult = await execa('npx', [
      'secretlint',
      tempFile,
      '--secretlintrc', configFile,
      '--format=stylish'
    ], { reject: false, cwd: tempDir });
    console.log(cliResult.stdout);
    if (cliResult.exitCode === 1) {
      console.log('CLI detected secrets and exited with code 1.');
    } else {
      console.log('CLI finished, no secrets detected or --output was used.');
    }

    console.log('\nRunning secretlint programmatically with `run` function:');
    const programmaticResult = await run([tempFile], {
      cwd: tempDir,
      secretlintrc: configFile,
      format: 'mask-result'
    });
    console.log(programmaticResult.output);

    if (programmaticResult.ok === false) {
      console.log('Programmatic run detected secrets.');
    } else {
      console.log('Programmatic run finished, no secrets detected.');
    }

  } catch (error) {
    console.error('An error occurred:', error);
  } finally {
    await fs.rm(tempDir, { recursive: true, force: true });
  }
}

quickstart();