[Feat]: CLI discoverability, PATH docs, python -m skillware, and unified help

[rosspeili]

Feature Description

Make the skillware CLI easy to run and easy to discover after pip install "skillware[cli]", on Windows and Unix, with or without Python on PATH.

A. Documentation, installation and PATH

Update docs/usage/cli.md (and README Quick Start if needed):

• After pip install "skillware[cli]", the skillware command lives in Python's Scripts directory (e.g. %LOCALAPPDATA%\Programs\Python\Python313\Scripts\ on Windows).
• If skillware is not recognized, add both Python3x\ and Python3x\Scripts\ to PATH, or use fallbacks (see B).
• Document Windows: py -3.13 -m pip install "skillware[cli]", verify with where skillware.
• Document Unix: python3 -m pip install "skillware[cli]", verify with which skillware.
• Clarify: core-only pip install skillware does not install rich; CLI requires [cli] extra.

B. Run without PATH (industry standard)

Add skillware/__main__.py so this works everywhere Python can import the package:

python -m skillware
python -m skillware list
python -m skillware list --category compliance
python -m skillware --help

Delegate to skillware.cli:main. Matches common Python packaging (pytest, pip, black, etc.). Console script entry point in pyproject.toml stays as primary when Scripts is on PATH.

Optional: one-line hint on ImportError / first run if someone tries -m skillware before this lands (not required once __main__.py exists).

C. Unified help (fix menu item 4 + expand --help)

Bug: Interactive menu 4 / help calls parser.print_help() (stderr, minimal). Users expect the same content as docs.

Fix:

• Add cmd_help(console) that prints rich, user-facing help to the same console as the menu (stdout via Rich).
• Wire menu help and top-level skillware --help / -h to cmd_help (or shared helper), not raw argparse stderr only.
• Include in help output:
  • All current commands: list (available), paths / test (stubs → [Feat]: CLI commands to set and repair skill directory paths (sub-issue of #16) #81 / [Feat]: CLI command to run skill tests (sub-issue of #16) #83)
  • Interactive mode: bare skillware, menu keys, q / Ctrl+C
  • list flags with examples: --category, --issuer, --skills-root
  • Copy-paste examples (compliance filter, issuer filter, custom root)
  • Link to full reference: docs/usage/cli.md
  • Install reminder: pip install "skillware[cli]"

Keep skillware list --help for flag-level detail (argparse subparser help is fine there).

D. CLI robustness (small, same PR if trivial)

• Add --version / -V at top level (print installed skillware version; useful for support).
• Ensure cmd_interactive always receives help helper (no branch that prints "Run skillware --help" only).
• Tests in tests/test_cli.py:
  • python -m skillware equivalent (import skillware.__main__ or run main with argv)
  • Interactive help / 4 prints expected sections (category example, issuer example)
  • --version output
• Update docs/usage/cli.md menu table: help item behavior matches implementation.

Out of scope (existing or separate issues)

• Implement paths ([Feat]: CLI commands to set and repair skill directory paths (sub-issue of #16) #81), test ([Feat]: CLI command to run skill tests (sub-issue of #16) #83), doctor, examples ([Feat]: cli skillware examples command and list --examples coverage flag #126) — stubs stay; only document in help.
• Version support policy / upgrade advisory ([Feat]: Version support policy — SECURITY.md and CLI upgrade advisory for installs below 0.3.1 #132).
• PyPI post-install hooks (not standard; prefer docs + __main__.py).

Rationale

Contributors and users hit friction right after install: skillware not found (Scripts not on PATH), python -m skillware failing, and help that only lists {list} while filters and examples live in docs only. Fixing discoverability and help in one pass reduces support burden and matches expectations set by tools like pip, pytest, and ollama-style CLIs (command on PATH + module fallback).

Implementation Idea

Files: skillware/__main__.py (new), skillware/cli.py, docs/usage/cli.md, README.md (Quick Start PATH note), tests/test_cli.py

1. skillware/__main__.py

   from skillware.cli import main
   if __name__ == "__main__":
       main()

2. cmd_help(console) in cli.py

   • Rich-formatted sections: Usage, Commands, Examples, Install, Docs link
   • Reuse strings or a small constant block; avoid duplicating all of cli.md

3. main()

   • parser.add_argument("--version", "-V", action="version", version=...)
   • On -h / --help with no subcommand: call cmd_help(Console()) then return (do not enter interactive menu)
   • cmd_interactive(parser=parser) → pass help_fn=cmd_help instead of relying on parser.print_help()

4. Docs

   • New subsection Running the CLI under Installation in cli.md: PATH, fallbacks, Windows py launcher

5. Tests

   • test_main_module_invocation (subprocess or importlib)
   • test_cmd_help_includes_list_examples
   • test_interactive_help_dispatches_to_cmd_help

Acceptance Criteria

• docs/usage/cli.md documents PATH (Python + Scripts), [cli] extra, and fallbacks (python -m skillware, full path to skillware.exe)
• python -m skillware and python -m skillware list work when package is installed
• skillware --help and interactive menu 4 / help show the same rich help (commands, flags, examples for category/issuer/root)
• skillware list --category / --issuer / --skills-root still work; examples appear in top-level help
• --version prints installed version
• tests/test_cli.py covers __main__, help content, and interactive help
• pytest tests/test_cli.py and flake8 pass

Affected Pages

skillware/__main__.py (new), skillware/cli.py, docs/usage/cli.md, README.md, tests/test_cli.py

Related

#81 (paths), #83 (test), #130 / #131 (polish done), #132 (version advisory, separate)

[rosspeili]

Hey @rizzoMartin, check this follow up for CLI, if you're interested, and I have quick design question for your take as the CLI owner.

Context: After #129 / #130 / #131, several of us hit the same friction on a fresh install: pip install skillware works, but skillware fails until you also run pip install "skillware[cli]" because rich lives in the optional [cli] extra (from #87’s lean-core split).

What we’re considering: Move rich>=13.0 into core [project] dependencies in pyproject.toml, so pip install skillware ships the CLI out of the box, same idea as “install once, run skillware” without remembering an extra.

Why we’re leaning yes:

• CLI is a first-class surface now (splash, menu, list, filters).
• #87 was mainly about LLM SDKs (anthropic, google-genai, etc.), not terminal UI. rich is much lighter (~11 MB installed with pygments + markdown-it-py on a local check).
• Less support burden (“why doesn’t skillware work?”) and simpler docs (pip install skillware only).

Trade-off: Library-only users who only import skillware / SkillLoader and never run the terminal would still pull in rich. We could keep [cli] as a deprecated alias for backward compat, or drop it later.

PATH / python -m skillware / help UX — that’s part of the current issue.

Does bundling rich in core make sense to you, or would you prefer keeping [cli] optional and fixing discoverability via docs + install messaging instead? Happy with either if you have a strong reason, wanted your opinion before we open a small issue.

No rush, just your take when you have a minute. Thanks again for all the CLI work. <3

[rizzoMartin]

Hey! Happy to take this one on.

I'd go with moving rich to core. It's lightweight and the CLI in my opinion is now a first-class functionality not just a side feature. Making users remember a second install step for something that weighs ~11MB doesn't make sense for me, especially when rich is what makes the package feel polished and informative right out of the box.

Fixing discoverability via docs and messaging is a valid option but moving rich to core is cleaner, simpler, and more intuitive — one install, everything works.

I'd keep [cli] as an empty deprecated alias for backward compat and clean it up later.

I'll handle the pyproject.toml change as part of the current issue. Let me know if you want it as a separate small PR or bundled in.

[rosspeili]

Hey @rizzoMartin, you can bundle this under #135 as-is yeah, I'll review and merge when it's ready. Thanks.

I also agree the CLI is too small to warrant a separate install path. The core pip install skillware is only a few MB, so adding ~10MB for rich looks like a huge percentage on paper, but in practice I doubt anyone will notice a ~12 MB download in 2026.

If the CLI later picks up more dependencies beyond rich, we can reevaluate, but for now I'm fully on board with shipping it in the default package so users get a working CLI out of the gate. I tested yesterday (with py on PATH) and skillware ran smoothly from any directory in cmd.

There are some minor issues called out in #135, so the full change should include moving rich into pyproject.toml and updating the relevant docs accordingly.

[rosspeili]

Hi @rizzoMartin, quick heads-up before you push #135: main now includes #132 (version support policy), so worth syncing your branch first.

What landed (#132):

• New skillware/version_policy.py, thresholds in one place (MIN_SECURITY_SUPPORTED, MIN_UNSUPPORTED)
• emit_upgrade_advisory() runs once at the top of cli.main() (before argparse / interactive menu), not on menu re-loops and not on import skillware
• Silent for almost everyone: CLI advisory only for installs below 0.2.6 (e.g. 0.2.5). 0.2.6+ stays quiet
• Opt-out: SKILLWARE_NO_VERSION_CHECK=1 (already documented in docs/usage/cli.md → Version advisory)
• SECURITY.md updated with the supported-version table

For your #135 PR: please keep the #132 hook at the start of main() when you add __main__.py, --help / cmd_help, and --version. --version can reuse the same installed-version lookup (importlib.metadata or helpers in version_policy.py). Help text can mention the unsupported-version line briefly, but no need to duplicate the full policy, link SECURITY.md / cli.md instead.

Docs note: issue body still says CLI needs [cli] for rich; per our thread you're moving rich to core, update install/PATH docs accordingly (pip install skillware + python -m skillware fallbacks).

No change to your scope (#81 / #83 stay stubs). Shout if anything conflicts when you rebase. Thanks again for taking this on.