{"meta":{"title":"Setting up the CodeQL CLI","intro":"To get started with the CodeQL CLI, you need to download and set up the CLI so that it can access the tools and libraries required to create and analyze databases.","product":"Security and code quality","breadcrumbs":[{"href":"/en/code-security","title":"Security and code quality"},{"href":"/en/code-security/how-tos","title":"How-tos"},{"href":"/en/code-security/how-tos/find-and-fix-code-vulnerabilities","title":"Find and fix code vulnerabilities"},{"href":"/en/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line","title":"Scan from the command line"},{"href":"/en/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/setting-up-the-codeql-cli","title":"Set up the CodeQL CLI"}],"documentType":"article"},"body":"# Setting up the CodeQL CLI\n\nTo get started with the CodeQL CLI, you need to download and set up the CLI so that it can access the tools and libraries required to create and analyze databases.\n\n## Setting up the CodeQL CLI\n\nTo run CodeQL commands, you need to set up the CodeQL CLI so that it can access the tools, queries, and libraries required to create and analyze databases.\n\nThe CodeQL CLI supports a range of use cases and directory structures. This article walks through a simple setup that works for most users and environments.\n\nIf you plan to use the CodeQL CLI for security research or to test or contribute queries, you may need a more advanced setup. For more information, see [About the CodeQL CLI](/en/code-security/concepts/code-scanning/codeql/about-the-codeql-cli#getting-started).\n\n### Before you begin\n\nIf you are using macOS on Apple Silicon (for example, Apple M1), ensure that the [Xcode command-line developer\ntools](https://developer.apple.com/library/archive/technotes/tn2339/_index.html) and [Rosetta 2](https://support.apple.com/en-us/HT211861) are installed.\n\n> \\[!NOTE]\n> The CodeQL CLI is currently not compatible with non-glibc Linux distributions such as (muslc-based) Alpine Linux.\n\n### 1. Download the CodeQL CLI tar archive\n\nThe CodeQL CLI download package is a tar archive containing tools, scripts, and\nvarious CodeQL-specific files. If you don’t have a GitHub Enterprise license then, by\ndownloading this archive, you are agreeing to the [GitHub CodeQL Terms and\nConditions](https://securitylab.github.com/tools/codeql/license).\n\nYou should download the CodeQL bundle from . The bundle contains:\n\n* CodeQL CLI product\n* A compatible version of the queries and libraries from \n* Precompiled versions of all the queries included in the bundle\n\nYou 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. If you will only be running the CLI on one specific platform, download the appropriate `codeql-bundle-PLATFORM.tar.zst` file. Alternatively, you can download `codeql-bundle.tar.zst`, which contains the CLI for all supported platforms.\n\nThere 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.\n\n### 2. Extract the CodeQL CLI tar archive\n\nExtract the CodeQL CLI tar archive to a directory of your choosing.\n\n### Optional: Make the CodeQL CLI available in your CI system\n\nIf you plan to run CodeQL code scanning analysis in a CI system, ensure that the full contents of the CodeQL CLI bundle are available to every CI server that will run analysis.\n\nFor example, you can:\n\n* Copy the bundle from a central internal location and extract it on each server, or\n* Use the REST API to download the bundle directly from GitHub, ensuring that you receive the latest improvements to queries. For more information, see [REST API endpoints for releases and release assets](/en/rest/releases).\n\n### 3. Launch `codeql`\n\nOnce extracted, you can run CodeQL processes by running the `codeql` executable in a couple of ways:\n\n* By executing `/codeql/codeql`, where `` is the folder where you extracted the CodeQL CLI\n package.\n* By adding `/codeql` to your `PATH`, so that you\n can run the executable as just `codeql`.\n\nAt this point, you can execute CodeQL commands. For a full list of the CodeQL CLI commands, see [CodeQL CLI commands manual](/en/code-security/codeql-cli/codeql-cli-manual).\n\n> \\[!NOTE]\n> If you add `codeql` to your `PATH`, it can be accessed by CodeQL for Visual Studio Code to compile and run queries. For more information about configuring VS Code to access the CodeQL CLI, see [Managing the CodeQL CLI in the VS Code extension](/en/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/configuring-access-to-the-codeql-cli).\n\n## Testing the CodeQL CLI configuration\n\nAfter you extract the CodeQL CLI bundle, you can run the following command to verify that the CLI is correctly configured to create and analyze databases:\n\n* `codeql resolve packs` if `//codeql` is on the `PATH`.\n* `//codeql/codeql resolve packs` otherwise.\n\nIf successful, you should see output similar to the extract below:\n\n```shell\nSearching directories specified by `--additional-packs`. All directories have equal priority.\n Searching in:\n No packs were found at this location.\nSearching directories specified by `--search-path`. Directories are searched in order.\nSearching the root of the CodeQL distribution.\n Searching in:\n \n The following packs were found:\n codeql/java-all@: (library) /qlpacks/codeql/javat-all//qlpack.yml\n codeql/java-queries@: (query) /qlpacks/codeql/java-queries//qlpack.yml\n codeql/javascript-all@: (library) /qlpacks/codeql/javascript-all//qlpack.yml\n codeql/javascript-queries@: (query) /qlpacks/codeql/javascript-queries//qlpack.yml\n codeql/swift-all@: (library) /qlpacks/codeql/swift-all//qlpack.yml\n codeql/swift-queries@: (query) /qlpacks/codeql/swift-queries//qlpack.yml\n...\n```\n\nThe results have been truncated for brevity. The actual results will be longer and more detailed.\n\nYou should check that the output contains the expected languages and also that the directory location for the qlpack files is correct. The location should be within the extracted CodeQL CLI bundle, shown in the earlier example as ``. If the CodeQL CLI is unable to locate the qlpacks for the expected languages, check that you downloaded the CodeQL bundle and not a standalone copy of the CodeQL CLI.\n\nYou can also run `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.\n\nOptionally, you can download some CodeQL packs containing pre-compiled queries you would like to run. For more information, see [Customizing analysis with CodeQL packs](/en/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs).\n\nThe `codeql resolve packs` command is useful for diagnosing problems when the CodeQL CLI is unable to locate query packs that you expect to be available for analysis.\n\n> \\[!NOTE] The `codeql resolve packs` command is available in the CodeQL CLI versions 2.19.0 and later. For earlier versions of the CLI, you should run the `codeql resolve qlpacks` command, which produces similar, but less detailed output.\n\n## Next steps\n\nTo learn how to prepare your code to be analyzed by the CodeQL CLI, see [Preparing your code for CodeQL analysis](/en/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis)."}