docs/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/about-the-codeql-cli.md

title, intro, product, versions, topics, redirect_from

title	intro	product	versions	topics	redirect_from
About the CodeQL CLI	You can use the {% data variables.product.prodname_codeql_cli %} to run {% data variables.product.prodname_codeql %} processes locally on software projects or to generate {% data variables.product.prodname_code_scanning %} results for upload to {% data variables.product.product_name %}.	{% data reusables.gated-features.codeql %}	fpt ghes ghae ghec * * * *	Advanced Security Code scanning CodeQL	/code-security/codeql-cli/about-the-codeql-cli /code-security/codeql-cli/using-the-codeql-cli/about-the-codeql-cli /code-security/secure-coding/about-codeql-code-scanning-in-your-ci-system /code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system/about-codeql-code-scanning-in-your-ci-system /code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/running-codeql-runner-in-your-ci-system /github/finding-security-vulnerabilities-and-errors-in-your-code/using-codeql-code-scanning-with-your-existing-ci-system/running-codeql-code-scanning-in-your-ci-system /github/finding-security-vulnerabilities-and-errors-in-your-code/running-codeql-code-scanning-in-your-ci-system /github/finding-security-vulnerabilities-and-errors-in-your-code/troubleshooting-codeql-code-scanning-in-your-ci-system /github/finding-security-vulnerabilities-and-errors-in-your-code/using-codeql-code-scanning-with-your-existing-ci-system/troubleshooting-codeql-code-scanning-in-your-ci-system /code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/migrating-from-the-codeql-runner-to-codeql-cli /code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/about-codeql-code-scanning-in-your-ci-system

About the {% data variables.product.prodname_codeql_cli %}

Software developers and security researchers can secure their code using {% data variables.product.prodname_codeql %} analysis. For more information about {% data variables.product.prodname_codeql %}, see "AUTOTITLE."

{% data reusables.code-scanning.what-is-codeql-cli %}

You can use the {% data variables.product.prodname_codeql_cli %} to:

• Run {% data variables.product.prodname_codeql %} analyses using queries provided by {% data variables.product.prodname_dotcom %} engineers and the open source community
• Generate code scanning alerts that you can upload to display in {% data variables.product.product_name %}
• Create {% data variables.product.prodname_codeql %} databases to use in the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension.
• Develop and test custom {% data variables.product.prodname_codeql %} queries to use in your own analyses

The {% data variables.product.prodname_codeql_cli %} can analyze:

• Dynamic languages, for example, JavaScript and Python.
• Compiled languages, for example, C/C++, C#,{% ifversion codeql-go-autobuild %} Go,{% endif %} and Java.
• Codebases written in a mixture of languages.

For information about setting up the {% data variables.product.prodname_codeql_cli %}, see "AUTOTITLE."

About using the {% data variables.product.prodname_codeql_cli %} for {% data variables.product.prodname_code_scanning %}

You can use the {% data variables.product.prodname_codeql_cli %} to run {% data variables.product.prodname_code_scanning %} on code that you're processing in a third-party continuous integration (CI) system. {% data reusables.code-scanning.about-code-scanning %} For an overview of using code scanning with external CI systems, see "AUTOTITLE." For recommended specifications (RAM, CPU cores, and disk) for running {% data variables.product.prodname_codeql %} analysis, see "AUTOTITLE."

Alternatively, you can use {% data variables.product.prodname_actions %} or Azure DevOps pipelines to scan code using the {% data variables.product.prodname_codeql_cli %}. For more information, see {% ifversion code-scanning-without-workflow %}"AUTOTITLE"{% else %}"AUTOTITLE"{% endif %} or Configure {% data variables.product.prodname_ghas_azdo %} in Microsoft Learn.

For an overview of all the options for using {% data variables.product.prodname_codeql %} analysis for code scanning, see "AUTOTITLE."

{% data reusables.code-scanning.licensing-note %}

About generating code scanning results with the {% data variables.product.prodname_codeql_cli %}

If you choose to run the {% data variables.product.prodname_codeql_cli %} directly, you first have to install the {% data variables.product.prodname_codeql_cli %} locally. If you are planning to use the {% data variables.product.prodname_codeql_cli %} with an external CI system, you need to make the {% data variables.product.prodname_codeql_cli %} available to servers in your CI system. For more information, see "AUTOTITLE."

Once the {% data variables.product.prodname_codeql_cli %} is set up, you can use three different commands to generate results and upload them to {% data variables.product.product_name %}:

1. database create to create a {% data variables.product.prodname_codeql %} database to represent the hierarchical structure of each supported programming language in the repository. For more information, see "AUTOTITLE."
2. database analyze to run queries to analyze each {% data variables.product.prodname_codeql %} database and summarize the results in a SARIF file. For more information, see "AUTOTITLE."
3. github upload-results to upload the resulting SARIF files to {% data variables.product.product_name %} where the results are matched to a branch or pull request and displayed as {% data variables.product.prodname_code_scanning %} alerts. For more information, see "AUTOTITLE."

{% data reusables.code-scanning.upload-sarif-ghas %}

Example CI configuration for {% data variables.product.prodname_codeql %} analysis

This is an example of the full series of commands for the {% data variables.product.prodname_codeql_cli %} that you might use to analyze a codebase with two supported languages and then upload the results to {% data variables.product.product_name %}.

# Create CodeQL databases for Java and Python in the 'codeql-dbs' directory
# Call the normal build script for the codebase: 'myBuildScript'

codeql database create codeql-dbs --source-root=src \
    --db-cluster --language=java,python --command=./myBuildScript

# Analyze the CodeQL database for Java, 'codeql-dbs/java'
# Tag the data as 'java' results and store in: 'java-results.sarif'

codeql database analyze codeql-dbs/java java-code-scanning.qls \
    --format=sarif-latest --sarif-category=java --output=java-results.sarif

# Analyze the CodeQL database for Python, 'codeql-dbs/python'
# Tag the data as 'python' results and store in: 'python-results.sarif'

codeql database analyze codeql-dbs/python python-code-scanning.qls \
    --format=sarif-latest --sarif-category=python --output=python-results.sarif

# Upload the SARIF file with the Java results: 'java-results.sarif'
# The {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} created for authentication
# with {% data variables.product.company_short %}'s REST API is available in the `GITHUB_TOKEN` environment variable.

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=java-results.sarif

# Upload the SARIF file with the Python results: 'python-results.sarif'

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=python-results.sarif

About the {% data variables.product.prodname_dotcom %} {% data variables.product.prodname_codeql %} license

License notice: If you don’t have a {% data variables.product.prodname_enterprise %} license then, by installing this product, you are agreeing to the {% data variables.product.prodname_dotcom %} {% data variables.product.prodname_codeql %} Terms and Conditions.

{% data variables.product.prodname_dotcom %} {% data variables.product.prodname_codeql %} is licensed on a per-user basis. Under the license restrictions, you can use {% data variables.product.prodname_codeql %} to perform the following tasks:

• To perform academic research.
• To demonstrate the software.
• To test {% data variables.product.prodname_codeql %} queries that are released under an OSI-approved License to confirm that new versions of those queries continue to find the right vulnerabilities.

Where "OSI-approved License" means an Open Source Initiative (OSI)-approved open source software license.

If you are working with an Open Source Codebase (that is, a codebase that is released under an OSI-approved License) you can also use {% data variables.product.prodname_codeql %} for the following tasks:

• To perform analysis of the Open Source Codebase.
• If the Open Source Codebase is hosted and maintained on {% data variables.product.prodname_dotcom_the_website %}, to generate {% data variables.product.prodname_codeql %} databases for or during automated analysis, continuous integration, or continuous delivery.

{% data variables.product.prodname_codeql %} can’t be used for automated analysis, continuous integration or continuous delivery, whether as part of normal software engineering processes or otherwise, except in the express cases set forth herein. For these uses, contact the sales team.