As the CLI has grown, naming patterns have diverged. This tracks the inconsistencies so we can agree on conventions going forward.
Two patterns for multi-action resource commands
Some resources use a single command with as a positional arg:
app variables <list|get|set|delete> [app]
app domains <list|add|remove|retry> [app]
app ip-list <get|set> [app]
app ua-blocklist <get|set> [app]
app tasks [list|cancel|logs]
Others use separate named commands per operation:
app deploy (create) vs app deploys (list)
app build (create) vs app builds (list)
app backup (create) vs app backups (list)
These are equivalent patterns for the same kind of CRUD operation.
Action vocabulary isn't standardised
add vs create, remove vs delete, set vs update are used interchangeably across commands with no rule for which to pick.
instance uses a non-standard flat positional chain
instance [group] [action] [id] [value]
All other commands use yargs subcommands. The instance routing is manual if/else, which breaks per-subcommand --help and causes the target argument to shift position:
instance info — id is in the action slot
instance access list — id is in the id slot
php-logs is redundant
stack php-logs duplicates app logs --type php. The dedicated command adds noise.
build-cache only accepts one value
build-cache requires a positional action but only accepts clear. It should just be build-cache clear.
local-setup is undocumented
lib/commands/stack/local-setup.js exists but is not listed in the README. Either document it or remove it.
Mark php-logs as deprecated
Proposed next steps:
- Agree on a standard CRUD pattern (suggest: plural noun + action subcommand
— deploys list, deploys create)
- Agree on action vocabulary (list, get, create, update, delete, with
add/remove only for membership)
- Refactor instance to use proper yargs subcommands
- Document agreed conventions in README or CONTRIBUTING
- Mark php-logs as deprecated
As the CLI has grown, naming patterns have diverged. This tracks the inconsistencies so we can agree on conventions going forward.
Two patterns for multi-action resource commands
Some resources use a single command with as a positional arg:
app variables <list|get|set|delete> [app]
app domains <list|add|remove|retry> [app]
app ip-list <get|set> [app]
app ua-blocklist <get|set> [app]
app tasks [list|cancel|logs]
Others use separate named commands per operation:
app deploy (create) vs app deploys (list)
app build (create) vs app builds (list)
app backup (create) vs app backups (list)
These are equivalent patterns for the same kind of CRUD operation.
Action vocabulary isn't standardised
add vs create, remove vs delete, set vs update are used interchangeably across commands with no rule for which to pick.
instance uses a non-standard flat positional chain
instance [group] [action] [id] [value]
All other commands use yargs subcommands. The instance routing is manual if/else, which breaks per-subcommand --help and causes the target argument to shift position:
instance info — id is in the action slot
instance access list — id is in the id slot
php-logs is redundant
stack php-logs duplicates app logs --type php. The dedicated command adds noise.
build-cache only accepts one value
build-cache requires a positional action but only accepts clear. It should just be build-cache clear.
local-setup is undocumented
lib/commands/stack/local-setup.js exists but is not listed in the README. Either document it or remove it.
Mark php-logs as deprecated
Proposed next steps:
— deploys list, deploys create)
add/remove only for membership)