### Quick Start

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/README.md

Install pkgx using Homebrew or a curl script.

```sh
brew install pkgx || curl https://pkgx.sh | sh
```

```pwsh
irm https://pkgx.sh | iex  # Windows
```

--------------------------------

### Install and verify a package

Source: https://github.com/pkgxdev/pkgx/wiki/Basics

Example of installing a package and then verifying its location.

```sh
> pkgx +gnu.org/wget echo -n
 ✓  ~/.pkgx/curl.se/ca-certs/v2023.12.12
 ✓  ~/.pkgx/openssl.org/v1.1.1w
 ✓  ~/.pkgx/gnu.org/coreutils/v9.4.0
 ✓  ~/.pkgx/gnu.org/wget/v1.21.4
> which wget
wget not found
> pkgx +gnu.org/wget which wget
/Users/max/.pkgx/gnu.org/wget/v1.21.4/bin/wget
```

--------------------------------

### GitHub Actions Setup

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/installing-pkgx.md

Use the pkgxdev/setup action in GitHub Actions.

```yaml
- uses: pkgxdev/setup@v4
```

--------------------------------

### Recommend using a package with pkgx

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/faq.md

Examples of how to recommend users install and run a package using pkgx.

```shell
pkgx your-package --args
```

```shell
sh <(curl https://pkgx.sh) your-package --args
```

```shell
docker run pkgxdev/pkgx your-package --args
```

--------------------------------

### Composing package environments

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/deeper-dives/conceptual-overview.md

Illustrates how to compose package environments, showing `pkgx npm start` as an example that could be achieved with `env "$(pkgx +npmjs.org)" npm start`.

```sh
env "$(pkgx +npmjs.org)" npm start
```

--------------------------------

### Recursive Run Examples

Source: https://github.com/pkgxdev/pkgx/blob/main/README.md

Examples of running tools from other language ecosystems using pkgx.

```bash
pkgx uvx cowsay "Run Python (PyPi) programs with `uvx`"  # or pipx
pkgx bunx cowsay "Run JavaScript (NPM) programs tools with `bunx`"  # or `npx`

```

--------------------------------

### pkgm Shim Example

Source: https://github.com/pkgxdev/pkgx/blob/main/README.md

Example of using `pkgm shim` to create a shim for the git command.

```bash
$ pkgm shim git
created shim: ~/.local/bin/git

$ cat ~/.local/bin/git
#!/usr/bin/env -S pkgx -q! git

```

--------------------------------

### Implicit package environment creation

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/deeper-dives/conceptual-overview.md

Demonstrates how a simple `pkgx node start` command implicitly translates to `pkgx +node -- node start` and further to `pkgx +nodejs.org -- node start`.

```sh
pkgx node start
```

```sh
pkgx +node -- node start
```

```sh
pkgx +nodejs.org -- node start
```

--------------------------------

### Install and run a package

Source: https://github.com/pkgxdev/pkgx/wiki/Basics

Basic form of pkgx to install a package if needed and run the command.

```sh
> pkgx wget
 ✓  ~/.pkgx/gnu.org/wget/v1.21.4
wget: missing URL
Usage: wget [OPTION]... [URL]...

Try `wget --help' for more options.
```

--------------------------------

### Download and Install Manually (TGZ)

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/installing-pkgx.md

Download and extract the pkgx binary to /usr/local/bin using a one-liner.

```shell
curl -Ssf https://pkgx.sh/$(uname)/$(uname -m).tgz | sudo tar xz -C /usr/local/bin
```

--------------------------------

### Recommended Installation

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/installing-pkgx.md

A combined command to install pkgx using Homebrew or cURL.

```shell
brew install pkgx || curl https://pkgx.sh | sh
```

--------------------------------

### Ultra portable script with cURL and pkgx

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/scripting.md

Example of using a `cURL` one-liner with `pkgx` to temporarily install and use packages like Git.

```sh
#!/bin/bash

eval "$(sh <(curl https://pkgx.sh) +git)"

which git  # prints soemthing like /tmp/pkgx/git-scm.org/v2.46.3/bin/git
```

--------------------------------

### Install pkgx

Source: https://github.com/pkgxdev/pkgx/wiki/Basics

Command to install pkgx using curl.

```sh
curl -Ssf https://pkgx.sh | sh
```

--------------------------------

### Install Manually (Binary)

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/installing-pkgx.md

Install the downloaded pkgx binary to /usr/local/bin.

```shell
# install it to "/usr/local/bin/pkgx"
sudo install -m 755 pkgx /usr/local/bin
```

--------------------------------

### Windows Installation

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/installing-pkgx.md

Install pkgx on Windows using PowerShell.

```powershell
irm https://pkgx.sh | iex
# ^^ limited packages so far, list available programs with `pkgx -Q`
```

--------------------------------

### Running a program (deno) with pkgx

Source: https://github.com/pkgxdev/pkgx/blob/main/README.md

Demonstrates how pkgx can run a program like 'deno' without it being installed on the system, and how the system remains untouched after the program exits.

```sh
$ deno
command not found: deno

$ pkgx deno
Deno 2.1.4
> ^D

$ deno
command not found: deno
# ^^ nothing was installed; your wider system is untouched
```

--------------------------------

### Install pkgx using Homebrew or curl

Source: https://github.com/pkgxdev/pkgx/blob/main/README.md

Provides instructions for installing pkgx on macOS and Linux systems using Homebrew or a curl script.

```sh
brew install pkgx || curl https://pkgx.sh | sh
```

```powershell
# Windows 10+
irm https://pkgx.sh | iex
# ^^ we only have limited packages so far
```

--------------------------------

### Release Script Example

Source: https://github.com/pkgxdev/pkgx/blob/main/README.md

A script to release new versions to GitHub using pkgx to load necessary tools like gum, gh, npx, and git.

```bash
#!/usr/bin/env -S pkgx +gum +gh +npx +git bash>=4 -eo pipefail

gum format "# determining new version"

versions="$(git tag | grep '^v[0-9]\+\.[0-9]\+\.[0-9]\+')"
v_latest="$(npx -- semver --include-prerelease $versions | tail -n1)"
v_new=$(npx -- semver bump $v_latest --increment $1)

gum format "# releasing v$v_new"

gh release create \
  $v_new \
  --title "$v_new Released 🎉" \
  --generate-notes \
  --notes-start-tag=v$v_latest

```

--------------------------------

### Dockerfile Installation

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/installing-pkgx.md

Use pkgx as a base image in a Dockerfile.

```dockerfile
FROM pkgxdev/pkgx
RUN pkgx +node@16 npm start
```

--------------------------------

### JavaScript/TypeScript script with Deno

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/scripting.md

Example of using `pkgx` with Deno for JavaScript and TypeScript.

```javascript
#!/usr/bin/env -S pkgx deno@2 run

import fs from "npm:fs";
```

--------------------------------

### Python Hello World via pipe

Source: https://github.com/pkgxdev/pkgx/wiki/Basics

Executes a Python 'Hello, World' example by piping the string to pkgx python.

```shell
> echo 'print("Hello, World")' | pkgx python
Hello, World
```

--------------------------------

### Homebrew Installation

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/installing-pkgx.md

Install pkgx using the Homebrew package manager.

```shell
brew install pkgx
```

--------------------------------

### cURL Installer

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/installing-pkgx.md

Install or upgrade pkgx using the cURL installer script.

```shell
curl -fsS https://pkgx.sh | sh
```

--------------------------------

### C script with Scriptisto, Clang, and pkg-config

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/scripting.md

Example of using `pkgx` with Clang, `pkg-config`, and Scriptisto for C code.

```c
#!/usr/bin/env pkgx +clang +pkg-config scriptisto

#include <stdio.h>
#include <glib.h>

// scriptisto-begin
// script_src: main.c
// build_cmd: clang -O2 main.c `pkg-config --libs --cflags glib-2.0` -o ./script
// scriptisto-end

int main(int argc, char *argv[]) {
  gchar* user = g_getenv("USER");
  printf("Hello, C! Current user: %s\n", user);
  return 0;
}
```

--------------------------------

### Wrapper shell script example

Source: https://github.com/pkgxdev/pkgx/wiki/Basics

Example of a wrapper shell script to execute a pkgx command.

```shell
#!/bin/sh
exec pkgx +foo/bar foo "$@"
```

--------------------------------

### Install specific package version

Source: https://github.com/pkgxdev/pkgx/wiki/Basics

Specifies an exact version of a package to be used.

```shell
pkgx +python.org=3.10.8 python
```

--------------------------------

### Cargo Installation

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/installing-pkgx.md

Install pkgx using the Cargo package manager.

```shell
cargo install pkgx
```

--------------------------------

### Searching for packages

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/pkgx.md

Examples of using pkgx query mode to search for available programs.

```sh
$ pkgx -Q git
# ^^ can we run git?

$ pkgx -Q | grep git-
# ^^ search for all git extensions

$ $ pkgx -Q
# ^^ list every program pkgx can run
```

--------------------------------

### SemVer version specifiers

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/pkgx.md

Examples of using SemVer for more specific version control.

```sh
$ pkgx postgres^12 --version
postgres (PostgreSQL) 12.14

$ pkgx "postgres>=12<14" --version
postgres (PostgreSQL) 13.11

$ pkgx deno=1.35.3 --version
den
```

--------------------------------

### Python Script with PyPI Dependencies

Source: https://github.com/pkgxdev/pkgx/blob/main/README.md

Example of a Python script that uses pkgx to load Python 3.11 and uv, and specifies PyPI dependencies.

```bash
#!/usr/bin/env -S pkgx +python@3.11 uv run

# /// script
# dependencies = [
#   "requests<3",
#   "rich",
# ]
# ///

import requests
from rich.pretty import pprint

resp = requests.get("https://peps.python.org/api/peps.json")
data = resp.json()
pprint([(k, v["title"]) for k, v in data.items()][:10])

```

--------------------------------

### Python Hello World with explicit version

Source: https://github.com/pkgxdev/pkgx/wiki/Basics

Runs the Python 'Hello, World' example using a specific Python version managed by pkgx.

```shell
> pkgx +python.org python -c 'print("Hello, World")'
Hello, World
```

--------------------------------

### Execute wget by direct path

Source: https://github.com/pkgxdev/pkgx/wiki/Basics

Shows how to execute wget by specifying its direct path within the pkgx installation.

```shell
~/.pkgx/gnu.org/wget/v*/bin/wget http://example.com
```

--------------------------------

### Download Manually (Binary)

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/installing-pkgx.md

Download the pkgx binary directly to the current directory.

```shell
# download it to "./pkgx"
curl -o ./pkgx \
   --compressed --fail --proto '=https' \
   https://pkgx.sh/$(uname)/$(uname -m)
```

--------------------------------

### Shell alias example

Source: https://github.com/pkgxdev/pkgx/wiki/Basics

Example of creating a shell alias in ~/.zshrc to use pkgx for a command.

```shell
alias foo='pkgx +foo/bar foo'
```

--------------------------------

### Docker Run

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/installing-pkgx.md

Run pkgx in a Docker container.

```shell
docker run -it pkgxdev/pkgx

# or, eg.
docker run pkgxdev/pkgx +python@3.10 node@22 start
```

--------------------------------

### Rust script with rust-script

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/scripting.md

Example of using `pkgx` with `rust-script` for Rust code.

```rust
#!/usr/bin/env -S pkgx rust-script

//! ```cargo
//! [dependencies]
//! time = "0.1.25"
//! ```
```

--------------------------------

### Running pkgx within Docker

Source: https://github.com/pkgxdev/pkgx/blob/main/README.md

Provides examples of using pkgx within Docker containers, including running specific programs and using pkgx in a Dockerfile.

```sh
$ pkgx docker run -it pkgxdev/pkgx

(docker) $ pkgx node@16
Welcome to Node.js v16.20.1.
Type ".help" for more information.
>
```

```sh
$ docker run pkgxdev/pkgx node@21.1 --version
v21.1.0
```

```dockerfile
FROM pkgxdev/pkgx
RUN pkgx deno@1.35 task start
```

```dockerfile
FROM ubuntu
RUN curl https://pkgx.sh | sh
RUN pkgx python@3.10 -m http.server 8000
```

--------------------------------

### Running system commands with injected environment

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/pkgx.md

Examples of running system commands with a pkgx environment, using full path or '--' separator.

```sh
pkgx +llvm.org /usr/bin/make

pkgx +llvm.org -- make  # finds `make` in PATH, failing if none found
```

--------------------------------

### Install a package without running it

Source: https://github.com/pkgxdev/pkgx/wiki/Basics

Command to install a package without running it by specifying the package namespace and using 'echo -n'.

```sh
pkgx +pkg echo -n
```

--------------------------------

### Python script with uv and PyPi dependencies

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/scripting.md

Example of using `pkgx` with Python, `uv`, and PyPi dependencies like `requests` and `rich`.

```python
#!/usr/bin/env -S pkgx +python@3.11 uv run --with requests<=3 --with rich

import requests
from rich.pretty import pprint

resp = requests.get("https://peps.python.org/api/peps.json")
data = resp.json()
pprint([(k, v["title"]) for k, v in data.items()][:10])
```

--------------------------------

### Disambiguation with fully-qualified-names

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/pkgx.md

Example of how pkgx handles ambiguous package names and how to resolve them.

```sh
$ pkgx yarn --version
error: multiple projects provide `yarn`. please be more specific:

    pkgx +classic.yarnpkg.com yarn --version
    pkgx +yarnpkg.com yarn --version
```

--------------------------------

### Ruby script with Bundler

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/scripting.md

Example of using `pkgx` with Ruby and Bundler to manage gem dependencies.

```ruby
#!/usr/bin/env -S pkgx ruby@3

require 'bundler/inline'

gemfile do
  source 'https://rubygems.org'
  gem 'ruby-macho', '~> 3'
end
```

--------------------------------

### Install package into Python silo

Source: https://github.com/pkgxdev/pkgx/wiki/Basics

Installs a package into the site-packages directory of a specific Python version managed by pkgx.

```shell
pkgx +python.org pip install some_package
```

--------------------------------

### Install package globally with npm

Source: https://github.com/pkgxdev/pkgx/wiki/Basics

Installs a package globally using npm, which is generally not recommended within pkgx silos.

```shell
pkgx -X npm install -g some_package
```

--------------------------------

### Install minimum version

Source: https://github.com/pkgxdev/pkgx/wiki/Basics

Specifies a minimum version for a package, ensuring the latest compatible version is used.

```shell
pkgx +python.org^3.10.0 python
```

--------------------------------

### Disambiguation example for same-named programs

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/faq.md

When two packages provide the same program, Pkgx errors and provides a method for disambiguation.

```sh
$ yarn
× multiple projects provide: yarn
│ pls be more specific:
│
│     pkgx +classic.yarnpkg.com --internal.use +yarn
│     pkgx +yarnpkg.com --internal.use +yarn
│
╰─➤ https://docs.pkgx.sh/help/ambiguous-pkgspec
```

--------------------------------

### Script including additional packages

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/scripting.md

Example of using `pkgx` to include additional packages like OpenSSL in a Deno script.

```sh
#!/usr/bin/env -S pkgx +openssl deno run

Deno.dlopen("libssl.dylib")
```

--------------------------------

### Robust environment specification

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/scripting.md

Example demonstrating robust environment specification using `pkgx` with Bash, requiring a specific version.

```sh
#!/usr/bin/env -S pkgx bash>=4

source <(pkgx dev --shellcode)
# ^^ bash >=4 is required for this syntax, and eg macOS only comes with bash 3
```

--------------------------------

### Quietening output

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/pkgx.md

Examples of using --quiet (-q) and --silent (-qq) flags to control pkgx output.

```sh
$ pkgx --quiet gum format 'download progress is still shown'
# ^^ supresses resolving/syncing etc. messages but not download progress info
# `pkgx -q` is the same

pkgx --silent gum format 'no output at all'
# ^^ silences everything, even errors
# ^^ `pkgx -qq` is the same
```

--------------------------------

### Python script with pkgx shebang

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/scripting.md

Example of using `pkgx` with Python to specify a version and import modules.

```python
#!/usr/bin/env -S pkgx python@3.9

import sys

print(sys.version)
```

```sh
$ chmod +x ./my-script.py
$ ./my-script.py
3.9.17
```

--------------------------------

### Example pkgx.yaml for C/C++ dependencies

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/deeper-dives/c++.md

This YAML configuration specifies common C/C++ libraries and tools that can be managed by pkgx.

```yaml
# pkgx.yaml

dependencies:
  openssl.org: ^3
  github.com/gabime/spdlog: ^1
  llvm.org: ^14
  gnu.org/autoconf: ^2
  cmake.org: ^3
```

--------------------------------

### Use a specific version range for a package

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/faq.md

Example of using semantic versioning with the caret syntax to specify a version range for a package.

```shell
$ pkgx node^20.1.3 --version
v20.1.5
```

--------------------------------

### Install latest minor version

Source: https://github.com/pkgxdev/pkgx/wiki/Basics

Specifies a major version, ensuring the latest minor version within that major release is used.

```shell
pkgx +python.org^3.10 python
```

--------------------------------

### Using 'dev' to create virtual environments

Source: https://github.com/pkgxdev/pkgx/blob/main/README.md

Explains and demonstrates how the 'dev' tool, leveraging pkgx, creates project-specific virtual environments by providing the necessary tools and dependencies.

```sh
$ cd my-rust-proj && ls
Cargo.toml  src/

my-rust-proj $ cargo build
command not found: cargo

my-rust-proj $ dev
+rust +cargo

my-rust-proj $ cargo build
Compiling my-rust-proj v0.1.0
#…

```

--------------------------------

### Avoid self-updating packages

Source: https://github.com/pkgxdev/pkgx/wiki/Basics

Example of an action to avoid: using a package's internal update mechanism, which defeats pkgx's version management.

```shell
pkgx +python.org=3.10.8 pip install --upgrade pip <-- DON'T DO THIS
```

--------------------------------

### Querying available packages with pkgx

Source: https://github.com/pkgxdev/pkgx/blob/main/README.md

Demonstrates how to use pkgx's query mode to check if a package is available, list all available packages, or find specific package extensions.

```sh
$ pkgx -Q git
# ^^ can you run git? (outputs the fully qualified project name)

$ pkgx -Q
# ^^ list everything that could be run

$ pkgx -Q | grep git-
# ^^ what git extensions does pkgx provide?
```

--------------------------------

### Using pkgx in scripts

Source: https://github.com/pkgxdev/pkgx/blob/main/README.md

Shows how to use pkgx to specify interpreter versions and available tools within a script's shebang line.

```sh
#!/usr/bin/env -S pkgx +git python@3.12

# python 3.12 runs the script and `git` is available during its execution
```

--------------------------------

### Execute wget

Source: https://github.com/pkgxdev/pkgx/wiki/Basics

Demonstrates how to execute the wget command using pkgx.

```shell
pkgx wget http://example.com
```

--------------------------------

### Using pkgx in CI/CD pipelines

Source: https://github.com/pkgxdev/pkgx/blob/main/README.md

Demonstrates how to integrate pkgx into CI/CD workflows using GitHub Actions or standalone scripts.

```yaml
- uses: pkgxdev/setup@v4
- run: pkgx shellcheck
```

```sh
curl https://pkgx.sh | sh
pkgx shellcheck
```

--------------------------------

### Running specific versions of programs

Source: https://github.com/pkgxdev/pkgx/blob/main/README.md

Shows how to use pkgx to run specific versions of programs like Node.js and Python.

```sh
$ pkgx node@14 --version
Node.js v14.21.3

$ pkgx python@2 --version
Python 2.7.18
```

--------------------------------

### Adding packages to the environment

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/pkgx.md

How to run a program with additional packages in its environment.

```sh
pkgx +openssl cargo build
```

--------------------------------

### Editor integration with `dev`

Source: https://github.com/pkgxdev/pkgx/blob/main/crates/cli/README.md

Shows how to use the `dev` tool (which utilizes `pkgx`) to automatically set up project dependencies for editors like VS Code.

```sh
$ cd myproj

myproj $ dev
+rust +cargo

myproj $ cargo build
Compiling my-rust-proj v0.1.0
#…

```

--------------------------------

### Migrating Shell Configuration

Source: https://github.com/pkgxdev/pkgx/blob/main/README.md

Commands to migrate shell configuration from pkgx^1 to dev.

```bash
pkgx pkgx^1 deintegrate
pkgx dev integrate

```

--------------------------------

### Execute Python script

Source: https://github.com/pkgxdev/pkgx/wiki/Basics

Demonstrates how to make a Python script executable and run it.

```shell
> chmod 755 hello-world.py
> ./hello-world.py
Hello, World
```

--------------------------------

### Docker image usage

Source: https://github.com/pkgxdev/pkgx/blob/main/crates/cli/README.md

Illustrates how to use the `pkgxdev/pkgx` Docker image to run programs like `node` and `deno`, and how to integrate it into a `Dockerfile`.

```sh
$ pkgx docker run -it pkgxdev/pkgx

(docker) $ pkgx node@16
Welcome to Node.js v16.20.1.
Type ".help" for more information.
>

```

```sh
$ docker run pkgxdev/pkgx node@21.1 --version
v21.1.0
```

```dockerfile
FROM pkgxdev/pkgx
RUN pkgx deno@1.35 task start
```

```dockerfile
FROM ubuntu
RUN curl https://pkgx.sh | sh
RUN pkgx python@3.10 -m http.server 8000
```

--------------------------------

### Pre-PR Linting Commands

Source: https://github.com/pkgxdev/pkgx/blob/main/README.md

Commands to run linting and formatting checks before submitting a Pull Request.

```bash
cargo fmt --all --check
cargo clippy --all-features
pkgx npx markdownlint --config .github/markdownlint.yml --fix .

```

--------------------------------

### Using pkgx with editors (dev tool)

Source: https://github.com/pkgxdev/pkgx/blob/main/README.md

Illustrates how the 'dev' tool, which uses pkgx primitives, can automatically manage project dependencies and be used to open the project in an editor.

```sh
$ cd myproj

myproj $ dev
+cargo +rust

myproj $ code .

```

--------------------------------

### Running a program

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/pkgx.md

Basic usage of pkgx to run a program and check its version.

```sh
$ pkgx openai --version
openai 1.59.6
```

--------------------------------

### Python script creation

Source: https://github.com/pkgxdev/pkgx/wiki/Basics

Provides the content for a Python script named 'hello-world.py'.

```python
#!/usr/local/bin/pkgx python

print("Hello, World")
```

--------------------------------

### Dumping the environment

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/pkgx.md

How pkgx dumps the environment when no command is specified, and how to use it.

```sh
$ pkgx +gum
PATH="$HOME/.pkgx/charm.sh/gum/v0.14.5/bin${PATH:+:$PATH}"

$ eval "$(pkgx +gum)"
$ gum --version
gum version 0.14.5
```

--------------------------------

### Using system man with Pkgx

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/faq.md

To use the system's `man` tool with a Pkgx environment, use the `--` flag.

```sh
pkgx +foo -- man foo
```

--------------------------------

### Listing Available Versions for a Package

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/pkgx.md

This command lists the available versions of a package that pkgx can manage.

```sh
$ pkgx mash inventory git
2.38.1
2.39.0
```

--------------------------------

### Listing What is Downloaded

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/pkgx.md

This command lists the packages that are currently downloaded and managed by pkgx.

```sh
$ pkgx mash ls

  Parent Directory                │Version
  ────────────────────────────────┼──────────
  perl.org                        │5.40.0
  x.org/xcb                       │1.17.0
```

--------------------------------

### Compile pkgx

Source: https://github.com/pkgxdev/pkgx/wiki/Building-pkgx

Steps to clone the pkgx repository and compile the project using Deno tasks.

```bash
git clone https://github.com/pkgxdev/pkgx.git
cd pkgx
pkgx deno task compile
./pkgx
```

--------------------------------

### Viewing man pages for Pkgx packages

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/faq.md

To view a man page for a Pkgx package, you must first create an environment containing the package and then invoke `man`.

```sh
pkgx +foo man foo
```

--------------------------------

### Setting PKGX_DIR for virtual environments

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/pkgx.md

How to use PKGX_DIR to create isolated package environments.

```sh
$ export PKGX_DIR="$PWD/foo"  # must be an absolute path or is ignored

$ pkgx +gum
$ find foo
foo/charm.sh/gum/v0.14.5/bin/gum

$ eval "$(pkgx +gum)"
$ echo $PATH
$PWD/foo/charm.sh/gum/v0.14.5/bin/gum:…
```

--------------------------------

### List downloaded packages

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/faq.md

Command to list all packages that pkgx has downloaded.

```shell
pkgx mash ls
```

--------------------------------

### Running a specific version of a package

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/pkgx.md

How to run a specific version of a package using version specifiers.

```sh
$ pkgx postgres@12 --version
postgres (PostgreSQL) 12.14
```

--------------------------------

### Environment Variable Export

Source: https://github.com/pkgxdev/pkgx/blob/main/README.md

Achieving the same result as `env +git` by evaluating pkgx output, with optional environment export.

```bash
eval "$(pkgx +git)"

```

--------------------------------

### Upgrading packages

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/pkgx.md

Command to upgrade all or specific packages to their latest downloaded versions.

```sh
$ pkgx mash upgrade
updating: /Users/mxcl/.pkgx/python.org/v3.11.11
# snip…

You can specify args to upgrade only specific packages.
```

--------------------------------

### Upgrade pkgx

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/faq.md

Instructions on how to upgrade the pkgx CLI tool.

```shell
brew upgrade pkgx
```

```shell
curl -LSsf pkgx.sh | sh
```

--------------------------------

### Inspecting a package environment

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/deeper-dives/conceptual-overview.md

Shows how to invoke `pkgx` raw to view the environment variables set for a specific package, in this case, `+node`.

```sh
$ pkgx +node
SSL_CERT_FILE=~/.pkgx/curl.se/ca-certs/v2023.5.30/ssl/cert.pem
PATH=~/.pkgx/unicode.org/v71.1.0/bin:~/.pkgx/unicode.org/v71.1.0/sbin:~/.pkgx/openssl.org/v1.1.1u/bin:~/.pkgx/nodejs.org/v20.5.0/bin
MANPATH=~/.pkgx/unicode.org/v71.1.0/share/man:~/.pkgx/zlib.net/v1.2.13/share/man:~/.pkgx/nodejs.org/v20.5.0/share/man:/usr/share/man
PKG_CONFIG_PATH=~/.pkgx/unicode.org/v71.1.0/lib/pkgconfig:~/.pkgx/openssl.org/v1.1.1u/lib/pkgconfig:~/.pkgx/zlib.net/v1.2.13/lib/pkgconfig
LIBRARY_PATH=~/.pkgx/unicode.org/v71.1.0/lib:~/.pkgx/openssl.org/v1.1.1u/lib:~/.pkgx/zlib.net/v1.2.13/lib
LD_LIBRARY_PATH=~/.pkgx/unicode.org/v71.1.0/lib:~/.pkgx/openssl.org/v1.1.1u/lib:~/.pkgx/zlib.net/v1.2.13/lib
CPATH=~/.pkgx/unicode.org/v71.1.0/include:~/.pkgx/openssl.org/v1.1.1u/include:~/.pkgx/zlib.net/v1.2.13/include:~/.pkgx/nodejs.org/v20.5.0/include
XDG_DATA_DIRS=~/.pkgx/unicode.org/v71.1.0/share:~/.pkgx/zlib.net/v1.2.13/share:~/.pkgx/nodejs.org/v20.5.0/share
DYLD_FALLBACK_LIBRARY_PATH=~/.pkgx/unicode.org/v71.1.0/lib:~/.pkgx/openssl.org/v1.1.1u/lib:~/.pkgx/zlib.net/v1.2.13/lib
```

--------------------------------

### Symlink wget to /usr/local/bin

Source: https://github.com/pkgxdev/pkgx/wiki/Basics

Creates a symbolic link for wget in /usr/local/bin to allow direct execution without pkgx.

```shell
cd /usr/local/bin
ln -s ~/.pkgx/gnu.org/wget/v*/bin/wget
```

--------------------------------

### Basic pkgx usage

Source: https://github.com/pkgxdev/pkgx/wiki/Basics

The fundamental command structure for using pkgx to run a command with its arguments.

```shell
pkgx +pkg cmd [args]
```

--------------------------------

### Uninstalling packages

Source: https://github.com/pkgxdev/pkgx/wiki/Basics

Command to remove a package by deleting its directory.

```shell
rm -r ~/.pkgx/**pkg_name**
```

--------------------------------

### Ensuring packages

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/pkgx.md

Using the 'ensure' script to use system packages if available, otherwise pkgx packages.

```sh
$ pkgx mash ensure git --version
# ^^ runs system `git` if installed, otherwise installs the `pkgx` pkg

$ eval "$(pkgx mash ensure +git)"
# ^^ adds pkgx git to the environment *unless* it is installed to the system
```

--------------------------------

### Upgrade specific pkgx packages

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/faq.md

Command to upgrade all downloaded pkgx packages.

```shell
pkgx mash upgrade
```

--------------------------------

### Uninstall pkgx

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/faq.md

Commands to completely uninstall pkgx and its associated data.

```shell
sudo rm /usr/local/bin/pkg[xm]
rm -rf ~/.pkgx
```

--------------------------------

### Update pkgx's pantry

Source: https://github.com/pkgxdev/pkgx/wiki/Basics

Command to update pkgx's pantry.

```sh
pkgx --sync
```

--------------------------------

### Symlink pkgx to /usr/local/bin

Source: https://github.com/pkgxdev/pkgx/wiki/Basics

Creates a symbolic link to pkgx itself in /usr/local/bin, allowing it to be executed by its symlink name.

```shell
sudo ln -s pkgx /usr/local/bin/wget
```

--------------------------------

### Core Commands

Source: https://github.com/pkgxdev/pkgx/blob/main/AGENTS.md

Core commands for the pkgx CLI repository.

```bash
cargo fmt --all -- --check
```

```bash
cargo clippy --all-features
```

```bash
cargo test --all-features
```

--------------------------------

### Update pkgx (tea sync)

Source: https://github.com/pkgxdev/pkgx/wiki/Basics

Command to have tea update itself.

```sh
pkgx --sync +pkgx.sh
```

--------------------------------

### Uninstall pkgx on Non-macOS

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/faq.md

Platform-specific commands for uninstalling pkgx cache and data on non-macOS systems.

```shell
rm -rf "${XDG_CACHE_HOME:-$HOME/.cache}/pkgx"
rm -rf "${XDG_DATA_HOME:-$HOME/.local/share}"/pkgx
```

--------------------------------

### Pruning older versions of packages

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/pkgx.md

Command to remove older versions of packages from the pkgx cache to save space.

```sh
$ pkgx mash prune
pruning: ~/.pkgx/deno.land/v1.39.4
pruning: ~/.pkgx/deno.land/v1.46.3
```

--------------------------------

### Uninstall pkgx on macOS

Source: https://github.com/pkgxdev/pkgx/blob/main/docs/faq.md

Platform-specific commands for uninstalling pkgx cache and data on macOS.

```shell
rm -rf ~/Library/Caches/pkgx
rm -rf ~/Library/Application\ Support/pkgx
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.