Reference
CLI options
Every flag of the jscpd command line, with its config key and default, generated from the help text of jscpd 5.4.0.
This page lists every option of jscpd 5.4.0, in the words of jscpd --help. The same settings go into the config file under the key in the second column; a flag on the command line wins over the file. Flags that take no value are true in the file. jscpd --debug prints the merged configuration and exits, which is the quickest way to see what a run would use.
Terminal
jscpd [OPTIONS] [PATH]...
PATH is one or more files or directories to scan; the current directory when left out.
What to scan
| Flag | Config key | What it does | Default |
|---|---|---|---|
-p, --pattern <PATTERN> | pattern | Glob pattern to find files to scan (e.g. **/.ts, **/.{js,ts}) | — |
-f, --format <FORMAT> | format | List of file extensions/formats to check (comma-separated) | — |
-i, --ignore <IGNORE> | ignore | File-level glob patterns to ignore, e.g. "/node_modules/" (comma-separated) | — |
--ignore-pattern <IGNORE_PATTERN> | ignorePattern | Code-level regex patterns to skip matching tokens during detection, e.g. "//\s*cpd-disable" (comma-separated) | — |
--no-gitignore | noGitignore | Do not respect .gitignore files | — |
--follow-symlinks | followSymlinks | Follow symbolic links | — |
-z, --max-size <MAX_SIZE> | maxSize | Skip files larger than SIZE (e.g. 1kb, 1mb, 100kb, or raw bytes). Default: 1mb | 1mb |
--formats-exts <FORMATS_EXTS> | formatsExts | Custom format-to-extension mappings (e.g. javascript:es,es6;dart:dt) | — |
--formats-names <FORMATS_NAMES> | formatsNames | Custom format-to-filename mappings (e.g. makefile:Makefile,GNUmakefile;docker:Dockerfile) | — |
--cross-formats <CROSS_FORMATS> | crossFormats | Detect clones across formats: semicolon-separated groups of comma-separated formats (e.g. "javascript,typescript;css,scss"). Preset: js-ts = javascript,jsx,typescript,tsx. TypeScript files in a group that also contains JavaScript are compared with type annotations stripped | — |
--skip-local | skipLocal | Skip clones where both fragments are in the same directory alias: --skipLocal | — |
--skip-isolated <GROUPS> | skipIsolated | Skip clones between different folders of the same isolation group: comma-separated groups of pipe-separated folders (e.g. "packages/a|packages/b,libs/a|libs/b") alias: --skipIsolated | — |
-c, --config <CONFIG> | — | Path to config file (.jscpd.json) | — |
--list | — | List all supported formats and exit | — |
--debug | — | Print merged config (CLI + config file) as JSON and exit without running detection | — |
Clone size and kinds
| Flag | Config key | What it does | Default |
|---|---|---|---|
-k, --min-tokens <MIN_TOKENS> | minTokens | Minimum number of tokens to consider a duplicate | — |
-l, --min-lines <MIN_LINES> | minLines | Minimum number of lines to consider a duplicate | — |
-x, --max-lines <MAX_LINES> | maxLines | Maximum number of lines per block to consider | — |
-m, --mode <MODE> | mode | Detection mode: mild, weak, strict | — |
--skip-comments | mode | Alias for --mode weak (skip comment tokens) | — |
--ignore-case | ignoreCase | Ignore case of symbols in code (experimental) | — |
--ignore-identifiers | ignoreIdentifiers | Treat all identifiers as equal, so clones that differ only in variable, function or type names are found (Type-2 clones) | — |
--ignore-literals | ignoreLiterals | Treat all string and numeric literals as equal, so clones that differ only in literal values are found | — |
--ignore-annotations | ignoreAnnotations | Skip annotations and decorators (@Name, @Name(...)) in Java, Kotlin, Scala, Groovy, Python, Dart, Swift, JavaScript and TypeScript | — |
--max-gap-lines <N> | maxGapLines | Merge clones of the same file pair that are separated by at most N unmatched lines in both files into one near-miss clone (Type-3, reported as "similar"); 0 disables | — |
--similarity <RATIO> | similarity | Report JavaScript/TypeScript function pairs whose AST similarity reaches RATIO as near-miss clones (Type-3, "similar"). A number in (0, 1]; the default 1 means exact matches only, e.g. 0.85 enables it | 1 |
--kind <LIST> | kind | Report only clones of these kinds: exact, renamed, similar, gap, ast, semantic (comma-separated). renamed needs --ignore-identifiers, --ignore-literals or --ignore-annotations; gap needs --max-gap-lines; ast needs --similarity; semantic needs --semantic | — |
Semantic clones
| Flag | Config key | What it does | Default |
|---|---|---|---|
--semantic | semantic | Find semantic clones (Type-4, experimental): functions that do the same thing written differently, in one language or across languages, e.g. a Rust backend and a Svelte frontend. Compares embeddings of the functions' code, computed on this machine by a model that --semantic-download fetches once, or by an embeddings API (--semantic-url). Functions of JavaScript, TypeScript, JSX, TSX, Vue, Svelte, Astro, Python, Rust, Go, Java, Kotlin, C#, C, C++, PHP, Ruby, Scala and Swift | — |
--semantic-scope <SCOPE> | — | Which semantic clones to report: all (default), same (within one language: several implementations of one feature) or cross (across languages: a rule written once per side) possible values: all, same, cross | — |
--semantic-provider <PROVIDER> | — | Where embeddings come from: local (default: a model run in-process, fetched once by --semantic-download) or http (an OpenAI-compatible embeddings API at --semantic-url; giving a URL selects it) possible values: local, http | a model run in-process, fetched once by --semantic-download |
--semantic-download [<MODEL>] | — | Download a local embedding model into the jscpd cache directory, checking its checksum: MODEL, or the one --semantic-model names, or CodeRankEmbed (548 MB from huggingface.co). Alone it exits after the download; with --semantic it goes on to scan, with MODEL unless --semantic-model names another | — |
--semantic-rebuild-cache | — | With --semantic: embed every function again and replace the cached vectors of the model in use for the scanned paths, instead of reusing them. The caches of other paths and models and the downloaded model stay | — |
--semantic-threshold <RATIO> | — | Lowest cosine similarity of a semantic clone across languages, in (0, 1] (default: the model's calibrated value, 0.4125 for the default model; --semantic-models lists them, and a model not listed gets 0.6). A pair within one language needs more: see --semantic-same-threshold | the model's calibrated value, 0 |
--semantic-same-threshold <RATIO> | — | Lowest cosine similarity of a semantic clone within one language, in (0, 1] (default: the model's calibrated value, 0.6375 for the default model; when --semantic-threshold is set, that value plus the model's gap between the two, 0.225 for the default model and 0.15 for a model not listed by --semantic-models) | the model's calibrated value, 0 |
--semantic-model <NAME> | — | Embedding model for --semantic (default: CodeRankEmbed for the local provider; for http, unclemusclez/jina-embeddings-v2-base-code, Ollama's name for jina-embeddings-v2-base-code). A model that --semantic-models lists, named as it is there, by its Hugging Face id or by its Ollama name, gets its calibrated thresholds; an API gets the name as given | CodeRankEmbed for the local provider |
--semantic-models | — | List the embedding models jscpd has calibrated thresholds for, with their licenses and where they run, and exit | — |
--semantic-url <URL> | — | OpenAI-compatible embeddings API for --semantic, e.g. http://localhost:11434/v1 for Ollama; selects the http provider. A key the API needs is read from the JSCPD_SEMANTIC_API_KEY environment variable, and is sent only to a URL given here or to a server on this machine | — |
Reports
| Flag | Config key | What it does | Default |
|---|---|---|---|
-r, --reporters <REPORTERS> | reporters | Output reporters (comma-separated): console,json,xml,csv,html,markdown,badge,sarif,codeclimate,openmetrics,ai,xcode,threshold,silent,console-full Aliases: "full" and "consoleFull" are accepted for "console-full"; "gitlab" for "codeclimate" | — |
-o, --output <OUTPUT> | output | Output directory for file reporters | — |
-a, --absolute | absolute | Use absolute paths in reports | — |
-b, --blame | blame | Enrich clones with git blame data | — |
--sarif-error-tokens <TOKENS> | sarifErrorTokens | Report SARIF results as "error" for clones with at least this many tokens (default: all "warning") | all "warning" |
--no-colors | noColors | Disable ANSI color output | — |
-s, --silent | silent | Do not write detection progress and result to console | — |
--no-tips | noTips | Do not print tips and promotional messages after detection (also skipped when stdout is not a terminal or CI or JSCPD_NO_TIPS is set) | — |
Gates and exit codes
| Flag | Config key | What it does | Default |
|---|---|---|---|
-t, --threshold <THRESHOLD> | threshold | Maximum duplication percentage before exit 1 | — |
--exit-code [<EXIT_CODE>] | exitCode | Exit with code if duplicates found (default code: 1) | 1 |
--baseline <FILE> | baseline | Path to a clone baseline file (e.g. .jscpd-baseline.json): clones whose fingerprint is absent from it are reported as new | — |
--update-baseline | — | Rewrite the baseline file from the current run, creating it if missing, and print added/removed fingerprint counts (requires --baseline) | — |
--fail-on-new-clones [<N>] | failOnNewClones | Exit 1 when more than N new clones are found (default N: 0; requires --baseline or --baseline-from-ref) | N: 0; requires --baseline or --baseline-from-ref |
--fail-on-empty | failOnEmpty | Exit 1 when the scan analyzes no files: the paths exist but nothing matched the --format, --ignore and --pattern filters, or every file was below --min-tokens | — |
--baseline-from-ref <REF> | baselineFromRef | Compare against an ephemeral baseline built from a git ref's tree (e.g. origin/main): the base ref is scanned with the same configuration and clones absent from it are reported as new | — |
Other modes of the same binary
| Flag | Config key | What it does | Default |
|---|---|---|---|
--dashboard | — | Print one screen with the whole picture: the health score, project size, duplication, complexity and dead code (JavaScript, TypeScript, Python). Reporters: console, json, badge, markdown, html | — |
--health | health | Print only the project health badge: one 0-100 score with a grade, from duplication, dead code and complexity, plus the metrics of --health-input. Reporters: console, ai, json, badge, markdown, html | — |
--health-input <FILE> | healthInput | JSON file with metrics from other tools (coverage, tests, security) to include in the health score: {"metrics": {"id", "score"} or {"id", "value", "halfLife", "direction"}} | — |
--dead-code | deadCode | Find dead code instead of duplicates: unused files, exports, symbols and imports across JavaScript, TypeScript and Python | — |
--dead-code-categories <LIST> | deadCodeCategories | Dead-code findings to report: unused-file, unused-export, unused-symbol, unused-import, unused-member, or all (with --dead-code) | — |
--min-confidence <N> | minConfidence | Drop dead-code findings below this confidence, 0-100 (with --dead-code) | — |
--rust-diagnostics <FILE> | — | Rust dead code from the compiler, for --dead-code, --dashboard and --health: a file of cargo check --message-format=json output, or - to read it from stdin | — |
--entry <GLOB> | entry | Treat files matching this glob as dead-code entry points (repeatable) | — |
--include-tests | includeTests | Report dead code inside test, fixture and example files | — |
--include-entry-exports | includeEntryExports | Report exports of entry-point files, which are usually a public API | — |
--complexity | — | Report complexity only: the --summary tables ranked by complexity, without clone detection (reporters: console, ai, json) | — |
--summary | summary | Print a codebase summary: top files and folders by tokens, lines, size, complexity | — |
--summary-top <N> | summaryTop | Number of entries in each summary top list (default: 10) | 10 |
--summary-by <METRIC> | summaryBy | Summary sort metric: tokens, lines, size, complexity (default: tokens) | tokens |
--history <RANGE> | history | Duplication trend over git history: scan every commit in RANGE (e.g. v5.0.0..HEAD) with this configuration and print a chart and a table | — |
--history-since <DATE> | historySince | Like --history, selecting commits since DATE (e.g. 2026-01-01); combines with --history to bound the range | — |
--history-every <N> | historyEvery | Keep every Nth commit of the history series, counted from the newest (default: 1) | 1 |
--history-limit <N> | historyLimit | Maximum number of commits in the history series, sampled evenly (default: 30) | 30 |
--compare | — | Compare two folders function by function: which functions of the first have a counterpart in the second and which do not, and the other way round. For a port to another language or platform, the source first and the target second (jscpd --compare python-lib/ rust-lib/), or two implementations of one app (jscpd --compare ios/ android/). Pairs functions with the --semantic model, so the --semantic-* options apply; counts functions of at least --min-lines lines and --min-tokens tokens (30 by default here). Reporters: console, console-full, json, markdown | — |
--mcp | — | Serve the Model Context Protocol over stdio: scan PATHs once, then expose check_duplication / get_statistics / check_current_directory tools to MCP clients | — |
--lsp | lsp | Serve the Language Server Protocol over stdio: an editor starts jscpd for its workspace and gets findings as diagnostics in the files it edits, updated as the text changes. Clones by default; --lsp-analyses picks the analyses. Each .jscpd.json in the workspace is a project of its own | — |
--lsp-analyses <LIST> | — | The analyses --lsp runs, comma-separated: clones, ast (similar functions), semantic, dead-code, complexity, or all (default: clones). The lsp section of .jscpd.json and the editor's settings switch each on or off over this list | clones |
Runtime
| Flag | Config key | What it does | Default |
|---|---|---|---|
--workers <WORKERS> | — | Number of worker threads (default: auto) | auto |
-h, --help | — | Print help | — |
-V, --version | — | Print version | — |
See also
- The config file: where jscpd looks for
.jscpd.json, thepackage.jsonform, inline markers. - Exit codes: what
--threshold,--exit-code,--fail-on-new-clonesand--fail-on-emptydo to the exit status. - GitHub Action: the same options as action inputs.
The health score
How jscpd turns duplication, dead code and complexity into one 0-100 score with a grade, step by step, with the constants and a worked example.
The config file
Every key of .jscpd.json and the jscpd section of package.json, where jscpd looks for them, and how they combine with the command line.