CLI Guide
=========

Complete guide to using the wosecopy command-line interface.

Overview
--------

wosecopy provides a comprehensive CLI for all operations. All commands follow this pattern:

.. code-block:: bash

   wosecopy COMMAND [ARGUMENTS] [OPTIONS]

Getting Help
------------

.. code-block:: bash

   # General help
   wosecopy --help

   # Command-specific help
   wosecopy extract --help
   wosecopy metrics --help

Common Workflows
----------------

Basic Analysis Pipeline
~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   # 1. Extract concepts
   wosecopy extract stories.csv -o results.csv

   # 2. Calculate metrics
   wosecopy metrics results.csv -o metrics.json

   # 3. Visualize
   wosecopy visualize results.csv -o graph.png --index 0

Research Workflow
~~~~~~~~~~~~~~~~~

.. code-block:: bash

   # Extract concepts
   wosecopy extract study_data.csv -o results.csv --language en

   # Analyze by ratings
   wosecopy analyze-ratings results.csv --rating-column creativity -o grouped.json

   # Compare raters
   wosecopy compare results.csv -r rating_h -r rating_j -r rating_k -o plots/

   # Calculate unexpectedness
   wosecopy unexpectedness results.csv --prompt-column prompt -o creativity.csv

   # Export graphs for network analysis
   wosecopy export results.csv -o graphs/ --format graphml

Command Reference
-----------------

See :doc:`api/cli` for detailed command reference.

Examples
--------

Extract with Custom Settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   wosecopy extract german_stories.csv \
       -o results_de.csv \
       --language de \
       --text-column Text \
       --similarity-threshold 0.6

Export Multiple Formats
~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   # GraphML for Gephi
   wosecopy export results.csv -o graphs/graphml/ --format graphml

   # GEXF for Gephi
   wosecopy export results.csv -o graphs/gexf/ --format gexf

   # GML for other tools
   wosecopy export results.csv -o graphs/gml/ --format gml

Batch Processing
~~~~~~~~~~~~~~~~

.. code-block:: bash

   # Process multiple files
   for file in data/*.csv; do
       wosecopy extract "$file" -o "results/$(basename $file)"
   done

Tips and Tricks
---------------

Progress Bars
~~~~~~~~~~~~~

Most commands show progress bars by default. The extraction command uses ``tqdm`` for progress tracking.

Output Organization
~~~~~~~~~~~~~~~~~~~

Organize outputs by creating a clear directory structure:

.. code-block:: bash

   mkdir -p outputs/{graphs,metrics,plots,results}

   wosecopy extract data.csv -o outputs/results/concepts.csv
   wosecopy metrics outputs/results/concepts.csv -o outputs/metrics/stats.json
   wosecopy export outputs/results/concepts.csv -o outputs/graphs/
   wosecopy compare ... -o outputs/plots/

Chaining Commands
~~~~~~~~~~~~~~~~~

Use command chaining for automated workflows:

.. code-block:: bash

   wosecopy extract data.csv -o results.csv && \
   wosecopy metrics results.csv -o metrics.json && \
   wosecopy visualize results.csv -o graph.png

Troubleshooting
---------------

Model Not Found
~~~~~~~~~~~~~~~

If you see "Model not found" errors:

.. code-block:: bash

   wosecopy download-model --language en --size lg

Column Not Found
~~~~~~~~~~~~~~~~

Check your column names:

.. code-block:: bash

   # Use head to inspect CSV
   head -n 1 data.csv

   # Then specify correct column
   wosecopy extract data.csv --text-column YourColumnName

Empty Results
~~~~~~~~~~~~~

If extraction produces empty results:

1. Check that sentences are separated by periods
2. Verify the text column has actual content
3. Try lowering similarity threshold
4. Check the language setting matches your data