diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 3ab76e255..18ed7e2bb 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -195,6 +195,13 @@ jobs:
           PKGX_DIR: ${{ github.workspace }}/pkgx
           PKGX_DIST_URL: https://dist.pkgx.dev
 
+      - name: --chdir
+        run: |
+          d=$(realpath $(mktemp -d))
+          test $(pwd) != $d
+          test $(pkgx -C $d -- pwd) = $d
+          test $(pkgx --chdir $d -- pwd) = $d
+
       - name: generate coverage
         run: |
           pkgx +llvm.org -- llvm-profdata merge -sparse $(find . -name default_\*.prof\*) -o default.profdata
diff --git a/README.md b/README.md
index ca863ddfd..acfe76a1d 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@
 
 > [!NOTE]
 >
-> You want your tools to *just work* and we want that too. We pride ourselves
+> You want your tools to _just work_ and we want that too. We pride ourselves
 > on packaging things as well as possible because we want you to change the
 > world with what you build and not have to worry about the rest.
 
@@ -74,7 +74,7 @@ Python 2.7.18
 > - libm.so.6 (provided by glibc)
 > - libgcc_s.so.1 (provided by libgcc)
 > - libpthread.so.0 (provided by glibc)
-> - libc.so.6 (this *is* glibc)
+> - libc.so.6 (this _is_ glibc)
 > - ld-linux-x86-64.so.2 (provided by the kernel, you get this for free)
 >
 > `libgcc` is built as part of the GCC distribution and usually is split out
diff --git a/crates/cli/src/args.rs b/crates/cli/src/args.rs
index 09768f037..3b0ebae20 100644
--- a/crates/cli/src/args.rs
+++ b/crates/cli/src/args.rs
@@ -14,6 +14,7 @@ pub struct Flags {
     pub version_n_continue: bool,
     pub shebang: bool,
     pub sync: bool,
+    pub chdir: Option<String>,
 }
 
 pub struct Args {
@@ -36,9 +37,11 @@ pub fn parse() -> Args {
     let mut version_n_continue = false;
     let mut shebang = false;
     let mut sync = false;
+    let mut chdir = None;
     let json_latest_v: isize = 2;
 
-    for arg in std::env::args().skip(1) {
+    let mut args_iter = std::env::args().skip(1);
+    while let Some(arg) = args_iter.next() {
         if collecting_args {
             args.push(arg);
         } else if arg.starts_with('+') {
@@ -59,6 +62,7 @@ pub fn parse() -> Args {
                     }
                     json = Some(2);
                 }
+                "--chdir" | "--cd" => chdir = args_iter.next(),
                 "--json=v1" => json = Some(1),
                 "--json=v2" => json = Some(2),
                 "--silent" => silent = true,
@@ -105,6 +109,7 @@ pub fn parse() -> Args {
                     'v' => version_n_continue = true,
                     '!' => shebang = true,
                     'Q' => mode = Mode::Query,
+                    'C' => chdir = args_iter.next(),
                     _ => panic!("unknown argument: -{}", c),
                 }
             }
@@ -127,6 +132,7 @@ pub fn parse() -> Args {
             quiet,
             version_n_continue,
             sync,
+            chdir,
         },
     }
 }
diff --git a/crates/cli/src/help.rs b/crates/cli/src/help.rs
index 8710a0260..6183ea452 100644
--- a/crates/cli/src/help.rs
+++ b/crates/cli/src/help.rs
@@ -28,11 +28,12 @@ modes:
   $ pkgx --version
 
 flags:
-  -q,  --quiet    # suppress brief informational messages
-  -qq, --silent   # no chat. no errors. just execute.
-  -v              # print version and continue
-  --sync          # sync first (note: rarely if ever needed)
-  -j,--json=v2    # output JSON (if sensible)
+  -q,  --quiet      # suppress brief informational messages
+  -qq, --silent     # no chat. no errors. just execute.
+  -j,  --json=v2    # output JSON (if sensible)
+  -C,  --chdir <d>  # change directory first
+  --sync            # sync first (note: rarely if ever needed)
+  -v                # print version and continue
 
 more:
   $ OPEN https://docs.pkgx.sh
diff --git a/crates/cli/src/main.rs b/crates/cli/src/main.rs
index 06d4d36e9..2a1e8bf9c 100644
--- a/crates/cli/src/main.rs
+++ b/crates/cli/src/main.rs
@@ -24,8 +24,12 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         find_program,
     } = args::parse();
 
+    if let Some(dir) = &flags.chdir {
+        std::env::set_current_dir(dir)?;
+    }
+
     if flags.version_n_continue {
-        eprintln!("pkgx {}", env!("CARGO_PKG_VERSION"));
+        print_version(flags.json.is_some());
     }
 
     match mode {
@@ -34,7 +38,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
             Ok(())
         }
         args::Mode::Version => {
-            println!("pkgx {}", env!("CARGO_PKG_VERSION"));
+            print_version(flags.json.is_some());
             Ok(())
         }
         args::Mode::Query => {
@@ -96,3 +100,14 @@ async fn setup(
 
     Ok((conn, did_sync, config, spinner))
 }
+
+fn print_version(json: bool) {
+    if !json {
+        eprintln!("pkgx {}", env!("CARGO_PKG_VERSION"));
+    } else {
+        eprintln!(
+            "{{\"program\": \"pkgx\", \"version\": \"{}\"}}",
+            env!("CARGO_PKG_VERSION")
+        );
+    }
+}
diff --git a/docs/pkgx.md b/docs/pkgx.md
index 36cbbd4b8..e169cbcdf 100644
--- a/docs/pkgx.md
+++ b/docs/pkgx.md
@@ -190,6 +190,12 @@ standardized so we offer some `mash` scripts to help.
 
 Longer term we will make a tool `pkgq` to help with these operations.
 
+### Listing Outdated Packages
+
+```sh
+pkgx mash outdated
+```
+
 ### Upgrading Packages
 
 `pkgx foo` executes the latest version of `foo` that is _downloaded_. To ensure
@@ -201,6 +207,8 @@ updating: /Users/mxcl/.pkgx/python.org/v3.11.11
 # snip…
 ```
 
+You can specify args to upgrade only specific packages.
+
 ### Pruning Older Versions of Packages
 
 The `pkgx` download cache can get large over time. To prune older versions: