# Migrate from Code Analyzer v4 to v5

Code Analyzer v5 is more intuitive and powerful than v4, but the configuration and CLI commands work a bit differently. This document helps you migrate.

:::important
As of August 2025, Code Analyzer v4 is retired and we no longer support it.
:::

## Install Code Analyzer V5

To install the Salesforce Code Analyzer plugin, run:

```bash
sf plugins install @salesforce/plugin-code-analyzer
```

## Changes in the CLI Commands

The most obvious high-level change between the Code Analyzer v4 and v5 CLI commands is that v4 commands are in the `scanner` topic and v5 commands in the `code-analyzer` topic. For example:

**v4**:

```bash
sf scanner run --category Security
```

**v5**:

```bash
sf code-analyzer run --rule-selector Security
```

We also reduced the six v4 commands to just three in v5: `code-analyzer run|rules|config`. This table summarizes the changes.

| v4 Command              | v5 Equivalent Command                    | Notes about v5 Equivalent                                                                                   |
| ----------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `scanner rule add`      | No equivalent.                           | Add custom rules to the `code-analyzer.yml` configuration file.                                             |
| `scanner rule describe` | `code-analyzer rules --view detail`      | Use the `--rule-selector` flag to select a specific rule or rules.                                          |
| `scanner rule list`     | `code-analyzer rules`                    | Use the `--rule-selector` flag to select a specific rule or rules.                                          |
| `scanner rule remove`   | No equivalent.                           | Remove custom rules by removing them from the `code-analyzer.yml` configuration file.                       |
| `scanner run`           | `code-analyzer run`                      |                                                                                                             |
| `scanner run dfa`       | `code-analyzer run --rule-selector sfge` | Use the same command (`code-analyzer run`) to run rules for all engines, including Salesforce Graph Engine. |

Another high-level change is that in v5, the three commands share many of the same flags for:

- Selecting the rules (`--rule-selector`).
- Selecting the set of files you want to include in your analysis (`--workspace`).
- Specifying the path to the configuration file (`--config-file`).

As a result, executing the three v5 commands is essentially the same whether you want to list rules, run rules, or view your configuration.

The v5 CLI commands now have a single flag (`--rule-selector`) for selecting the rules you want to list or run on your source code. With this single flag you can select rules based on their name, engine, severity level, and tags. And more importantly, you can *combine* these properties in many different ways so as to select exactly what you want. It's a powerful flag. But it's also different from how v4 CLI commands worked, which had multiple flags such as `--engine` or `--category`.

Finally, another big change: v5 introduces a configuration YAML file (`code-analyzer.yml`) which you can use to configure top-level properties and customize rules and engines, including adding custom rules. See [Customize the v5 Configuration](/docs/platform/salesforce-code-analyzer/guide/config-custom.md) for details.

## Changes in the Code Analyzer VS Code Extension

The Salesforce Code Analyzer Visual Studio Code (VS Code) extension integrates many of Code Analyzer’s most useful features into VS Code. The extension has its own versioning, separate from core Code Analyzer. As Code Analyzer transitioned from v4 to v5, here's how the extension supported each version:

- Version 1.3.0 and smaller: The extension supported only Code Analyzer v4.
- Version 1.4.0 and 1.5.0: The extension supported both Code Analyzer v4 and v5, but v4 was enabled by default.
- Version 1.6.0 - 1.9.0: The extension supported both Code Analyzer v4 and v5, but v5 was enabled by default.
- Version 1.10.0 and greater: The extension supports only Code Analyzer v5.

This section describes the high-level differences in the extension between supporting v4 and v5. For simplicity, we call the extension support for Code Analyzer v4 simply *v4*, same with *v5*.

- In v4, Salesforce Graph Engine had its own specialized commands for running a scan (**SFDX: Scan Selected Method with Graph Engine Path-Based Analysis** and **SFDX: Scan Project with Graph Engine Path-Based Analysis**).

  In v5, we removed these specialized commands. Instead, Salesforce Graph Engine works just like the other engines and you use the [same commands to run a scan](/docs/platform/salesforce-code-analyzer/guide/analyze-vscode.md#launch-code-analyzer-and-scan-your-code): **SFDX: Scan Current File with Code Analyzer** or **SFDX: Scan Selected Files or Folders with Code Analyzer**.

- In v4, you used various VS Code settings to customize your code scans. For example, you used settings to specify the engines and categories of rules to use in code scans, configure Salesforce Graph Engine, normalize the severity across engines, and more.

  In v5, many of the v4 settings are gone. New v5 settings mirror how the v5 `code-analyzer` CLI commands work.

  For example, you use the **Code Analyzer: Config File** setting to [customize all engines and rules](/docs/platform/salesforce-code-analyzer/guide/config-custom.md), including Salesforce Graph Engine; this VS Code command is equivalent to the `--config-file` CLI flag. Use **Code Analyzer: Rule Selectors** to [select the rules to scan your code](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_code-analyzer_commands_unified.htm#cli_reference_code-analyzer_rules_unified), similar to the `--rule-selector` flag.

  These v4 settings are still available in v5:

  - Scan files on open automatically.
  - Scan files on save automatically.
  - Enable Apex Guru (Pilot).

## Migrate a Custom PMD Configuration

In v4, if you specify a PMD ruleset file with the `--pmdconfig` flag of `scanner run`, only the rules in the ruleset actually run. You can't also run other PMD rules that aren't specified in the ruleset.

But with v5, when you specify your ruleset file in your `code-analyzer.yml` file, the rules in the ruleset are added to the full list of PMD rules that you can select and run. To make selection of your ruleset rules easy, we add a tag to each rule that matches the `name` attribute of your ruleset, minus any spaces.

For example, let's say your PMD ruleset file looks like this:

```XML
<ruleset name="My Rules"
    xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 https://pmd.sourceforge.io/ruleset_2_0_0.xsd">

    <!-- Your list of rules-->

</ruleset>
```

Then each rule in the ruleset file is tagged with `MyRules`.

Follow these steps to mimic the v4 behavior of `sf scanner rule --pmdconfig path/to/my/ruleset.xml` in v5:

1. As described in [Add Custom PMD Rules](/docs/platform/salesforce-code-analyzer/guide/engine-pmd.md#add-custom-pmd-rules), update your `code-analyzer.yml` file like this:

   ```yaml
   engines:
     pmd:
       custom_rulesets:
         - path/to/my/ruleset.xml
   ```

2. Run this command to ensure that your custom rules are available.

   ```bash
   sf code-analyzer rules --rule-selector pmd
   ```

   Your PMD rules have up to two new tags added. The first tag is the name of your ruleset, with spaces removed. This tag is added to all rules, including the standard PMD rules that are referenced in your ruleset. The second tag is `Custom`, which is added to only the custom non-standard PMD rules in your ruleset.

3. Run all the rules in your ruleset by specifying the `  --rule-selector pmd:<RuleSetNameWithoutSpaces> ` flag.

   ```bash
   sf code-analyzer run --rule-selector pmd:MyRules
   ```

   Be sure the `code-analyzer.yml` file is either in your local directory or you use the `--config-file` flag to specify it.

In v5, you can do more than just run the rules in your ruleset. This example shows how to run all the Recommended rules in addition to the rules from your ruleset file:

```bash
sf code-analyzer run --rule-selector Recommended --rule-selector pmd:MyRules
```

## Migrate a Custom ESLint Configuration

In v4, you specify custom ESLint rules by pointing to your `.eslintrc.json` file with the `--eslintconfig` flag of `scanner run`. But then you couldn't also run the recommended standard ESLint rules that run when you don't supply the `--eslintconfig` flag.

With v5, we allow you to supply your ESLint configuration either on its own or added alongside our recommended base configuration, assuming there are no configuration conflicts.

To mimic the v4 behavior in v5, provide your ESLint configuration file and turn off our recommended base configuration, as described by these steps:

1. If you haven't already, create a `code-analyzer.yml` configuration file and set these options in the `engine:eslint` section:

   ```yaml
   engines:
     eslint:
       eslint_config_file: <path-to-your-eslint-config-file>
       disable_javascript_base_config: true
       disable_lwc_base_config: true
       disable_typescript_base_config: true
   ```

   See [Add Custom ESLint Configuration and Rules](/docs/platform/salesforce-code-analyzer/guide/engine-eslint.md#add-custom-eslint-configuration-and-rules) for details.

2. Run this command to ensure that your custom ESLint rules are available.

   ```bash
   sf code-analyzer rules --rule-selector eslint
   ```

   Any new custom ESLint rules that are not already provided by the base configurations have the `Custom` tag added.

3. Run only your custom ESLint rules this way:

   ```bash
   sf code-analyzer run --rule-selector eslint:Custom
   ```

   Be sure the `code-analyzer.yml` file is either in your local directory or you use the `--config-file` flag to specify it.

If you want ESLint to merge your configuration with our recommended base configurations, then set the `disable_*_base_config` fields back to `false` while still supplying your `eslint_config_file`. This merging of configurations wasn't possible in v4. Then run this command:

```bash
sf code-analyzer run --rule-selector eslint
```

## Examples of Equivalent v4 and v5 Commands

Let's look at a few examples to get you started using the new v5 commands.

This v4 CLI command runs all the rules with the `Security` or `Performance` category:

```bash
sf scanner run --category Security,Performance
```

This is the v5 equivalent CLI command:

```bash
sf code-analyzer run --rule-selector Recommended:Security --rule-selector Recommended:Performance
```

It's a Salesforce CLI best practice to use multiple flags to specify multiple values, but this syntax also still works:

```bash
sf code-analyzer run --rule-selector Recommended:Security,Recommended:Performance
```

This v4 CLI command runs all the PMD rules in the `Security` category:

```bash
sf scanner run --engine pmd --category Security
```

This is the v5 equivalent:

```bash
sf code-analyzer run --rule-selector pmd:Security
```

Salesforce Graph Engine no longer has its own CLI command to run its rules; you instead use `code-analyzer run` just like with any other engine. Here's a v4 command to run a Graph Engine scan:

```bash
sf scanner run dfa --target ./myproject/main/default/classes/*.cls --projectdir ./myproject/
```

This is the equivalent v5 command:

```bash
sf code-analyzer run --rule-selector sfge --target ./myproject/main/default/classes/*.cls --workspace ./myproject/
```

## Examples of v5 Commands That You Can't Run Using v4

Due to the improved design of the v5 CLI commands, there are many useful scans that you can easily run in v5 that are impossible with v4 commands.

Run all the ESLint rules and any PMD rules with the `Security` category:

```bash
sf code-analyzer run --rule-selector eslint --rule-selector pmd:Security
```

Run only PMD's rules for the Apex language:

```bash
sf code-analyzer run --rule-selector pmd:Apex
```

Run only the rules that have severity 1 (critical), for all enabled engines:

```bash
sf code-analyzer run --rule-selector 1
```