document the mash scripts that help with pkgx (#1083)

Author: mxcl

.gitbook.yaml

@@ -14,10 +14,10 @@ redirects:
   docker: getting-started.md
   ci-cd: getting-started.md
   scripts: scripting.md
-  run/anywhere/terminals: getting-started.md
-  run/anywhere/docker: getting-started.md
-  run/anywhere/ci-cd: getting-started.md
-  run/anywhere/scripts: scripting.md
+  run-anywhere/terminals: getting-started.md
+  run-anywhere/docker: getting-started.md
+  run-anywhere/ci-cd: getting-started.md
+  run-anywhere/scripts: scripting.md
   pantry.md: pkging/pantry.md
   pantry-api: pkging/pantry-api.md
   pkgx-install: https://github.com/pkgxdev/pkgm

.github/markdownlint.yml

@@ -15,3 +15,7 @@ MD025: false
 MD033: false
 # Multiple consecutive blank lines
 MD012: false
+
+# Blank line inside blockquote
+# gives false positives on code blocks for literal consecutive blockquotes
+MD028: false

README.md

@@ -1,7 +1,8 @@
 ![pkgx.dev](https://pkgx.dev/banner.png)
 
 `pkgx` is a 4MB, *standalone* binary that can *run anything*.
-  [![coverage][]][coveralls] [![teaRank][]](https://tea.xyz)
+
+[![coverage][]][coveralls] [![teaRank][]](https://tea.xyz)
 
  
 
@@ -244,6 +245,7 @@ pprint([(k, v["title"]) for k, v in data.items()][:10])
 > ecosystem is available to your scripts Check it out [`mash`].
 
 > [!INFO]
+>
 > Notably, packages used during your script aren’t installed and don’t pollute
 > your system and anyone else’s systems either. Don’t be confused— they are
 > downloaded to `~/.pkgx` but the wider system is not touched.
@@ -312,8 +314,8 @@ exported.
 
 ## `pkgx install`
 
-We now provide [`pkgm`][pkgm] but if you miss the leanness of “stubs” we provide a
-[`mash`] script to create stubs in `/usr/local/bin`:
+We now provide [`pkgm`][pkgm] but if you miss the leanness of “stubs” we
+provide a [`mash`] script to create stubs in `/usr/local/bin`:
 
 ```sh
 $ pkgx mash pkgx/stub git

docs/pkgx.md

@@ -119,10 +119,73 @@ gum version 0.14.5
 For this mode we can also output JSON: `pkgx +gum --json`.
 
 
-## Silent Mode
+## Quietening Output
 
 ```sh
-pkgx --silent gum format 'no progress information is output'
+$ pkgx --quiet gum format 'download progress is still shown'
+# ^^ supresses resolving/syncing etc. messages but not download progress info
+
+```sh
+pkgx --silent gum format 'no output at all'
+# ^^ silences everything, even errors
+```
+
+Note that this only effects `pkgx` *not the tools you run with `pkgx`*.
+
+## Other Common Needs
+
+`pkgx` is not a package manager. Thus the command itself doesn’t typically
+offer such operations you may expect, however the way `pkgx` works is simple
+and standardized so we offer some `mash` scripts to help.
+
+Longer term we will make a tool `pkgq` to help with these operations.
+
+### Upgrading Packages
+
+`pkgx foo` executes the latest version of `foo` that is *downloaded*. To
+ensure you have (any) newer versions installed use this command:
+
+```sh
+$ pkgx mash pkgx/cache upgrade
+updating: /Users/mxcl/.pkgx/python.org/v3.11.11
+# snip…
+```
+
+### Pruning Older Versions of Packages
+
+The `pkgx` download cache can get large over time. To prune older versions:
+
+```sh
+$ pkgx mash pkgx/cache prune
+pruning: ~/.pkgx/deno.land/v1.39.4
+pruning: ~/.pkgx/deno.land/v1.46.3
+# snip…
+```
+
+This may delete versions that you use—if so—this is fine. `pkgx` will just
+reinstall them next time you need them.
+
+### Listing Available Versions for a Package
+
+ie. what versions *could be* run by `pkgx`:
+
+```sh
+$ pkgx mash pkgx/pantry-inventory git
+2.38.1
+2.39.0
+# snip…
+```
+
+### Listing What is Downloaded
+
+```sh
+$ mash pkgx/cache ls
+
+  Parent Directory                │Version
+  ────────────────────────────────┼──────────
+  perl.org                        │5.40.0
+  x.org/xcb                       │1.17.0
+  # snip…
 ```
 
 [SemVer]: https://devhints.io/semver