.. _cli_usage:

=======================
Command-Line Interface
=======================

The `epmc-cli` tool provides a command-line interface for the Europe PMC API and for local file processing.

Usage
-----

.. code-block:: bash

    epmc-cli [OPTIONS] COMMAND [ARGS]...

Options
-------

*   `--email TEXT`: Contact email for API identification.
*   `--tool TEXT`: Tool name for API identification.

Commands
--------

*   `local`: Commands for local file processing.
*   `articles`: Commands for the Europe PMC Articles API.
*   `annotations`: Commands for the Europe PMC Annotations API.
*   `grants`: Commands for the Europe PMC Grants API.
*   `oai`: Commands for the Europe PMC OAI-PMH service.

Local Commands
--------------

The `local` command group provides tools for processing local files.

`jats2json`
~~~~~~~~~~~

Converts a JATS XML file to a structured JSON format. By default, it also performs sentence splitting.

The command intelligently detects the input type. The input can be a local file path, a URL pointing to a JATS XML file, or a Europe PMC article ID (PMCID).

.. code-block:: bash

    epmc-cli local jats2json <input> <path_to_output_json> [--no-sentenciser]

**Arguments:**

*   `INPUT`: The input to process. This can be a local file path, a URL, or a PMCID (e.g., `PMC11704132`).
*   `OUTPUT_PATH`: Path to save the output JSON file.

**Options:**

*   `--no-sentenciser`: Disable sentence splitting.

**Examples:**

*   **From a local file:**
    .. code-block:: bash

        epmc-cli local jats2json test_data/PXD053361.xml output.json

*   **From a URL:**
    .. code-block:: bash

        epmc-cli local jats2json https://www.ebi.ac.uk/europepmc/webservices/rest/PMC11704132/fullTextXML output.json

*   **From a PMCID:**
    .. code-block:: bash

        epmc-cli local jats2json PMC11704132 output.json

The tool provides specific error messages if the input file cannot be found, the URL is invalid, or the PMCID does not have a full-text XML available.

`extract-accessions-resources`
--------------------------

Extracts accession numbers and resources from a JSON file (previously generated by `jats2json`).

.. code-block:: bash

    epmc-cli local extract-accessions-resources output.json accessions.json

You can also run this command in offline mode to avoid online validation of the extracted entities:

.. code-block:: bash

    epmc-cli local extract-accessions-resources output.json accessions.json --offline


Articles API
------------

**Search for articles:**

.. code-block:: bash

    epmc-cli articles search "machine learning" --page-size 1

**Get article metadata:**

.. code-block:: bash

    epmc-cli articles get PMC11704132

**Get full-text XML:**

.. code-block:: bash

    epmc-cli articles fulltext PMC11704132

Annotations API
---------------

**Get annotations by article ID:**

.. code-block:: bash

    epmc-cli annotations by-id PMC:11704132

**Find articles that cite a specific entity:**

.. code-block:: bash

    epmc-cli annotations by-entity p53

**Get annotations of a specific type:**

*   **By data accession:**

    .. code-block:: bash

        epmc-cli annotations by-type --type 'Accession Numbers' --subtype 'uniprot'

*   **By gene name:**

    .. code-block:: bash

        epmc-cli annotations by-type --type 'Gene_Proteins'

*   **By resource name:**

    .. code-block:: bash

        epmc-cli annotations by-type --type 'Resources'

Grants API
----------

**Search for grants:**

.. code-block:: bash

    epmc-cli grants search "cancer" --page-size 1

OAI Service
-----------

**Harvest metadata:**

.. code-block:: bash

    epmc-cli oai harvest --metadata-prefix oai_dc