Documentation

[ts-mothership]

Question

Abstract

The shopware-cli command is more or less a blackbox. The current version of the documentation on https://sw-cli.fos.gg/ mostly lists only the different commands but does not explain the reasons why different arguments are needed, how it internally works and what to do on certain use cases and errors. There should be more information given, more examples and explanation.

I checked a few commands and it was not always clear why it didn't work as expected. Only after deep diving into the source code I understood more concepts of different commands, but not always. I know documentation is not easy but I'll try to list the questionable commands here and try to suggest something if possible or ask specific questions. Commands not listed below are fine for me 👍 .

shopware-cli project admin-build

• What are the differences to bin/build-administration.sh? What are the benefits and consequences of running project admin-build vs bin/build-administration.sh?
• What does "ERROR Extension ... should be installed using Composer. Please remove the extension from custom/plugins." mean exactly? Is it a notice/warning and the extension has been built, or was the extension skipped, or is it an error which blocks another following process?
• The command seems to build all plugins even if they're disabled. bin/build-administration.sh seems to skip disabled modules. This might cause issues with problematic plugins, e.g. the Evolve plugin SwagDynamicAccess fails building with this error (which doesn't happen in bin/build-administration.sh because it's disabled):

  npm ERR! code ETARGET
  npm ERR! notarget No matching version found for vue@3.3.10.
  npm ERR! notarget In most cases you or one of your dependencies are requesting
  npm ERR! notarget a package version that doesn't exist.

shopware-cli project storefront-build

• Same questions as above

shopware-cli project worker

• Please clarify what "Starts the Shopware worker in background" means. Seems they're running in shell foreground, not background.
• Are there any benefits to the usual bin/console messenger:consume command?
• A setup with supervisor/systemd is still needed I guess? If so, maybe link to the Shopware documentation for an example.

shopware-cli project dump

• Argument database is required while username, password is optional and has defaults, but it should be vice versa. Usually the database name could be extracted from DATABASE_URL env variable and username/password should be required because the credentials in DATABASE_URL might not have all permissions for the dump.
• Password is given in plain text and seems there is no way to provide password via environment variable or hidden input
• Option --clean does not contain SW 6.5 table "messenger_messages". Maybe include also other core tables like import_export_log. Also update all rows in table scheduled_task to status='scheduled' to make sure they're not hanging in status "queued" because you clean the queue table.
• Option --anonymize should change/remove password and legacy password fields as well
• Is it possible to exclude table user from anonymization?

shopware-cli project extension *

• Requires admin-api configuration in .shopware-project.yml which is not documented in https://sw-cli.fos.gg/commands/project/#shopware-cli-project-extension-list nor https://sw-cli.fos.gg/shopware-project-yml-schema/ . But command fails with useful hints 👍
• Still, it should be documented which commands are working when executed in Shopware home directory and which are working only via admin api access. Why was admin api chosen for plugin management when project worker works from home directory?
• Please also differentiate between project extension commands and extension commands in documentation and use cases for both

shopware-cli project generate-jwt

• What are the differences to bin/console system:generate-jwt-secret command?

shopware-cli extension validate

• What exactly does "store compliance" mean? Can you please list more details in documentation of what is checked. Which parts of composer.json, which files, directories, etc.
• Message Required field "previewMedia" in theme.json is not in ends abruptly, seems there should be something after "in"

shopware-cli extension build

• Documentation at https://sw-cli.fos.gg/commands/extension/#shopware-cli-extension-build seems incorrect. Instead of the plugin name like in documentation, the relative path is required. Using plugin name fails in an obscure message "cannot open extension: unknown extension type"
• Environment variable SHOPWARE_PROJECT_ROOT seems to be required and commands does not work if executed from Shopware home directory
• A nice-to-have feature: make plugin name optional. If not given it will build all plugins in custom/static-plugins

shopware-cli extension admin-watch

• What is the difference to shopware-cli project admin-watch?
• Why is there no storefront-watch like in project scope?

shopware-cli extension get-changelog

• Please update documentation what exactly is fetched
• With path as required argument this command seems pointless. Why should I call SHOPWARE_PROJECT_ROOT=$( pwd ) shopware-cli extension get-changelog vendor/store.shopware.com/swagsocialshopping when I just can cat vendor/store.shopware.com/swagsocialshopping/CHANGELOG.md ?
• The get-changelog command fetches only the latest version and parses it into HTML, which doesn't make sense in terminal. What are the reasons behind it?
• Instead of Option --german I suggest changing it to --locale de-DE to make it future prove for other languages

shopware-cli extension get-version

• same as above

[shyim]

feel free to make a PR to improve the docs :)

[andreasemer]

@ts-mothership I think there a too many issues in this ticket, can please split this ticket up? The incompatibility of shopware-cli project dump with the current versions of SW is for example a topic for it's own.

[ts-mothership]

@andreasemer First things first, the documentation should be updated first to make clear how it should work. Not everything is clear until now, maybe shyim first can clarify the intensions and use-cases for the commands listed above.

To the "project dump": it still works, there is no error if old tables are missing so I wouldn't consider it a bug but a missing feature. And this is more a documentation issue than anything else.

[shyim]

I will look how when I have time for this. I want to do a lot of more until the SCD. I will present shopware-cli on the Community Stage at the SCD

[Isengo1989]

If this becomes an official tool, I bet we can give support here docs-wise.

Only played around with it so far, but never used in "production" - I am curious :)

[azngeek]

@Isengo1989 @shyim As this becomes an official tool, what is the state of the documentation? I think it would make sense that @shyim starts with a draft of some examples, as this would help us to understand the expected usage. Based on that we then could create PRs for specific topics.