|
| 1 | +--- |
| 2 | +name: usethis-cli-modify |
| 3 | +description: Modify the usethis CLI layer (commands, options, help text) and keep documentation in sync |
| 4 | +compatibility: usethis, Python, typer, markdown |
| 5 | +license: MIT |
| 6 | +metadata: |
| 7 | + version: "1.0" |
| 8 | +--- |
| 9 | + |
| 10 | +# Modifying the CLI |
| 11 | + |
| 12 | +## Procedure |
| 13 | + |
| 14 | +1. Make your changes to the CLI layer (command functions, options, help text, or app registration). |
| 15 | +2. Update the CLI documentation to reflect every user-facing change. |
| 16 | +3. Run the affected interface-level tests. |
| 17 | + |
| 18 | +## When this skill applies |
| 19 | + |
| 20 | +Use this skill whenever you modify anything under the `_ui` package, including: |
| 21 | + |
| 22 | +- Adding, removing, or renaming a command |
| 23 | +- Changing a command's options, arguments, or defaults |
| 24 | +- Changing help text or command descriptions |
| 25 | +- Modifying how commands are registered on the app |
| 26 | + |
| 27 | +## Update the CLI documentation |
| 28 | + |
| 29 | +**Every user-facing CLI change requires a documentation update.** The documentation is manually written and is not auto-generated from the code, so it will not update itself. |
| 30 | + |
| 31 | +After making CLI changes, review and update each of the following as needed: |
| 32 | + |
| 33 | +### Command reference |
| 34 | + |
| 35 | +The command reference page documents every command with its full description, supported options, and behavior. Update it to match any changes you made to commands, options, defaults, or descriptions. |
| 36 | + |
| 37 | +### Command overview |
| 38 | + |
| 39 | +The command overview page lists all commands organized by category with brief descriptions. Update it if you added, removed, renamed, or recategorized a command. |
| 40 | + |
| 41 | +### Example usage and getting-started pages |
| 42 | + |
| 43 | +The getting-started pages show practical CLI usage examples. If your change affects the commands or output shown in these examples, update them so the examples remain accurate and runnable. |
| 44 | + |
| 45 | +### README |
| 46 | + |
| 47 | +If your change adds, removes, or renames a CLI command or tool integration, update the README to reflect this. |
| 48 | + |
| 49 | +### CONTRIBUTING.md |
| 50 | + |
| 51 | +If your change affects the step-by-step guides in CONTRIBUTING.md (e.g. the "Adding a new tool" or "Adding a new badge" guides), update those guides to remain accurate. |
| 52 | + |
| 53 | +## CLI architecture |
| 54 | + |
| 55 | +### Separation of interface and core logic |
| 56 | + |
| 57 | +Command functions in the `_ui` layer are thin wrappers. They parse CLI arguments, set up configuration and file management context, then delegate to functions in the `_core` package. Keep this separation: do not put business logic in command functions. |
| 58 | + |
| 59 | +### Command registration pattern |
| 60 | + |
| 61 | +Each command is defined in its own file under `_ui/interface/`. The main app object in `_ui/app.py` registers commands using `app.command()` or `app.add_typer()` for sub-apps. Shared CLI options are defined as module-level constants in `_ui/options.py`. |
| 62 | + |
| 63 | +When adding a new command: |
| 64 | + |
| 65 | +1. Create a new file in `_ui/interface/` following the pattern of existing commands. |
| 66 | +2. Register it in `_ui/app.py`. |
| 67 | +3. If the command uses shared options, import them from `_ui/options.py`. If it needs new options, add them there. |
| 68 | +4. Create the corresponding core logic function in `_core/`. |
0 commit comments