dpx - execute Dart package binaries

Installation

dart pub global activate dpx

For ease of use, follow these instructions to add the system cache bin directory to your path so that you can run dpx directly.

Usage

dpx <package-spec>[:<package-executable>] [-e <executable>] [args...]

First, dpx will globally activate the package specified by <package-spec>. Then it will run a command.

If neither :<package-executable> nor -e <executable> are specified, dpx will run the default package executable from <package>. This is equivalent to:

dart pub global run <package> [args...]

If :<package-executable> is specified, dpx will run that executable from the installed package. This is equivalent to:

dart pub global run <package>:<package-executable> [args...]

If -e <executable> is specified, dpx will run <executable> [args...] directly after installing the package. This allows you to opt-out of the default method that uses dart pub global run. This may be useful for Dart packages that declare an executable in the pubspec that would be available in the PATH, or if other executables outside of the package need to be used.

Exit Status

Package Sources

The first arg to dpx is referred to as a <package-spec>, which supports several different formats to enable installing from different sources and targeting specific versions.

# Install from pub with an optional version constraint.
# Syntax:
dpx <pkg>[@<version-constraint>] [args...]
# Example:
dpx webdev@^3.0.0 [args...]

# Install from custom pub server.
# Syntax:
dpx pub@<pub-server>:<package>[@<version-constraint] [args...]
# Example:
dpx pub@pub.workiva.org:dart_null_tools@^1.0.0

# Install from a github repo.
# Syntax:
dpx <git-url> [args...]
# Example:
dpx https://github.com/Workiva/dpx.git --help

# Shorthand for public github repos:
dpx github:<org>/<repo> [args...]

# Shorthand for private github repos:
dpx github+ssh:<org>/<repo> [args...]

# Optionally, all git-based package specs can specify:
# - <path> if the package is not in the root of the repo
# - <ref> to checkout a specific tag/branch/commit
# Syntax:
dpx <git-url>#path=sub/dir,ref=v1.0.2 [args...]
# Examples:
dpx github:Workiva/dpx#ref=v0.1.0 --help
dpx github:Workiva/dpx#path=example/dpx_hello
dpx github:Workiva/dpx#path=example/dpx_hello,ref=v0.1.0

Troubleshooting

If you encounter any issues, please run the command again with --verbose:

dpx --verbose ...

This will provide a lot more detail that might help identify the cause of your issue. If not, please open an issue and include the verbose logs.

Why the name?

It's like npx, but for Dart.

Dart Package eXecute.

Acknowledgements

dpx is inspired by the npx package, which is now a part of the npm CLI.