Command Reference¶
Comprehensive reference of every command available in this project.
Auto-generated from Taskfile definitions, script --help output, and
Hatch environment configuration.
Generation details
| Field | Value |
|---|---|
| Command | python scripts/generate_command_reference.py |
| Timestamp | 2026-04-02 13:01:50 UTC |
| Generator version | 1.4.0 |
| Python | 3.12.13 |
| Platform | Linux 6.17.0-1008-azure |
Quick start
Most developers only need task check (run all quality gates) and
task test (run tests). See Developer Commands
for a guided walkthrough.
Taskfile Commands¶
Run any task with task <name>. Pass extra arguments with -- <args> (e.g., task test -- -v).
Could not parse Taskfile. Is task installed?
Scripts¶
Standalone utilities in scripts/. Run with python scripts/<name>.py or via the corresponding Taskfile shortcut.
apply_labels.py¶
File: scripts/apply_labels.py
Full --help output
usage: apply_labels.py [-h] --set {baseline,extended} [--repo REPO]
[--dry-run] [--version]
Apply GitHub labels to a repository from a JSON label set.
options:
-h, --help show this help message and exit
--set {baseline,extended}
--repo REPO OWNER/REPO; default is current repo
--dry-run
--version show program's version number and exit
archive_todos.py¶
File: scripts/archive_todos.py
Full --help output
usage: archive_todos [-h] [--version] [--dry-run] [--quiet] [--no-backup]
[--todo-file TODO_FILE] [--archive-file ARCHIVE_FILE]
Archive completed TODO items from docs/notes/todo.md.
options:
-h, --help show this help message and exit
--version show program's version number and exit
--dry-run Show what would change without modifying files
--quiet, -q Suppress informational output (errors still shown)
--no-backup Skip creating .bak files before writing
--todo-file TODO_FILE
Path to todo file (default: /home/runner/work/simple-
python-boilerplate/simple-python-
boilerplate/docs/notes/todo.md)
--archive-file ARCHIVE_FILE
Path to archive file (default:
/home/runner/work/simple-python-boilerplate/simple-
python-boilerplate/docs/notes/archive.md)
bootstrap.py¶
File: scripts/bootstrap.py
Full --help output
usage: bootstrap [-h] [--version] [--skip-hooks] [--skip-test-matrix]
[--dry-run] [--smoke] [--strict] [--fix] [--ci-like]
One-command setup for fresh clones.
options:
-h, --help show this help message and exit
--version show program's version number and exit
--skip-hooks Skip pre-commit hook installation
--skip-test-matrix Skip creating test.py3.x environments (faster setup)
--dry-run Show what would happen without making changes
--smoke Quick import and arg-parse health check; exit 0
immediately
--strict Run optional quality pass (ruff + mypy) after setup
--fix With --strict, auto-fix ruff issues where possible
--ci-like Run all checks including quality pass and docs build
(mirrors CI pipeline)
changelog_check.py¶
File: scripts/changelog_check.py
Full --help output
usage: changelog_check.py [-h] [--version] [--verbose | --quiet]
[--changelog-path CHANGELOG_PATH] [--smoke]
Verify CHANGELOG.md entries match git tags.
options:
-h, --help show this help message and exit
--version show program's version number and exit
--verbose, -v Show versions that are in sync
--quiet, -q Suppress output; exit code only (for CI)
--changelog-path CHANGELOG_PATH
Path to CHANGELOG.md (default:
/home/runner/work/simple-python-boilerplate/simple-
python-boilerplate/CHANGELOG.md)
--smoke Quick import and arg-parse health check; exit 0
immediately
check_known_issues.py¶
File: scripts/check_known_issues.py
Full --help output
usage: check_known_issues.py [-h] [--days N] [--issues-path PATH] [--json]
[-q] [--version] [--smoke]
Check docs/known-issues.md for stale resolved entries. Exits non-zero if any
entry has been in the Resolved table longer than --days.
options:
-h, --help show this help message and exit
--days N Max age in days for resolved entries (default: 90)
--issues-path PATH Path to known-issues.md (default: docs/known-issues.md)
--json Output results as JSON
-q, --quiet Suppress output; exit code only
--version show program's version number and exit
--smoke Quick import and arg-parse health check; exit 0
immediately
check_python_support.py¶
File: scripts/check_python_support.py
Full --help output
usage: check-python-support [-h] [--version] [--json] [--quiet] [--no-color]
[--smoke]
Validate Python version support is consistent across config files.
options:
-h, --help show this help message and exit
--version show program's version number and exit
--json Output as JSON
--quiet, -q Suppress output; exit code only
--no-color Disable colored output
--smoke Quick import and arg-parse health check; exit 0 immediately
check_todos.py¶
File: scripts/check_todos.py
Full --help output
usage: check_todos.py [-h] [--version] [--pattern PATTERN] [--count | --json]
[--exclude EXCLUDE] [--smoke]
Scan for TODO (template users) comments in the repository.
options:
-h, --help show this help message and exit
--version show program's version number and exit
--pattern PATTERN Text pattern to search for (default: "TODO (template
users)")
--count Only print the count of TODOs found
--json Output results as JSON (for CI integration)
--exclude EXCLUDE Additional path prefixes to exclude (relative to project
root)
--smoke Quick import and arg-parse health check; exit 0
immediately
exit codes:
0 No TODOs found (template fully customized)
1 TODOs remain (useful as a CI gate)
clean.py¶
File: scripts/clean.py
Full --help output
usage: clean [-h] [--version] [--dry-run] [--quiet] [--include-venv] [--yes]
[--smoke]
Remove build artifacts and caches from the repository.
options:
-h, --help show this help message and exit
--version show program's version number and exit
--dry-run Show what would be removed without deleting
--quiet, -q Suppress informational output (exit code still shown)
--include-venv Also remove .venv* directories (requires confirmation)
--yes, -y Skip confirmation prompt for --include-venv
--smoke Quick import and arg-parse health check; exit 0 immediately
exit codes:
0 Clean completed successfully (or aborted by user)
1 Error during cleanup
customize.py¶
File: scripts/customize.py
Full --help output
usage: customize.py [-h] [--version] [--quiet] [--non-interactive]
[--project-name PROJECT_NAME]
[--package-name PACKAGE_NAME] [--author AUTHOR]
[--github-user GITHUB_USER] [--description DESCRIPTION]
[--cli-prefix CLI_PREFIX]
[--license {apache-2.0,mit,bsd-3-clause}]
[--strip [DIR ...]] [--template-cleanup [ITEM ...]]
[--force] [--private-repo] [--enable-workflows OWNER/REPO]
[--export-config [PATH]] [--apply-from PATH] [--dry-run]
Interactive project customization — replaces boilerplate placeholders with your project's values.
options:
-h, --help show this help message and exit
--version show program's version number and exit
--quiet, -q Suppress informational output (errors still shown)
--non-interactive Skip interactive prompts; use CLI arguments for all
values
--project-name PROJECT_NAME
Project name (lowercase-hyphenated)
--package-name PACKAGE_NAME
Python package name (underscored; auto-derived from
--project-name if omitted)
--author AUTHOR Author name
--github-user GITHUB_USER
GitHub username or organization
--description DESCRIPTION
One-line project description
--cli-prefix CLI_PREFIX
CLI command prefix (default: initials of project name)
--license {apache-2.0,mit,bsd-3-clause}
License to use (default: apache-2.0)
--strip [DIR ...] Optional directories to remove. Choices: db,
experiments, var, docs-templates, container, optional-
workflows, labels, repo-doctor, mkdocs-hooks, repo-
sauron, git-config-ref, test-config-ref, commit-
report, codecov-config, readthedocs-config, release-
automation-config, requirements-files, linting-config,
link-checker, git-templates, vscode-config, code-
workspace, all-scripts, unit-tests, integration-tests,
all-tests, src-content, docs-all, github-all, pre-
commit-config, taskfile-config, mkdocs-config,
dependabot-config, typos-config, changelog, github-
issue-templates, github-config-files
--template-cleanup [ITEM ...]
Template-specific items to clean up. Choices: adr-
files, docs-notes, docs-design, docs-reference, docs-
development, docs-guide, placeholder-code, utility-
scripts, advanced-workflows
--force Skip the already-customized safety check
--private-repo Strip open-source community files not needed for
private repos (CODE_OF_CONDUCT, CONTRIBUTING,
SECURITY, scorecard workflow, etc.)
--enable-workflows OWNER/REPO
Enable all GitHub workflows by replacing
'YOURNAME/YOURREPO' placeholder. Pass your repo slug
(e.g. 'myorg/myproject'). Runs only this operation.
--export-config [PATH]
Export customization options to a Markdown file for
offline editing. Default output: customize-config.md
--apply-from PATH Apply customization from an edited Markdown config
file (generated by --export-config).
--dry-run Preview mode: show what --apply-from would do without
modifying any files. Generates a preview report to
customize-report.md.
examples:
python scripts/customize.py
python scripts/customize.py --apply-from customize-config.md
python scripts/customize.py --non-interactive \
--project-name my-project --author "Jane Doe" \
--github-user janedoe
dep_versions.py¶
File: scripts/dep_versions.py
Full --help output
usage: dep_versions [-h] [--version] [--smoke]
{show,update-comments,upgrade} ...
Dependency version manager for pyproject.toml and requirements files.
positional arguments:
{show,update-comments,upgrade}
Available commands
show Show installed and latest versions of all dependencies
(default).
update-comments Update inline version comments in pyproject.toml and
requirements*.txt files. Adds descriptions and
versions to lines that have no comment.
upgrade Upgrade dependencies via pip.
options:
-h, --help show this help message and exit
--version show program's version number and exit
--smoke Quick import and arg-parse health check; exit 0
immediately (aliases --offline for consistency with
other scripts)
doctor.py¶
File: scripts/doctor.py
Full --help output
usage: doctor [-h] [--version] [--output OUTPUT]
[--markdown | --json | --quiet] [--no-color] [--smoke]
Print a diagnostics bundle for bug reports.
options:
-h, --help show this help message and exit
--version show program's version number and exit
--output OUTPUT, -o OUTPUT
Write output to file (e.g., var/doctor.txt)
--markdown Output as markdown (for GitHub issues)
--json Output as JSON (machine-readable)
--quiet, -q Print a one-line summary only
--no-color Disable colored output
--smoke Quick import and arg-parse health check; exit 0
immediately
env_doctor.py¶
File: scripts/env_doctor.py
Full --help output
usage: env_doctor.py [-h] [--version] [--strict] [--no-color] [--json]
[--smoke]
Quick environment health check for development.
options:
-h, --help show this help message and exit
--version show program's version number and exit
--strict Treat optional tool warnings as failures
--no-color Disable colored output
--json Output results as JSON (for CI integration)
--smoke Quick import and arg-parse health check; exit 0 immediately
env_inspect.py¶
File: scripts/env_inspect.py
Full --help output
usage: env-inspect [-h] [--version] [--json]
[--section {python,python-installs,git,venv,packages,entrypoints,build-tools,python-support,path,system}]
[--quiet] [--no-color] [--smoke]
Environment and dependency inspector.
options:
-h, --help show this help message and exit
--version show program's version number and exit
--json Output as JSON
--section {python,python-installs,git,venv,packages,entrypoints,build-tools,python-support,path,system}
Only show a specific section
--quiet, -q Suppress output; exit code only
--no-color Disable colored output
--smoke Quick import and arg-parse health check; exit 0
immediately
generate_command_reference.py¶
File: scripts/generate_command_reference.py
Full --help output
usage: generate_command_reference [-h] [--check] [--dry-run] [--version]
Generate docs/reference/commands.md from project commands.
options:
-h, --help show this help message and exit
--check Exit 1 if the generated file differs from the existing one (CI
mode).
--dry-run Print generated Markdown to stdout instead of writing to disk.
--version show program's version number and exit
git_doctor.py¶
File: scripts/git_doctor.py
Full --help output
usage: git_doctor.py [-h] [--version] [--no-color] [--json]
[--export-config [PATH]] [--apply-from PATH]
[--apply-recommended] [--apply-recommended-minimal]
[--dry-run] [--new-branch] [--watch [SECONDS]]
[--refresh] [--cleanup] [--view-commits] [--markdown]
[--smoke]
Git-focused health check and information dashboard.
options:
-h, --help show this help message and exit
--version show program's version number and exit
--no-color Disable colored output
--json Output results as JSON (for CI integration)
--export-config [PATH]
Export comprehensive git config reference to a
Markdown file (default: git-config-reference.md).
NOTE: overwrites the file on each run.
--apply-from PATH Apply desired values from an edited config reference
file (exported with --export-config). Both 'Desired
value' and 'Desired scope' columns must be set for an
entry to apply.
--apply-recommended Apply ALL catalog recommended values and scopes,
overwriting existing values. Resets config to the
catalog baseline. Use --dry-run to preview. See git-
config-reference.md for details.
--apply-recommended-minimal
Apply only the core minimal set of recommended configs
(12 high-impact keys). Safer alternative to --apply-
recommended for first-time setup. Use --dry-run to
preview.
--dry-run With --apply-from, --apply-recommended, --apply-
recommended-minimal, --refresh, --cleanup, or --new-
branch: show what would be changed without applying
--new-branch Interactive branch creation: prompts for a name,
creates the branch off origin/main, pushes with
upstream tracking, and prints a summary of all
commands executed
--watch [SECONDS] Re-run the dashboard every N seconds (default: 10).
Press Ctrl+C to stop.
--refresh Interactive refresh: fetch all remotes, prune stale
remote-tracking refs, sync tags, and update remote
HEAD. Shows a preview and asks for confirmation before
running. Use --dry-run to preview without executing.
--cleanup Interactive cleanup: delete stale local branches (90+
days inactive), branches with deleted upstreams, and
run git gc. Shows everything that would be deleted and
asks for confirmation. Use --dry-run to preview only.
--view-commits Show detailed commit report for the current working
branch: branch origin, all SHAs, messages, authors,
dates, per-file insertions/deletions, and conflict
detection with the default branch. Use --markdown to
write a Markdown report file instead.
--markdown With --view-commits, write a Markdown commit report to
commit-report.md (in the repo root) instead of
terminal output. Includes quick stats, a clickable
table of contents, and GitHub links.
--smoke Quick import and arg-parse health check; exit 0
immediately
repo_doctor.py¶
File: scripts/repo_doctor.py
Full --help output
usage: repo_doctor.py [-h] [--version] [--missing] [--staged] [--diff RANGE]
[--category CAT] [--min-level {info,warn}]
[--include-info] [--profile NAME] [--no-hints]
[--no-links] [--fix] [--no-color] [--show-passed]
[--strict] [--smoke [NAME]]
Warn-only repo doctor checks (missing files, deletions, config presence).
options:
-h, --help show this help message and exit
--version show program's version number and exit
--missing Report missing files/dirs in working tree.
--staged Report staged deletions (index).
--diff RANGE Report deletions in a git diff range, e.g.
"origin/main...HEAD".
--category CAT Only show rules matching this category (e.g. ci,
hooks, security).
--min-level {info,warn}
Minimum severity to display (default: warn). Use
'info' to include everything.
--include-info Include info-level checks (shorthand for --min-level
info).
--profile NAME Load additional rules from repo_doctor.d/NAME.toml
(repeatable; 'all' loads everything).
--no-hints Hide hint lines.
--no-links Hide link/reference lines.
--fix Show auto-fix commands for rules that define one.
--no-color Disable colored output.
--show-passed Show checks that passed (in addition to warnings).
--strict Exit non-zero when warnings are found (for CI gating).
--smoke [NAME] Inject a synthetic failure to test dashboard
appearance. Optionally specify a profile name (e.g.
'ci') to fail its first check; if omitted, a random
loaded rule is chosen.
repo_sauron.py¶
File: scripts/repo_sauron.py
Full --help output
usage: repo-sauron [-h] [--version] [--output OUTPUT] [--json] [--quiet]
[--smoke]
Repository statistics dashboard — generates a Markdown report.
options:
-h, --help show this help message and exit
--version show program's version number and exit
--output OUTPUT, -o OUTPUT
Output file path (default: repo-sauron-report.md)
--json Output as JSON instead of Markdown
--quiet, -q Suppress output; exit code only
--smoke Quick import and arg-parse health check; exit 0
immediately
test_containerfile.py¶
File: scripts/test_containerfile.py
Full --help output
usage: test_containerfile.py [-h] [--version] [--dry-run] [--keep] [--verbose]
[--timeout N]
Test the Containerfile: build, validate, clean up.
options:
-h, --help show this help message and exit
--version show program's version number and exit
--dry-run Show what would be executed without running
--keep Keep the test image after running (skip cleanup)
--verbose Show full command output including stderr
--timeout N Per-step timeout in seconds (default: 300)
test_docker_compose.py¶
File: scripts/test_docker_compose.py
Full --help output
usage: test_docker_compose.py [-h] [--version] [--dry-run] [--keep]
[--verbose] [--timeout N]
Test the docker compose stack: build, run, validate, clean up.
options:
-h, --help show this help message and exit
--version show program's version number and exit
--dry-run Show what would be executed without running
--keep Keep containers and images after running (skip cleanup)
--verbose Show full command output including stderr
--timeout N Per-step timeout in seconds (default: 300)
workflow_versions.py¶
File: scripts/workflow_versions.py
Full --help output
usage: workflow_versions [-h] [--version] [--color | --no-color] [--quiet]
[--smoke]
{show,update-comments,upgrade} ...
Show and update version comments on SHA-pinned GitHub Actions in
.github/workflows/.
positional arguments:
{show,update-comments,upgrade}
Available commands
show Show all SHA-pinned actions with comment and resolved
tags (default).
update-comments Update inline version comments and add action
descriptions. Comments are rewritten as '#
<description> (vX.Y.Z)'. Requires GitHub API access.
upgrade Upgrade actions to their latest release (or a specific
version).
options:
-h, --help show this help message and exit
--version show program's version number and exit
--color Force colored output.
--no-color Disable colored output.
--quiet, -q Suppress table output. Exit non-zero if issues are
found (CI mode).
--smoke Quick import and arg-parse health check; exit 0
immediately
auto_chmod_scripts.py¶
File: scripts/precommit/auto_chmod_scripts.py
Full --help output
check_local_imports.py¶
File: scripts/precommit/check_local_imports.py
Full --help output
check_nul_bytes.py¶
File: scripts/precommit/check_nul_bytes.py
Full --help output
Shared Modules¶
Internal modules in scripts/ used by multiple scripts. Not intended to be run directly.
| Module | Description |
|---|---|
_colors.py |
Shared ANSI color utilities for scripts |
_container_common.py |
Shared helpers for container test scripts |
_doctor_common.py |
Shared utilities for doctor-family scripts |
_imports.py |
Shared import helper for scripts |
_progress.py |
Shared progress-indicator utilities for scripts |
_ui.py |
Shared dashboard UI utilities for scripts |
Hatch Environments¶
Managed by Hatch. Enter with hatch shell or run commands with hatch run <cmd>.
Could not capture Hatch environments. Is hatch installed?
CLI Entry Points¶
Console commands installed by pip install -e . or hatch shell. Defined in [project.scripts] in pyproject.toml.
| Command | Entry point |
|---|---|
spb |
simple_python_boilerplate.main:main |
spb-doctor |
simple_python_boilerplate.main:doctor |
spb-start |
simple_python_boilerplate.main:start |
spb-version |
simple_python_boilerplate.main:print_version |
Common Flag Patterns¶
Most scripts in this project follow consistent flag conventions:
| Flag | Meaning | Used by |
|---|---|---|
--help |
Show usage and exit | All scripts |
--version |
Print version and exit | All scripts |
--dry-run |
Preview changes without writing | clean, customize, bootstrap, dep_versions, workflow_versions, git_doctor |
--json |
Machine-readable JSON output | doctor, env_doctor, git_doctor, check_todos, check_known_issues |
--no-color |
Disable colored terminal output | doctor, env_doctor, git_doctor, repo_doctor, workflow_versions |
-q, --quiet |
Suppress informational output | clean, bootstrap, archive_todos, changelog_check, check_known_issues, workflow_versions |
Quick Reference¶
Flat summary of every available task.