Getting Started
With pkgx
it couldn’t be simpler to run anything from the Open Source
ecosystem:
$ pkgx openai --version
openai 1.59.6
Search
Generally you don’t need to search since you already know what you want to run, so just type it! Sometimes though you want to browse.
We have a web based package listing atpkgx.dev/pkgs/. This is the most thorough resource at this time.
And from the CLI you can use query mode:
$ pkgx -Q git
# ^^ can we run git?
$ pkgx -Q | grep git-
# ^^ search for all git extensions
$ $ pkgx -Q
# ^^ list every program pkgx can run
Run Any Version
$ pkgx postgres@12 --version
postgres (PostgreSQL) 12.14
SemVer
Generally you probably want @
syntax, but if you need more specificity we
fully support SemVer:
$ pkgx postgres^12 --version
postgres (PostgreSQL) 12.14
$ pkgx "postgres>=12<14" --version
postgres (PostgreSQL) 13.11
$ pkgx deno=1.35.3 --version
deno 1.35.3
Running the Latest Version
pkgx foo
runs the latest “foo” that is installed.
If you want to ensure the latest version of “foo” is installed, usepkgx mash upgrade foo
.
Adding Additional Packages to the Execution Environment
It can be useful to run a program with additional packages in the environment.
pkgx +openssl cargo build
Here +pkg
syntax added OpenSSL to Cargo’s environment. Thus the build will see
the OpenSSL headers and libraries.
Disambiguation
In some cases pkgx foo
may be ambiguous because multiple packages providefoo
.
In such cases pkgx
will error and ask you be more specific by using
fully-qualified-names:
$ pkgx yarn --version
error: multiple projects provide `yarn`. please be more specific:
pkgx +classic.yarnpkg.com yarn --version
pkgx +yarnpkg.com yarn --version
In general it's a good idea to specify fully qualified names in scripts, etc. since you want these to work forever.
Running System Commands
It can be useful to run system commands with a package environment injected. To do this either specify the full path of the system executable:
pkgx +llvm.org /usr/bin/make
Or separate your commands with --
:
pkgx +llvm.org -- make # finds `make` in PATH, failing if none found
If you only specified make
rather than /usr/bin/make
or separating with-- make
then pkgx
would install GNU make for you and use that.
Dumping the Environment
If you don’t specify anything to run, pkgx
will install any +pkg
s and then
dump the environment:
$ pkgx +gum
PATH="$HOME/.pkgx/charm.sh/gum/v0.14.5/bin${PATH:+:$PATH}"
This can be useful in scripts or for adding tools to your shell:
$ eval "$(pkgx +gum)"
$ gum --version
gum version 0.14.5
For this mode we can also output JSON: pkgx +gum --json
.
Quietening Output
$ pkgx --quiet gum format 'download progress is still shown'
# ^^ supresses resolving/syncing etc. messages but not download progress info
# `pkgx -q` is the same
```sh
pkgx --silent gum format 'no output at all'
# ^^ silences everything, even errors
# ^^ `pkgx -qq` is the same
Note that this only effects pkgx
not the tools you run with pkgx
.
Ensuring Packages
In some cases you don’t want to use a pkgx
package if the user has that
package already installed to their system. For these cases we provide anensure
script:
$ 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
“Virtual Environments”
You can set PKGX_DIR
to have pkgx
install packages there. This can be useful
for creating “virtual environments” for various usages.
$ 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:…
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.
Listing Outdated Packages
pkgx mash outdated
Upgrading Packages
pkgx foo
executes the latest version of foo
that is downloaded. To ensure
you have (any) newer versions installed use this command:
$ pkgx mash upgrade
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:
$ pkgx mash 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
:
$ pkgx mash inventory git
2.38.1
2.39.0
# snip…
Listing What is Downloaded
$ pkgx mash ls
Parent Directory │Version
────────────────────────────────┼──────────
perl.org │5.40.0
x.org/xcb │1.17.0
# snip…
Last updated