Getting Help from the Command Line¶
Scancode-Toolkit Command Line Interface can help you to search for specific options or use cases
from the command line itself. These are two options are --help and --examples, and are
very helpful if you need a quick glance of the options or use cases. Or it can be useful when you
can’t access the more elaborate online documentation.
Help text¶
The Scancode-Toolkit Command Line Interface has a Help option displaying all the options. It also displays basic usage, and some simple examples. The command line option for this is:
--help
Tip
You can also use the shorter -h option, which does the same.
For Linux based systems the full command is:
$ ./scancode --help
And for windows, it will be like:
$ scancode --help
Note
Make sure you are in the Scancode Root Directory before carrying out this command. After
extracting the .zip or .tar.bz file, the folder for Scancode-Toolkit version 2.1.1
will be named like “scancode-toolkit-2.2.1”.
The Following Help Text is displayed, i.e. this is the help text for Scancode Version 2.2.1
Usage: scancode [OPTIONS] <input> <output_file>
scan the <input> file or directory for origin clues and license and
save results to the <output_file>.
The scan results are printed to stdout if <output_file> is not
provided. Error and progress is printed to stderr.
Options:
scans:
-c, --copyright Scan <input> for copyrights. [default]
-l, --license Scan <input> for licenses. [default]
-p, --package Scan <input> for packages. [default]
-e, --email Scan <input> for emails.
-u, --url Scan <input> for urls.
-i, --info Include information such as size, type,
etc.
--license-score INTEGER Do not return license matches with scores
lower than this score. A number between 0
and 100. [default: 0]
--license-text Include the detected licenses matched
text. Has no effect unless --license is
requested.
--license-url-template TEXT Set the template URL used for the license
reference URLs. In a template URL, curly
braces ({}) are replaced by the license
key. [default: https://enterprise.dejaco
de.com/urn/urn:dje:license:{}]
output:
--strip-root Strip the root directory segment of all paths.
The default is to always include the last
directory segment of the scanned path such that
all paths have a common root directory. This
cannot be combined with `--full-root` option.
--full-root Report full, absolute paths. The default is to
always include the last directory segment of
the scanned path such that all paths have a
common root directory. This cannot be combined
with the `--strip-root` option.
-f, --format <format> Set <output_file> format to one of: csv, html,
html-app, json, json-pp, jsonlines, spdx-rdf,
spdx-tv or use <format> as the path to a custom
template file [default: json]
--verbose Print verbose file-by-file progress messages.
--quiet Do not print summary or progress messages.
pre-scan:
--ignore <pattern> Ignore files matching <pattern>.
post-scan:
--mark-source Set the "is_source" flag to true for directories that
contain over 90% of source files as direct children.
Has no effect unless the --info scan is requested.
--only-findings Only return files or directories with findings for
the requested scans. Files and directories without
findings are omitted (not considering basic file
information as findings).
misc:
--reindex-licenses Force a check and possible reindexing of the
cached license index.
core:
-h, --help Show this message and exit.
-n, --processes INTEGER Scan <input> using n parallel processes.
[default: 1]
--examples Show command examples and exit.
--about Show information about ScanCode and licensing
and exit.
--version Show the version and exit.
--diag Include additional diagnostic information
such as error messages or result details.
--timeout FLOAT Stop scanning a file if scanning takes longer
than a timeout in seconds. [default: 120]
Examples (use --examples for more):
Scan the 'samples' directory for licenses and copyrights.
Save scan results to a JSON file:
scancode --format json samples scancode_result.json
Scan the 'samples' directory for licenses and copyrights. Save scan results to
an HTML app file for interactive web browser results navigation. Additional app
files are saved to the 'myscan_files' directory:
scancode --format html-app samples myscan.html
Note: when you run scancode, a progress bar is displayed with a
counter of the number of files processed. Use --verbose to display
file-by-file progress.
Command Examples Text¶
The Scancode-Toolkit Command Line Interface has an examples option which displays some basic
examples (more than the basic synopsis in --help). These examples include the following aspects
of code scanning:
- Scanning Single File/Directory
- Output Scan results to stdout(as JSON) or HTML/JSON file
- Scanning for only Copyrights/Licenses
- Ignoring Files
- Using GLOB Patterns to Scan Multiple Files
- Using Verbose Mode
The command line option for displaying these basic examples is:
--examples
For Linux based systems the full command is:
$ ./scancode --examples
And for windows, it will be like:
$ scancode --examples
The Following Text is displayed, i.e. this is the examples for Scancode Version 2.2.1
Scancode command lines examples:
(Note for Windows: use '\' back slash instead of '/' forward slash for paths.)
Scan the 'samples' directory for licenses and copyrights. Save scan results to
an HTML app file for interactive scan results navigation. When the scan is done,
open 'scancode_result.html' in your web browser. Note that additional app files
are saved in a directory named 'scancode_result_files':
scancode --format html-app samples/ scancode_result.html
Scan a directory for licenses and copyrights. Save scan results to an
HTML file:
scancode --format html samples/zlib scancode_result.html
Scan a single file for copyrights. Print scan results to stdout as JSON:
scancode --copyright samples/zlib/zlib.h
Scan a single file for licenses, print verbose progress to stderr as each
file is scanned. Save scan to a JSON file:
scancode --license --verbose samples/zlib/zlib.h licenses.json
Scan a directory explicitly for licenses and copyrights. Redirect JSON scan
results to a file:
scancode -f json -l -c samples/zlib/ > scan.json
Scan a directory while ignoring a single file. Print scan results to stdout as JSON:
scancode --ignore README samples/
Scan a directory while ignoring all files with txt extension. Print scan results to
stdout as JSON (It is recommended to use quoted glob patterns to prevent pattern
expansion by the shell):
scancode --ignore "*.txt" samples/
Special characters supported in GLOB pattern:
* matches everything
? matches any single character
[seq] matches any character in seq
[!seq] matches any character not in seq
For a literal match, wrap the meta-characters in brackets. For example, '[?]' matches the character '?'.
For glob see https://en.wikipedia.org/wiki/Glob_(programming).
Note: Glob patterns cannot be applied to path as strings, for e.g.
scancode --ignore "samples*licenses" samples/
will not ignore "samples/JGroups/licenses".
Scan a directory while ignoring multiple files (or glob patterns). Print the scan
results to stdout as JSON:
scancode --ignore README --ignore "*.txt" samples/
To extract archives, see the 'extractcode' command instead.