.. index:: Registry, Workflow Registry

.. _registry:

Workflow Registry
=================

The registry is bio-pype's package manager for bioinformatics workflows. It provides
a way to discover, install, update, and manage versioned workflow packages distributed
via git repositories.

Concepts
--------

**Registry**
  A git repository containing a manifest of available workflows. The default registry
  is ``https://codeberg.org/bio-pype/workflows-registry.git``. You can configure
  additional registries or use a private one.

**Workflow package**
  A directory containing snippets, pipelines, profiles, and/or queues subdirectories
  — the same layout as a ``PYPE_MODULES`` directory. Packages are versioned using
  date-based version strings (e.g., ``2026.03.11-1``).

**Activation**
  Once installed, a workflow is activated by setting the ``PYPE_MODULES`` environment
  variable to its local path. The recommended pattern uses ``pype registry path`` to
  get the correct path::

      export PYPE_MODULES=$(pype registry path somatic==2026.03.11-1)

Getting Started
---------------

**1. Sync the registry**

Fetch the manifest of available workflows from the remote registry::

    pype registry sync

This downloads the registry index to the local cache (``~/.bio_pype/cache/``).
No workflows are installed yet — this is just the index.

To sync a specific registry URL::

    pype registry sync https://codeberg.org/my-org/my-registry.git

**2. Search available workflows**

List all workflows in the synced registry::

    pype registry search

Filter by keyword::

    pype registry search somatic

Add ``-a`` / ``--all`` for detailed information (versions, maintainer, tags, homepage)::

    pype registry search -a

**3. Install a workflow**

Install the latest version of a workflow::

    pype registry install qc

Install a specific version::

    pype registry install somatic==2026.03.11-1

When installing over an existing version, any local modifications you made to the
previous version are automatically carried forward to the new version.

**4. Activate the workflow**

After installation, set ``PYPE_MODULES`` to activate the workflow for use in bio-pype::

    export PYPE_MODULES=$(pype registry path somatic==2026.03.11-1)

To make this permanent for a specific project, add it to your shell profile or
a project activation script.

**5. Set up your profile**

Workflow packages often include a profile **spec** (a ``.yaml.spec`` file). When
one is present, build the profile automatically — Bio_pype downloads and builds
the reference files and pulls the software for you::

    pype profiles build hg38 --ref-dir /data/references

If the package ships a plain profile template instead, edit it to point at
resources you already have::

    pype profiles edit hg38

See :ref:`building_profiles` for the spec format and build options, or
:ref:`profiles` for the full profile reference.

Managing Installed Workflows
----------------------------

**List installed workflows**::

    pype registry list

Shows a compact table of all installed packages and their versions.

**Update a workflow**::

    pype registry update somatic

Installs the latest version and carries forward your local modifications.

**Remove a workflow**::

    pype registry remove somatic

**Get the path to an installed workflow**::

    pype registry path somatic==2026.03.11-1

This is the same command used in the ``export PYPE_MODULES=$(...)`` pattern.

Publishing Workflows
--------------------

If you are a workflow developer who wants to publish to a registry, see the
``pype registry init``, ``pype registry manifest``, and ``pype registry publish``
commands.

**Initialize a new registry**::

    pype registry init ./my-registry --name "My Workflows" --maintainer "My Name"

This creates a ``repo.yaml`` file in the specified directory. The directory should
be a git repository that you push to a remote (e.g., Codeberg or GitHub).

**Publish a new workflow version**::

    pype registry publish registry_module_path workflow_package_dir

Where ``registry_module_path`` is your local registry directory and
``workflow_package_dir`` is the directory containing the workflow to publish.

**Rebuild the manifest** (after manually editing version files)::

    pype registry manifest

Configuration
-------------

The default registry URL can be changed in ``~/.bio_pype/config``::

    PYPE_REGISTRY=https://codeberg.org/my-org/my-registry.git

Or per-command using the ``--registry`` flag::

    pype registry sync --registry https://codeberg.org/my-org/my-registry.git
    pype registry search --registry https://codeberg.org/my-org/my-registry.git

The local cache is stored in ``~/.bio_pype/cache/`` by default. Override with
``--cache``::

    pype registry sync --cache /custom/cache/path