Running Workflows Locally

The voc4cat-template includes a justfile with the same commands as used in GitHub Actions. This enables running the actions workflows locally on your machine exactly as they are run in GitHub actions, which is very useful to

  • debug workflow issues

  • test and develop voc4cat-tool code

  • test migrating to a new version

Prerequisites

  • just - A command runner (like make, but simpler)

  • uv - A fast Python package manager

Installing uv

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

Installing just

just is available via PyPI. So we can use uv (or pipx) to install

uv tool install rust-just

Alternatively, you can download from just’s GitHub releases page.

Available commands

From the root of a voc4cat-template based repository, run just to see available commands:

$ just
Available recipes:
    all     # Run all steps as in gh-actions: check xlsx, convert to SKOS, build docs, re-build xlsx

    [environment]
    clean   # Remove all generated files/directories
    setup   # Run initial setup (run this first)
    upgrade # Upgrades voc4cat-tool installation

    [individual steps]
    check   # Check the *.xlsx file(s) in inbox/ for errors
    convert # Convert the voc4cat.xlsx file in inbox/ to turtle
    docs    # Run voc4cat (build HTML documentation from ttl files)
    join    # Join individual ttl files in vocabularies/ to one turtle file in outbox/
    prov    # Add provenance information to all ttl files in vocabularies/
    xlsx    # Rebuild the xlsx file from the joined ttl file.

Command descriptions

Command

Description

just setup

Initial setup - installs voc4cat as a uv tool

just check

Validate xlsx files in inbox-excel-vocabs/

just convert

Convert xlsx to turtle format

just docs

Generate HTML documentation from turtle files

just xlsx

Rebuild xlsx from turtle (round-trip test)

just all

Run the complete pipeline (check → convert → docs → xlsx)

just join

Join the turtle files in vocabularies/ into one file in outbox/

just prov

Add provenance dates to vocabularies/, as the pull-request workflow does

just clean

Remove generated files and directories

just upgrade

Update voc4cat-tool to the latest version

Typical local workflow

First-time setup

# Clone your vocabulary repository
git clone https://github.com/yourorg/your-vocabulary.git
cd your-vocabulary

# Run initial setup
just setup

No environment variables need to be set manually. The justfile automatically creates _main_branch/ and copies idranges.toml when running just check, just convert or just xlsx.

Tip

For verbose output, set LOGLEVEL=DEBUG before running commands:

export LOGLEVEL=DEBUG  # Linux/macOS
set LOGLEVEL=DEBUG     # Windows cmd

Testing changes

  1. Place your modified xlsx file in inbox-excel-vocabs/

  2. Run the full pipeline:

just all

  1. Review the output:

    • Check console for validation errors

    • Inspect the intermediate files and HTML documentation in outbox/

    • Inspect generated turtle files in vocabularies/

Troubleshooting

idranges comparison with main branch

In CI, the workflow prevents unauthorized modification of idranges.toml by comparing it against the main branch version. The justfile automatically creates _main_branch/ and copies your local idranges.toml there.

Note

The automatic setup copies your current idranges.toml. If you’re testing changes to idranges.toml itself and want to simulate exact CI behavior, manually copy the main branch version:

git show main:idranges.toml > _main_branch/idranges.toml

Outdated voc4cat-tool

just setup installs the version of voc4cat that was current at the time. To move to the latest release:

just upgrade

See also