fairguard 0.10.2

FAIR4RS compliance checker for research software

FAIRGuard

FAIR4RS compliance checker for research software.

Checks your software project against the 17 FAIR4RS principles (Findable, Accessible, Interoperable, Reusable) and gives you a compliance score.

Work in progress.

How it works

FAIRGuard uses a plugin system to check each FAIR4RS principle. Built-in plugins cover all 17 principles:

• Findable: persistent identifiers, metadata, searchability
• Accessible: retrieval protocols, access documentation
• Interoperable: standard data formats, qualified references
• Reusable: license, provenance, community standards

Install

pipx install fairguard       # isolated install, recommended on shared machines
# or
pip install --user fairguard

For development:

pip install -e ".[dev]"

Usage

Basic assessment

# assess the current directory
fairguard assess

# assess a specific repository
fairguard assess /path/to/repo

# assess a remote repository
fairguard assess https://github.com/org/repo

# shorthand for GitHub repos
fairguard assess org/repo

# Codeberg / Gitea / Forgejo repos work the same way
fairguard assess https://codeberg.org/owner/repo

# verbose output with evidence details
fairguard assess . -v

# quiet mode (exit code only, no output)
fairguard assess . -q

Forge support

Forge	Token env var	CLI flag	Notes
GitHub	GITHUB_TOKEN or GH_TOKEN	--github-token	github.com and self-hosted GHE
GitLab	GITLAB_TOKEN	--gitlab-token	gitlab.com and self-hosted (set GITLAB_URL)
Codeberg	CODEBERG_TOKEN	--gitea-token	codeberg.org
Gitea / Forgejo	GITEA_TOKEN	--gitea-token	self-hosted (set GITEA_URL if needed)

Tokens are only required for higher rate limits or to read private repositories. Public repos on any supported forge can be assessed anonymously.

Output formats

FAIRGuard supports three output formats: text (default), json, and markdown.

# print json to terminal
fairguard assess . --format json

# print markdown to terminal
fairguard assess . --format markdown

Saving reports to file

Use --output (-o) to write the report to a file. The format is determined by --format:

# save as markdown
fairguard assess . --format markdown --output report.md

# save as json
fairguard assess . --format json --output results.json

# save as plain text
fairguard assess . --output report.txt

If you pass a directory instead of a file, FAIRGuard auto-names the file:

# creates ./reports/fairguard-report.md
fairguard assess . --format markdown --output ./reports/

Publishing to a FAIRGuard backend

One-step assess + upload, no JSON file in between:

export FAIRGUARD_BACKEND_URL=https://fairguard.example.org
export FAIRGUARD_API_KEY=fg_xxxxxxxxxxxxxxxx

fairguard assess . --publish

The two-step flow still works if you need the JSON for something else:

fairguard assess . --format json --output report.json
fairguard publish report.json

fairguard publish - reads JSON from stdin, so this also works:

fairguard assess . --format json | fairguard publish -

Resolution order for --backend-url and --api-key: CLI flag, then FAIRGUARD_BACKEND_URL / FAIRGUARD_API_KEY env vars, then backend_url and api_key in .fairguard.yml, then default http://localhost:8000. Avoid committing api_key to the config file -- the CLI warns when it loads one from disk.

Profiles

# use a specific profile
fairguard assess . --profile minimal

# list available profiles
fairguard profile list

# show profile details
fairguard profile show strict

Skip indicators

# skip an indicator
fairguard assess . --skip persistent_identifier

# skip with a reason
fairguard assess . --skip "persistent_identifier:no DOI yet"

# skip multiple
fairguard assess . --skip persistent_identifier --skip metadata_persistence

Other commands

# list plugins and their indicators
fairguard plugin list
fairguard plugin info license_check

# list FAIR4RS indicators
fairguard indicator list
fairguard indicator list -v             # with descriptions
fairguard indicator list --unimplemented

# initialize a config file
fairguard init

# validate config
fairguard validate

# check plugin dependencies
fairguard deps

Exit codes

Code	Meaning
0	All indicators pass
1	One or more indicators failed
2	Error or quality gate failed

Configuration

FAIRGuard looks for a .fairguard.yml file in the repository root (or any parent directory). You can also pass a config file explicitly with --config. Run fairguard init to create one.

Example .fairguard.yml:

profile: default
skip_indicators:
  - metadata_persistence

quality_gate:
  min_compliance: bronze
  min_score: 4.0
  required_indicators:
    - clear_license

quality_goals:
  target_compliance: gold
  target_score: 7.0

Profiles

Three built-in profiles are available:

• default -- all 17 indicators, threshold 5.0
• minimal -- only the 4 Bronze-essential indicators (persistent_identifier, clear_license, open_access_protocol, community_standards)
• strict -- all 17 indicators at Platinum threshold (8.0)

Select a profile via --profile flag or the profile key in .fairguard.yml.

Quality Gates

Quality gates enforce minimum requirements. The assessment will report PASSED or FAILED:

• min_compliance: minimum compliance level (none/bronze/silver/gold/platinum)
• min_score: minimum overall score
• required_indicators: list of indicators that must pass

Quality Goals

Quality goals are aspirational targets for tracking progress. They are non-blocking -- the assessment always completes, but shows whether each goal is met.

Extra Features

For detailed HTML reports, assessment trends, team dashboards, batch/organization scanning, and more, visit fairguard.org.

License

AGPL-3.0 with Commons Clause