CLI Tooling and Invokers
Relevant source files
The following files were used as context for generating this wiki page:
CLI Tooling and Invokers encompass the suite of command-line utilities and automation scripts used to maintain, validate, and manage the Infrahub skills repository. These tools ensure that all documentation, code snippets, and repository structures adhere to established standards and versioning requirements.
The tooling leverages uv for Python environment management and invoke as a task runner to execute complex maintenance workflows. Key functions include validating CLI command syntax in documentation, ensuring symlink integrity across different agent environments, and managing the project's tiered evaluation and release processes.
Task Automation with Invoke
The project uses tasks.py to define high-level automation routines. These tasks act as invokers for linters, formatters, and custom validation scripts.
| Task | Description | Command |
|---|---|---|
| Lint | Runs rumdl, yamllint, and check-cli-invocations.py to verify project health. | uv run invoke lint |
| Format | Fixes markdown formatting issues across the repository. | uv run invoke format |
| Test | Executes the full test suite using pytest. | uv run invoke test |
| Freshness | Compares the installed plugin against the current working tree. | uv run invoke freshness |
Sources: tasks.py, AGENTS.md:65-74
CI/CD Workflow Integration
The following diagram illustrates how the invoke tasks and scripts are utilized within the Continuous Integration pipeline to gate pull requests.
This flow ensures that no change breaks the CLI documentation or repository structure.
Sources: tasks.py, AGENTS.md:76-79, dev/guidelines/skill-authoring.md:104-108
CLI Command Validation
The script scripts/check-cli-invocations.py serves as a specialized validator for infrahubctl commands cited within the repository's Markdown files. It ensures that the commands taught to users and agents are technically accurate and supported by the current CLI tree.
Validation Scope
The validator scans specific targets defined in its SCAN_TARGETS configuration, including:
- All files under
skills/ - Grader libraries and scripts
- Test files and
eval.yaml - Agent-specific documentation in
.agents/skills/
Sources: dev/guidelines/skill-authoring.md:104-112, scripts/check-cli-invocations.py
CLI Tree Enforcement
Commands are judged against a reference tree pinned in graders/common/cli_tree.py. This prevents documentation from referencing non-existent flags or commands that have not yet been released. Documentation outside the scan targets, such as README.md and dev/specs/, is not subject to this automated check.
Sources: dev/guidelines/skill-authoring.md:104-112
Repository Structure and Symlinks
The project maintains a complex structure to support multiple AI agents (Claude, Cursor, Copilot). The scripts/check-symlinks.py tool is used to verify the integrity of these configurations.
Agent Adapter Pattern
The repository uses a system of relative symlinks to provide consistent rules and skills across different agent environments without duplicating files.
The diagram shows how the .claude/ and .codex/ directories act as adapters, linking back to the source of truth in .agents/.
Sources: AGENTS.md:102-114, scripts/check-symlinks.py
Dependency and Environment Management
The pyproject.toml file defines the environment and dependency groups required by the tooling.
Dependency Groups
- Dev Group: Includes
rumdl,invoke,ruff, andtowncrier. These are used for linting and release management. - Test Group: Includes
pytest,pyyaml, andinfrahub-sdk. This group is kept separate to prevent the SDK from bloating CI linting jobs that do not require it.
Sources: pyproject.toml:7-31
Release Tooling
The project uses towncrier to manage the changelog and release process. It assembles news fragments from the changelog/ directory into the final CHANGELOG.md.
# Example fragment creation
uv run towncrier create -c "Description of change" 123.added.md
Sources: pyproject.toml:60-104, AGENTS.md:144-149
Conclusion
The CLI tooling and invokers provide a robust foundation for the Infrahub skills project. By automating the validation of CLI syntax, repository links, and formatting, these tools ensure that the AI skills remain high-quality and technically accurate across various development environments.