Set up the CodeQL CLI directly from the source code.
Some users prefer working with CodeQL query sources directly in order to work on or contribute to open source shared queries.
The CodeQL CLI download package is a tar archive containing tools, scripts, and
various CodeQL-specific files. If you don’t have a GitHub Enterprise license then, by
downloading this archive, you are agreeing to the GitHub CodeQL Terms and
Conditions.
You should download the CodeQL bundle from https://github.com/github/codeql-action/releases. The bundle contains:
You should always use the CodeQL bundle. This ensures compatibility and gives much better performance than a separate download of the CodeQL CLI and checkout of the CodeQL queries. Download the codeql-bundle-PLATFORM.tar.zst file for the platform where you will run the CLI. Replace PLATFORM with linux64 for Linux x64, linux-arm64 for Linux ARM64, osx64 for macOS, or win64 for Windows.
The all-platforms bundle (codeql-bundle.tar.zst and codeql-bundle.tar.gz) is closing down and will stop being published in a future release. Download the per-platform codeql-bundle-PLATFORM.tar.zst file instead. In CodeQL CLI 2.27.0 and later, running the CLI from an all-platforms distribution produces a warning.
There are also tar.gz variants of the bundle, which are identical to the tar.zst variants except compressed using the less efficient gzip algorithm. The only reason to download the tar.gz variants is if you are using older decompression tools that do not support the Zstandard compression algorithm.
Create a new directory where you can place the CLI and any queries and libraries
you want to use. For example, $HOME/codeql-home.
The CLI’s built-in search operations automatically look in all of its sibling
directories for the files used in database creation and analysis. Keeping these
components in their own directory prevents the CLI searching unrelated sibling
directories while ensuring all files are available without specifying any
further options on the command line.
The CodeQL repository contains
the queries and libraries required for CodeQL analysis of all supported languages.
Clone a copy of this repository into codeql-home.
By default, the root of the cloned repository will be called codeql.
Rename this folder codeql-repo to avoid conflicting with the CodeQL CLI that you will extract in step 1. If you use git on the command line, you can
clone and rename the repository in a single step by running
git clone git@github.com:github/codeql.git codeql-repo in the codeql-home folder.
Within this repository, the queries and libraries are organized into CodeQL
packs. Along with the queries themselves, CodeQL packs contain important metadata
that tells the CodeQL CLI how to process the query files. For more information,
see Creating and working with CodeQL packs.
Note
There are different versions of the CodeQL queries available for different users. Check out the correct version for your use case:
codeql-cli/latest. You should use this branch for databases you’ve built using the CodeQL CLI or recently downloaded from GitHub.main branch. This branch represents the very latest version of CodeQL’s analysis.Extract the tar archive into the directory you created in step 2.
For example, if the path to your copy of the CodeQL repository is $HOME/codeql-home/codeql-repo, then extract the CLI into
$HOME/codeql-home/.
codeqlOnce extracted, you can run CodeQL processes by running the codeql executable in a couple of ways:
<extraction-root>/codeql/codeql, where <extraction-root> is the folder where you extracted the CodeQL CLI<extraction-root>/codeql to your PATH, so that youcodeql.At this point, you can execute CodeQL commands. For a full list of the CodeQL CLI commands, see CodeQL CLI commands manual.
CodeQL CLI has subcommands you can execute to verify that you are correctly set up to create and analyze databases:
codeql resolve languages to show which languages are available for database creation. This will list the languages supported by default in your CodeQL CLI package.codeql resolve qlpacks to show which CodeQL packs the CLI can find. This will display the names of all the CodeQL packs directly available to the CodeQL CLI. This should include:
codeql/{language}-queries. These packs contain the standard queries that will be run for each analysis.codeql/{language}-all. These packs contain query libraries, such as control flow and data flow libraries, that may be useful to query writers.codeql/{language}-examples. These packs contain useful snippets of CodeQL that query writers may find useful.