[feature] list commands for both attachment and emojis (#2121)

* [feature] list commands for both attachment and emojis

* use fewer commands, provide `local-only` and `remote-only` as filters

* envparsing

---------

Co-authored-by: Romain de Laage <romain.delaage@rdelaage.ovh>
Co-authored-by: tsmethurst <tobi.smethurst@protonmail.com>

1 files changed, 62 insertions, 6 deletions

diff --git a/docs/admin/cli.md b/docs/admin/cli.md
index 653c8aa3e..405093531 100644
--- a/docs/admin/cli.md
+++ b/docs/admin/cli.md
@@ -255,17 +255,73 @@ Example:
 gotosocial admin import --path example.json --config-path config.yaml
 ```
 
-### gotosocial admin media list-local
+### gotosocial admin media list-attachments
 
-This command can be used to list local media. Local media is media that belongs to posts by users with an account on the instance.
+Can be used to list the storage paths of local, remote, or all media attachments on your instance (including headers and avatars).
 
-The output will be a list of files. The list can be used to drive your backups.
+`local-only` and `remote-only` can be used as filters; they cannot both be set at once.
 
-### gotosocial admin media list-remote
+If neither `local-only` or `remote-only` are set, all media attachments on your instance will be listed.
 
-This is the corollary to list-local, but instead lists media from remote instances. Remote media belongs to other instances, but was attached to a post we received over federation and have potentially cached locally.
+You may want to run this with `GTS_LOG_LEVEL` set to `warn` or `error`, otherwise it will log a lot of info messages you probably don't need.
 
-The output will be a list of URLs to retrieve the original content from. GoToSocial automatically retrieves remote media when it needs it, so you should never need to do so yourself.
+`gotosocial admin media list-attachments --help`:
+
+```text
+list local, remote, or all attachments
+
+Usage:
+  gotosocial admin media list-attachments [flags]
+
+Flags:
+  -h, --help          help for list-attachments
+      --local-only    list only local attachments/emojis; if specified then remote-only cannot also be true
+      --remote-only   list only remote attachments/emojis; if specified then local-only cannot also be true
+```
+
+Example output:
+
+```text
+/gotosocial/062G5WYKY35KKD12EMSM3F8PJ8/attachment/original/01PFPMWK2FF0D9WMHEJHR07C3R.jpg
+/gotosocial/01F8MH1H7YV1Z7D2C8K2730QBF/attachment/original/01PFPMWK2FF0D9WMHEJHR07C3Q.jpg
+/gotosocial/01F8MH5ZK5VRH73AKHQM6Y9VNX/attachment/original/01FVW7RXPQ8YJHTEXYPE7Q8ZY0.jpg
+/gotosocial/01F8MH1H7YV1Z7D2C8K2730QBF/attachment/original/01F8MH8RMYQ6MSNY3JM2XT1CQ5.jpg
+/gotosocial/01F8MH1H7YV1Z7D2C8K2730QBF/attachment/original/01F8MH7TDVANYKWVE8VVKFPJTJ.gif
+/gotosocial/01F8MH17FWEB39HZJ76B6VXSKF/attachment/original/01F8MH6NEM8D7527KZAECTCR76.jpg
+/gotosocial/01F8MH1H7YV1Z7D2C8K2730QBF/attachment/original/01F8MH58A357CV5K7R7TJMSH6S.jpg
+/gotosocial/01F8MH1H7YV1Z7D2C8K2730QBF/attachment/original/01CDR64G398ADCHXK08WWTHEZ5.gif
+```
+
+### gotosocial admin media list-emojis
+
+Can be used to list the storage paths of local, remote, or all emojis on your instance.
+
+`local-only` and `remote-only` can be used as filters; they cannot both be set at once.
+
+If neither `local-only` or `remote-only` are set, all emojis on your instance will be listed.
+
+You may want to run this with `GTS_LOG_LEVEL` set to `warn` or `error`, otherwise it will log a lot of info messages you probably don't need.
+
+`gotosocial admin media list-emojis --help`:
+
+```text
+list local, remote, or all emojis
+
+Usage:
+  gotosocial admin media list-emojis [flags]
+
+Flags:
+  -h, --help          help for list-emojis
+      --local-only    list only local attachments/emojis; if specified then remote-only cannot also be true
+      --remote-only   list only remote attachments/emojis; if specified then local-only cannot also be true
+```
+
+Example output:
+
+```text
+/gotosocial/01AY6P665V14JJR0AFVRT7311Y/emoji/original/01GD5KP5CQEE1R3X43Y1EHS2CW.png
+/gotosocial/01AY6P665V14JJR0AFVRT7311Y/emoji/original/01F8MH9H8E4VG3KDYJR9EGPXCQ.png
+```
 
 ### gotosocial admin media prune orphaned