Synopsis

codeql database init --source-root=<dir> [--language=<lang>[,<lang>...]] [--github-auth-stdin] [--github-url=<url>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database>

codeql database init --source-root=<dir> [--language=<lang>[,<lang>...]] [--github-auth-stdin] [--github-url=<url>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database>

Description

[Plumbing] Create an empty CodeQL database.

Create a skeleton structure for a CodeQL database that doesn't have araw QL dataset yet, but is ready for running extractor steps. After thiscommand completes, run one or morecodeql database trace-command commands followed bycodeql database finalize to prepare the database for querying.

(Part of what this does is resolve the location of the appropriatelanguage pack and store it in the database metadata, such that it won'tneed to be redone at each extraction command. It is not valid to switchextractors in the middle of an extraction operation anyway.)

Options

Primary Options

<database>

[Mandatory] Path to the CodeQL database to create. This directory willbe created, andmust not already exist (but its parent must).

If the--db-cluster option is given, this will not be a databaseitself, but a directory that willcontain databases for severallanguages built from the same source root.

It is important that this directory is not in a location that the buildprocess will interfere with. For instance, thetarget directory of aMaven project would not be a suitable choice.

-s, --source-root=<dir>

[Mandatory] The root source code directory. In many cases, this willbe the checkout root. Files within it are considered to be the primarysource files for this database. In some output formats, files will bereferred to by their relative path from this directory.

--[no-]overwrite

[Advanced] If the database already exists, delete it and proceed withthis command instead of failing. If the directory exists, but it doesnot look like a database, an error will be thrown.

--[no-]force-overwrite

[Advanced] If the database already exists, delete it even if it doesnot look like a database and proceed with this command instead offailing. This option should be used with caution as it may recursivelydelete the entire database directory.

--codescanning-config=<file>

[Advanced] Read a Code Scanning configuration file specifying optionson how to create the CodeQL databases and what queries to run in latersteps. For more details on the format of this configuration file, refertoCustomizing your advanced setup for code scanning. To run queries fromthis file in a later step, invokecodeql database analyze without any other queries specified.

--[no-]db-cluster

Instead of creating a single database, create a "cluster" of databasesfor different languages, each of which is a subdirectory of thedirectory given on the command line.

-l, --language=<lang>[,<lang>...]

The language that the new database will be used to analyze.

Usecodeql resolve languages to get a list of the pluggable language extractors found on the search path.

When the--db-cluster option is given, this can appear multiple times,or the value can be a comma-separated list of languages.

If this option is omitted, and the source root being analysed is acheckout of a GitHub repository, the CodeQL CLI will make a call to theGitHub API to attempt to automatically determine what languages toanalyse. Note that to be able to do this, a GitHub PAT token must besupplied either in the environment variable GITHUB_TOKEN or via standardinput using the--github-auth-stdin option.

--build-mode=<mode>

The build mode that will be used to create the database.

Choose your build mode based on the language you are analyzing:

none: The database will be created without building the source root.Available for C#, Java, JavaScript/TypeScript, Python, and Ruby.

autobuild: The database will be created by attempting to automaticallybuild the source root. Available for C/C++, C#, Go, Java/Kotlin, andSwift.

manual: The database will be created by building the source root usinga manually specified build command. Available for C/C++, C#, Go,Java/Kotlin, and Swift.

When creating a database with--command, there is no need toadditionally specify '--build-mode manual'.

Available sincev2.16.4.

--[no-]allow-missing-source-root

[Advanced] Proceed even if the specified source root does not exist.

--[no-]begin-tracing

[Advanced] Create some scripts that can be used to set up "indirectbuild tracing," which allows integration into existing build workflowswhen an explicit build command is not available. For information aboutwhen and how to use this feature, please refer to our documentation atPreparing your code for CodeQL analysis.

Baseline calculation options

--[no-]calculate-baseline

[Advanced] Calculate baseline information about the code beinganalyzed and add it to the database. By default, this is enabled unlessthe source root is the root of a filesystem. This flag can be used toeither disable, or force the behavior to be enabled even in the root ofthe filesystem.

--[no-]sublanguage-file-coverage

[GitHub.com and GitHub Enterprise Server v3.12.0+ only] Usesub-language file coverage information. This calculates, displays, andexports separate file coverage information for languages which share aCodeQL extractor like C and C++, Java and Kotlin, and JavaScript andTypeScript.

Available sincev2.15.2.

Extractor selection options

--search-path=<dir>[:<dir>...]

A list of directories under which extractor packs may be found. Thedirectories can either be the extractor packs themselves or directoriesthat contain extractors as immediate subdirectories.

If the path contains multiple directory trees, their order definesprecedence between them: if the target language is matched in more thanone of the directory trees, the one given first wins.

The extractors bundled with the CodeQL toolchain itself will always befound, but if you need to use separately distributed extractors you needto give this option (or, better yet, set up--search-path in aper-user configuration file).

(Note: On Windows the path separator is;).

Options to configure how to call the GitHub API to auto-detect languages.

-a, --github-auth-stdin

Accept a GitHub Apps token or personal access token via standard input.

This overrides the GITHUB_TOKEN environment variable.

-g, --github-url=<url>

URL of the GitHub instance to use. If omitted, the CLI will attempt toautodetect this from the checkout path and if this is not possibledefault tohttps://github.com/

Options to configure the package manager.

--registries-auth-stdin

Authenticate to GitHub Enterprise Server Container registries by passinga comma-separated list of <registry_url>=<token> pairs.

For example, you can passhttps://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2to authenticate to two GitHub Enterprise Server instances.

This overrides the CODEQL_REGISTRIES_AUTH and GITHUB_TOKEN environmentvariables. If you only need to authenticate to the github.com Containerregistry, you can instead authenticate using the simpler--github-auth-stdin option.

Options to configure Windows tracing

--trace-process-name=<process-name>

[Windows only] When initializing tracing, inject the tracer into aparent process of the CodeQL CLI whose name matches this argument. Ifmore than one parent process has this name, the one lowest in theprocess tree will be selected. This option overrides--trace-process-level, so if both are passed, only this option will beused.

--trace-process-level=<process-level>

[Windows only] When initializing tracing, inject the tracer this manyparents above the current process, with 0 corresponding to the processthat is invoking the CodeQL CLI. The CLI's default behavior if noarguments are passed is to inject into the parent of the callingprocess, with some special cases for GitHub Actions and Azure Pipelines.

Options to configure indirect build tracing

--no-tracing

[Advanced] Do not trace the specified command, instead rely on it toproduce all necessary data directly.

--extra-tracing-config=<tracing-config.lua>

[Advanced] The path to a tracer configuration file. It may be used tomodify the behavior of the build tracer. It may be used to pick outcompiler processes that run as part of the build command, and triggerthe execution of other tools. The extractors will provide default tracerconfiguration files that should work in most situations.

Options to control extractor behavior: only be applied to the indirect tracing environment

-O, --extractor-option=<extractor-option-name=value>

Set options for CodeQL extractors.extractor-option-name should be ofthe form extractor_name.group1.group2.option_name orgroup1.group2.option_name. Ifextractor_option_name starts with anextractor name, the indicated extractor must declare the optiongroup1.group2.option_name. Otherwise, any extractor that declares theoption group1.group2.option_name will have the option set.value canbe any string that does not contain a newline.

You can use this command-line option repeatedly to set multipleextractor options. If you provide multiple values for the same extractoroption, the behavior depends on the type that the extractor optionexpects. String options will use the last value provided. Array optionswill use all the values provided, in order. Extractor options specifiedusing this command-line option are processed after extractor optionsgiven via--extractor-options-file.

When passed tocodeql database init orcodeql database begin-tracing, the options will only beapplied to the indirect tracing environment. If your workflow also makescalls tocodeql database trace-command then the options also need to be passed there if desired.

Seehttps://codeql.github.com/docs/codeql-cli/extractor-options formore information on CodeQL extractor options, including how to list theoptions declared by each extractor.

--extractor-options-file=<extractor-options-bundle-file>

Specify extractor option bundle files. An extractor option bundle fileis a JSON file (extension.json) or YAML file (extension.yaml or.yml) that sets extractor options. The file must have the top-levelmap key 'extractor' and, under it, extractor names as second-level mapkeys. Further levels of maps represent nested extractor groups, andstring and array options are map entries with string and array values.

Extractor option bundle files are read in the order they are specified.If different extractor option bundle files specify the same extractoroption, the behavior depends on the type that the extractor optionexpects. String options will use the last value provided. Array optionswill use all the values provided, in order. Extractor options specifiedusing this command-line option are processed before extractor optionsgiven via--extractor-option.

When passed tocodeql database init orcodeql database begin-tracing, the options will only beapplied to the indirect tracing environment. If your workflow also makescalls tocodeql database trace-command then the options also need to be passed there if desired.

Seehttps://codeql.github.com/docs/codeql-cli/extractor-options formore information on CodeQL extractor options, including how to list theoptions declared by each extractor.

Common options

-h, --help

Show this help text.

-J=<opt>

[Advanced] Give option to the JVM running the command.

(Beware that options containing spaces will not be handled correctly.)

-v, --verbose

Incrementally increase the number of progress messages printed.

-q, --quiet

Incrementally decrease the number of progress messages printed.

--verbosity=<level>

[Advanced] Explicitly set the verbosity level to one of errors,warnings, progress, progress+, progress++, progress+++. Overrides-vand-q.

--logdir=<dir>

[Advanced] Write detailed logs to one or more files in the givendirectory, with generated names that include timestamps and the name ofthe running subcommand.

(To write a log file with a name you have full control over, insteadgive--log-to-stderr and redirect stderr as desired.)

--common-caches=<dir>

[Advanced] Controls the location of cached data on disk that willpersist between several runs of the CLI, such as downloaded QL packs andcompiled query plans. If not set explicitly, this defaults to adirectory named.codeql in the user's home directory; it will becreated if it doesn't already exist.

Available sincev2.15.2.