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

--view: View search sources

--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).