> ## Documentation Index
> Fetch the complete documentation index at: https://semgrep-ee9d73d8-mintlify-b75b9a88.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Local scans with Semgrep

> Learn how to set up Semgrep, scan your project for security issues using Semgrep Code's interfile analysis, and view your findings in the CLI.

## Prerequisites

Before proceeding, see [Prerequisites](/prerequisites) to ensure that your machine meets Semgrep's requirements.

## Set up Semgrep

Install the Semgrep CLI tool and confirm the installation:

```bash theme={null}
# macOS users only - ensure that you've added Homebrew to your PATH
# https://docs.brew.sh/FAQ#my-mac-apps-dont-find-homebrew-utilities
brew install semgrep

# macOS, Linux, Windows users - using pipx (recommended)
# See https://pipx.pypa.io/stable/how-to/install-pipx/ to install pipx
pipx install semgrep

# Or, if you use uv (https://docs.astral.sh/uv/)
uv tool install semgrep

# confirm
semgrep --version
```

## Log in to your Semgrep account

<Steps>
  <Step>
    Log in to your Semgrep account. Running this command launches a browser window, but you can also use the link that's returned in the CLI to proceed:

    ```bash theme={null}
    semgrep login
    ```
  </Step>

  <Step>
    In the **Semgrep CLI login**, click **Activate** to proceed.
  </Step>
</Steps>

<Warning>
  **WARNING**

  Semgrep scans triggered using `semgrep ci` fail if you aren't signed in to your Semgrep account.
</Warning>

## Turn on cross-file analysis

To turn on [cross-file analysis](/semgrep-code/semgrep-pro-engine-intro), which allows you to detect vulnerabilities across files and folders:

<Steps>
  <Step>
    In Semgrep AppSec Platform, go to [Settings > General > Code](https://semgrep.dev/orgs/-/settings/general/code).
  </Step>

  <Step>
    Click the **Cross-file analysis** <Icon icon="toggle-large-on" iconType="solid" /> toggle to turn this feature on.
  </Step>
</Steps>

## Scan your project

Semgrep provides two commands that you can use to start a scan from the CLI:

* `semgrep scan` - This is the recommended command for [scanning local codebases or scanning a project when you don't have a Semgrep account](/getting-started/quickstart-ce). It is also recommended for [writing and testing custom rules](/writing-rules/testing-rules).
* `semgrep ci` - This is the recommended command if you are scanning Git repositories with Semgrep as part of an organization with custom rules and policies. `semgrep ci` fetches your organization's scan configurations from Semgrep AppSec Platform.

Navigate to the root of your codebase, and run your first scan. The specific command you use depends on how you want to view the results.

To view the results in the CLI:

```bash theme={null}
semgrep ci
```

To export the results to a plain text file:

```bash theme={null}
semgrep ci --text --text-output=semgrep.txt
```

To export the results to a SARIF file:

```bash theme={null}
semgrep ci --sarif --sarif-output=semgrep.sarif
```

To export the results to a JSON file:

```bash theme={null}
semgrep ci --json --json-output=semgrep.json
```

> The JSON schema for Semgrep's CLI output is in [semgrep/semgrep-interfaces](https://github.com/semgrep/semgrep-interfaces/blob/main/semgrep_output_v1.jsonschema).

In addition to the `--text`, `--json`, and `--sarif` flags, which set the primary output formats, and the `--output=<value>` flag that saves the results to a file or posts to a URL, you can append `--<format>-output=<file>` to obtain additional output streams:

```bash theme={null}
# prints findings in SARIF format to standard output and writes in JSON format to `findings.json`.
semgrep ci --sarif --json-output=findings.json

# prints findings in text to standard out and writes JSON output to `findings.json`.
semgrep ci --json-output=findings.json

# prints text output to `findings.txt` and writes in SARIF to `findings.sarif`.
semgrep ci --output=findings.txt --sarif-output=findings.sarif

# writes text to `semgrep.txt`, JSON to `semgrep.json`, and SARIF to `semgrep.sarif`.
semgrep ci --text --output=semgrep.txt --json-output=semgrep.json --sarif-output=semgrep.sarif
```

Accepted values for `<format>`: `text`, `json`, `sarif`, `gitlab-sast`, `gitlab-secrets`, `junit-xml`, `emacs`, `vim`

## Test custom rules

Semgrep includes features to [test the custom rules that you write](/writing-rules/testing-rules):

```bash theme={null}
semgrep scan --test
```

### Publish custom rules

To share your rules by adding them to the Semgrep Registry:

```bash theme={null}
semgrep publish <path/to/rules>
```

## Scan without sending results to Semgrep

To scan your project using the configuration you've set up in Semgrep AppSec Platform **without** sending scan results to Semgrep, use:

```bash theme={null}
semgrep ci --dry-run
```

This can help verify the results of a specific ruleset or see how your findings change based on the rulesets you choose for your scans.

## Scan using Semgrep CE analysis (single-function)

To scan your project using exclusively open source Semgrep, even though you have proprietary cross-file analysis enabled in Semgrep AppSec Platform:

```bash theme={null}
semgrep ci --oss-only
```

<Note>
  **INFO**

  See [Semgrep AppSec Platform versus Semgrep Community Edition](/semgrep-pro-vs-oss) for information on the differences between Semgrep's proprietary and open source analyses.
</Note>

## Scan using specific Semgrep products

When you run `semgrep ci`, you scan your project with any product that is enabled in Semgrep AppSec Platform. To scan your project with just one product, run:

```bash theme={null}
# scan with Semgrep Code
semgrep ci --code

# scan with Semgrep Supply Chain
semgrep ci --supply-chain

# scan with Semgrep Secrets
semgrep ci --secrets
```

## Extend timeout thresholds

Depending on the file sizes in your project, you may need to increase the timeout threshold so that Semgrep doesn't time out before the scan completes. You can control this value with the `--timeout` flag, which specifies the maximum time Semgrep spends scanning a single file. The default value is 5 seconds. Semgrep attempts to scan each file with this timeout value three times, but you can change this using the `--timeout-threshold` flag:

```bash theme={null}
# increase timeout to 45 seconds, try only 2 times
semgrep ci --timeout 45 --timeout-threshold 2
```

## Improve performance for large codebases

You can set the number of subprocesses Semgrep uses to run checks in parallel:

```bash theme={null}
semgrep scan -j NUMBER_OF_SUBPROCESSES
```

By default, the number of jobs Semgrep uses is equivalent to the number of cores detected on the system, but `-j = 1` if you're passing in `--pro`. For additional information, see [Parallelization](/kb/semgrep-code/scan-engine-kill).

## Set log levels

Semgrep provides three levels of logging:

| **Log level** | **Flag**            | **Description**                                                                                                             |
| :------------ | :------------------ | :-------------------------------------------------------------------------------------------------------------------------- |
| Default       | None                | Prints scan progress, findings information, warnings, and errors.                                                           |
| Verbose       | `-v` or `--verbose` | Includes everything printed when using the default logging level, adding a list of rules and details such as skipped files. |
| Debug         | `--debug`           | Logs the entire scan process at a high level of detail.                                                                     |

### Example usage

To set the logging level for a scan, include the flag when scanning your project:

```bash theme={null}
# run a scan and get debug logs
semgrep ci --debug
```

## Exit codes

The CLI commands `semgrep ci` and `semgrep scan` finish with exit code `0` as long as the scan completes, regardless of whether there were findings. To finish with exit code `1` when there are findings:

* [Configure blocking rules](/semgrep-code/policies/#block-a-pr-or-mr-through-rule-modes)
* Pass in the `--error` flag when running `semgrep scan`.

When you run `semgrep ci`, you can pass in the `--no-suppress-errors` if you don't want [internal errors suppressed](/cli-reference/#exit-codes).

## Log out

To log out of your Semgrep account:

```bash theme={null}
semgrep logout
```