This issue serves as documentation for our decision to migrate from using colons (:) as the default topic separator in our CLI to using spaces ( ).
The migration aims to improve the overall user experience by making commands feel more natural and aligned with common CLI patterns.
Reasons for the Migration
Benefits of using spaces
- Improved readability and familiarity: Space-separated commands (e.g., apimatic portal quickstart) are more intuitive and resemble popular CLIs like git, npm etc. This reduces the learning curve for users familiar with these tools.
- Enhanced usability: Spaces make commands easier to type and read, especially for nested subcommands, promoting a more modern and user-friendly interface.
- Environment specific limitations: Using colons can be problematic in some environments, for instance, oclif's autocomplete plugin does not work with powershell when using colon as a topic separator.
Known Limitations and Trade-offs
- Argument ambiguity: With spaces, the parser may confuse positional arguments with subcommands. As a design decisions, we do not use positional arguments in topic-level commands, opting for flags instead.
We evaluated these trade-offs and determined that the UX benefits outweigh the limitations, especially since our CLI structure does not use positional arguments.
Backward compatibility
Migrating to spaces is not a breaking change because the cli still continues to accept commands using colon as a topic separator. This is the default behaviour for oclif.
This issue serves as documentation for our decision to migrate from using colons (:) as the default topic separator in our CLI to using spaces ( ).
The migration aims to improve the overall user experience by making commands feel more natural and aligned with common CLI patterns.
Reasons for the Migration
Benefits of using spaces
Known Limitations and Trade-offs
We evaluated these trade-offs and determined that the UX benefits outweigh the limitations, especially since our CLI structure does not use positional arguments.
Backward compatibility
Migrating to spaces is not a breaking change because the cli still continues to accept commands using colon as a topic separator. This is the default behaviour for oclif.