Command-line Interface¶

This documentation provides an overview of the CLI commands and the corresponding operations. The parameters for each command should be stored in the settings.json.

colrev status¶

Show status

colrev status [OPTIONS]

Options

-v, --verbose¶: Verbose: printing more infos

colrev init¶

Initialize (define review objectives and type)

Docs: https://colrev-environment.github.io/colrev/manual/problem_formulation/init.html

colrev init [OPTIONS]

Options

--type <review_type>¶: Review type for the setup.

-f, --force¶: Force mode

--light¶: Setup a lightweight repository (without Docker services)

--example¶: Add search results example

colrev retrieve¶

Retrieve, a high-level operation, consists of search, load, prep, and dedupe.

To retrieve search results:
- Copy files (*.bib, *.ris, *.xlsx, …) to the directory data/search or
- Copy PDF files to the directory data/pdfs or
- Add an API-based search, as described in the documentation:

https://colrev-environment.github.io/colrev/manual/metadata_retrieval/search.html

colrev retrieve [OPTIONS]

Options

-v, --verbose¶: Verbose: printing more infos

-f, --force¶: Force mode

colrev search¶

Search for records

Docs: https://colrev-environment.github.io/colrev/manual/metadata_retrieval/search.html

colrev search [OPTIONS]

Options

-a, --add <add>¶: Search source to be added.

-p, --params <params>¶: Parameters

--view¶: View search sources

-s, --selected <selected>¶: Only retrieve search results for selected sources

-r, --rerun¶: Rerun API-based searches, retrieving and updating all records (not just the most recent ones)

-bws <bws>¶: Backward search on a selected paper

--skip¶: Skip adding new SearchSources

-scs, --setup_custom_script¶: Setup template for custom search script.

-v, --verbose¶: Verbose: printing more infos

-f, --force¶: Force mode

colrev load¶

Load records

Docs: https://colrev-environment.github.io/colrev/manual/metadata_retrieval/load.html

colrev load [OPTIONS]

Options

-k, --keep_ids¶: Do not change the record IDs. Useful when importing an existing sample.

-sq, --skip_query¶: Skip entering the search query (if applicable)

-v, --verbose¶: Verbose: printing more infos

-f, --force¶: Force mode

colrev prep¶

Prepare records

Docs: https://colrev-environment.github.io/colrev/manual/metadata_retrieval/prep.html

colrev prep [OPTIONS]

Options

-a, --add <add>¶: Prep package to be added.

-p, --params <params>¶: Parameters

-k, --keep_ids¶: Do not change the record IDs. Useful when importing an existing sample.

--polish¶: Polish record metadata (includes records in md_processed or beyond).

-d, --debug <debug>¶: Debug the preparation step for a selected record (can be ‘all’).

--cpu <cpu>¶: Number of cpus (parallel processes)

-scs, --setup_custom_script¶: Setup template for custom prep script.

-v, --verbose¶: Verbose: printing more infos

-f, --force¶: Force mode

colrev prep-man¶

Prepare records manually

Docs: https://colrev-environment.github.io/colrev/manual/metadata_retrieval/prep.html

colrev prep-man [OPTIONS]

Options

-a, --add <add>¶: Prep-man script to be added.

-p, --params <params>¶: Parameters

--stats¶: Print statistics of records with colrev_status md_needs_manual_preparation

-l, --languages¶: Export spreadsheet to add missing language fields.

-v, --verbose¶: Verbose: printing more infos

-f, --force¶: Force mode

colrev dedupe¶

Deduplicate records

Docs: https://colrev-environment.github.io/colrev/manual/metadata_retrieval/dedupe.html

colrev dedupe [OPTIONS]

Options

-a, --add <add>¶: Dedupe package to be added.

-p, --params <params>¶: Parameters

-m, --merge <merge>¶: Merge records by providing a comma-separated list of IDs (ID1,ID2).

-u, --unmerge <unmerge>¶: Unmerge records by providing a comma-separated list of IDs (ID1,ID2).

-f, --fix_errors¶: Fix errors marked in duplicates_to_validate.xlsx or non_duplicates_to_validate.xlsx or a dupes.txt file containing comma-separated ID tuples

-gid¶: Merge records with identical global IDs (e.g., DOI)

--view¶: View dedupe info

-d, --debug¶: Debug mode

-v, --verbose¶: Verbose: printing more infos

-f, --force¶: Force mode

colrev prescreen¶

Pre-screen exclusion based on metadata (titles and abstracts)

Docs: https://colrev-environment.github.io/colrev/manual/metadata_prescreen/prescreen.html

colrev prescreen [OPTIONS]

Options

-a, --add <add>¶: Prescreen package to be added.

-p, --params <params>¶: Parameters

--include_all¶: Include all records in prescreen

--include_all_always¶: Include all records in this and future prescreens

--export_format <export_format>¶

Export table with the screening decisions

Options:: CSV | XLSX

--import_table <import_table>¶: Import file with the screening decisions (csv/xlsx supported)

--create_split <create_split>¶: Split the prescreen between n researchers (same size, non-overlapping samples)

--split <split>¶: Prescreen a split sample

-i, --include <include>¶: Prescreen include records based on IDs (ID1,ID2,…).

-e, --exclude <exclude>¶: Prescreen exclude records based on IDs (ID1,ID2,…).

-scs, --setup_custom_script¶: Setup template for custom prescreen script.

-v, --verbose¶: Verbose: printing more infos

-f, --force¶: Force mode

colrev screen¶

Screen based on PDFs and inclusion/exclusion criteria

Docs: https://colrev-environment.github.io/colrev/manual/pdf_screen/screen.html

colrev screen [OPTIONS]

Options

-a, --add <add>¶: Screen package to be added.

-p, --params <params>¶: Parameters

--include_all¶: Include all records in the screen

--include_all_always¶: Include all records in this and future screens

-ac, --add_criterion <add_criterion>¶: Add a screening criterion. Format: -ac ‘criterion_name,criterion explanation’

-dc, --delete_criterion <delete_criterion>¶: Delete a screening criterion. Format: -dc ‘criterion_name’

--create_split <create_split>¶: Split the screen between n researchers (each researcher screens the same number of papers without overlaps)

--split <split>¶: Screen a split sample

-abstracts, --add_abstracts_from_tei¶: Add abstracts from TEI files

-scs, --setup_custom_script¶: Setup template for custom screen script.

-v, --verbose¶: Verbose: printing more infos

-f, --force¶: Force mode

colrev pdfs¶

Retrieve and prepare PDFs

colrev pdfs [OPTIONS]

Options

--discard¶: Discard all missing PDFs as not_available

-d, --dir¶: Open the PDFs directory

-v, --verbose¶: Verbose: printing more infos

-f, --force¶: Force mode

colrev pdf-get¶

Get PDFs

Docs: https://colrev-environment.github.io/colrev/manual/pdf_retrieval/pdf_get.html

colrev pdf-get [OPTIONS]

Options

-a, --add <add>¶: PDF-get package to be added.

-p, --params <params>¶: Parameters

-c, --copy-to-repo¶: Copy PDF files to the repository (the /pdfs directory)

-r, --rename¶: Rename the PDF files according to record IDs

--relink_pdfs¶: Recreate links to PDFs based on colrev pdf-IDs (when PDFs were renamed)

-scs, --setup_custom_script¶: Setup template for custom pdf-get script.

-v, --verbose¶: Verbose: printing more infos

-f, --force¶: Force mode

colrev pdf-get-man¶

Get PDFs manually

Docs: https://colrev-environment.github.io/colrev/manual/pdf_retrieval/pdf_get.html

colrev pdf-get-man [OPTIONS]

Options

-a, --add <add>¶: PDF-get-man package to be added.

-p, --params <params>¶: Parameters

-e, --export¶: Export a table.

--discard¶: Discard all missing PDFs as not_available

-v, --verbose¶: Verbose: printing more infos

-f, --force¶: Force mode

colrev pdf-prep¶

Prepare PDFs

Docs: https://colrev-environment.github.io/colrev/manual/pdf_retrieval/pdf_prep.html

colrev pdf-prep [OPTIONS]

Options

-a, --add <add>¶: PDF-prep package to be added.

-p, --params <params>¶: Parameters

--update_colrev_pdf_ids¶: Update colrev_pdf_ids

-b, --batch_size <batch_size>¶: Batch size (when not all records should be processed in one batch).

--reprocess¶: Prepare all PDFs again (pdf_needs_manual_preparation).

--tei¶: Generate TEI documents.

-scs, --setup_custom_script¶: Setup template for custom pdf-prep script.

-v, --verbose¶: Verbose: printing more infos

-f, --force¶: Force mode

colrev pdf-prep-man¶

Prepare PDFs manually

Docs: https://colrev-environment.github.io/colrev/manual/pdf_retrieval/pdf_prep.html

colrev pdf-prep-man [OPTIONS]

Options

-a, --add <add>¶: PDF-prep-man package to be added.

-p, --params <params>¶: Parameters

-dfp, --delete_first_page <delete_first_page>¶: Delete first page of PDF. Format: –delete_first_page ID

--stats¶: Print statistics of records with colrev_status pdf_needs_manual_preparation

--discard¶: Discard records whose PDF needs to be prepared manually

--extract¶: Extract records for manual_preparation (to csv and bib)

--apply¶: Apply manual preparation (from csv or bib)

-v, --verbose¶: Verbose: printing more infos

-f, --force¶: Force mode

colrev data¶

Complete selected forms of data analysis and synthesis

Docs: https://colrev-environment.github.io/colrev/manual/data/data.html

colrev data [OPTIONS]

Options

-a, --add <add>¶: Data package to be added.

-p, --params <params>¶: Parameters

--reading_heuristics¶: Heuristics to prioritize reading efforts

-scs, --setup_custom_script¶: Setup template for custom data script.

-v, --verbose¶: Verbose: printing more infos

-f, --force¶: Force mode

colrev env¶

Manage the environment

colrev env [OPTIONS]

Options

-i, --index¶: Create the LocalIndex

--install <install>¶: Install a new resource providing its url (e.g., a curated metadata repository)

--pull¶: Pull curated metadata

-s, --status¶: Print environment status

-r, --register¶: Register a repository in the CoLRev environment

-ur, --unregister <unregister>¶: Path of repository to remove from local registry.

--update_package_list¶: Update the package list (packages).

-v, --verbose¶: Verbose: printing more infos

colrev clone¶

Create local clone from shared CoLRev repository with git_url

colrev clone [OPTIONS] GIT_URL

Arguments

GIT_URL¶: Required argument

colrev pull¶

Pull CoLRev project remote and record updates

colrev pull [OPTIONS]

Options

-v, --verbose¶: Verbose: printing more infos

-f, --force¶: Force mode

colrev push¶

Push CoLRev project remote and record updates

colrev push [OPTIONS]

Options

-r, --records_only¶: Update records only

-p, --project_only¶: Push project only

-a, --all¶: Push record changes/corrections to all sources (not just curations).

-v, --verbose¶: Verbose: printing more infos

-f, --force¶: Force mode

colrev distribute¶

Distribute records to other local repositories

colrev distribute [OPTIONS]

Options

-p, --path <path>¶: Path to file(s)

-v, --verbose¶: Verbose: printing more infos

-f, --force¶: Force mode

colrev validate¶

Validate changes in the given commit (scope)

The validation scope argument can be
- A commit-sha,
- ‘.’ for the latest commit,
- HEAD~4 for commit 4 before HEAD
- A contributor name

colrev validate [OPTIONS] SCOPE

Options

--filter <filter_settings>¶

prepare, merge, or all.

Options:: prepare | dedupe | merge | all

--threshold <threshold>¶: Change score threshold for changes to display.

--properties¶: Flag indicating whether to validate the review properties.

-v, --verbose¶: Verbose: printing more infos

-f, --force¶: Force mode

Arguments

SCOPE¶: Required argument

colrev trace¶

Trace a record

colrev trace [OPTIONS]

Options

--id <record_id>¶: Required Record ID to trace (citation_key).