PIDGIN-STOP(1)

NAME
pidgin-stop - Stop running experiments gracefully

SYNOPSIS
pidgin stop [EXPERIMENT_ID]
pidgin stop --all

DESCRIPTION
The stop command gracefully terminates running experiments. It ensures that any in-progress conversations are completed and data is properly saved before shutting down the experiment daemon.

You can stop a specific experiment by providing its ID (full or shortened) or name, or stop all running experiments at once with the --all flag.

ARGUMENTS

EXPERIMENT_ID
    The experiment to stop. Can be:

    •   Full experiment ID (e.g., experiment_7a8b9c0d)

    •   Shortened ID (e.g., 7a8b9c0d or even 7a8b)

    •   Experiment name (e.g., "bright-horizon")

OPTIONS

--all
    Stop all running experiments. This option cannot be used with an experiment ID.

BEHAVIOR
When stopping an experiment:

    1.  The stop signal is sent to the experiment daemon

    2.  Any conversations currently processing a turn are allowed to complete

    3.  Pending conversations are cancelled

    4.  All JSONL event files are properly closed

    5.  The experiment status is updated to "stopped"

    6.  Database import is triggered for completed conversations

The command will wait for graceful shutdown (up to 30 seconds) before forcing termination if necessary.

EXAMPLES

Stop a specific experiment by ID:
    pidgin stop experiment_7a8b9c0d

Stop using shortened ID:
    pidgin stop 7a8b

Stop by experiment name:
    pidgin stop bright-horizon

Stop all running experiments:
    pidgin stop --all

EXIT STATUS

0   Successfully stopped the experiment(s)

1   Error occurred (experiment not found, already stopped, etc.)

FILES

./pidgin_output/experiments/*/manifest.json
    Updated with stop timestamp and final status

./pidgin_output/experiments/*/daemon.pid
    PID file removed after successful stop

NOTES
Stopping an experiment does not delete any data. All conversations completed before the stop are preserved and can be analyzed. The experiment can be analyzed using the auto-generated Jupyter notebook or DuckDB after stopping.

If an experiment appears to be hung, you can force-terminate it by manually killing the process using the PID from the daemon.pid file, though this is not recommended as it may result in incomplete data.

SEE ALSO
pidgin(1), pidgin-run(1), pidgin-monitor(1), pidgin-info(1)

AUTHOR
Nicholas Lange and contributors