Context-aware single-letter project commands to speed up your command-line workflow.

•   🏗   b to build/compile any project.
•   🚀   r to run/start any project.
•   🧪   t to test any project.

https://user-images.githubusercontent.com/521604/231857437-12c14aff-585d-4817-8f44-59b40ecc32e0.mov

• Supports over 20 build and project tools – Bun, Cabal, Cargo, CMake, .NET, Dune, Go, Gradle, Lake, Leiningen, Mage, Maven, Meson, Poetry, Stack, Tectonic, just, make, nix, npm, pnpm, and yarn. More details.
• Portable – Dependency-free portable POSIX shell script. Supports Linux, macOS, WSL, etc.
• Shell Integration – Works with aliases in any shell and for the Fish shell through a Fish plugin.
• Simple – Easy to extend with support for new tools.

Why & What

If you're a developer and command line user, you're probably constantly using commands like make, cargo run, npm test, etc. The common approach of using shell aliases to provide shorthand forms for frequently used commands does not work well in these cases. For example, creating an alias like b for cargo build one day is completely useless the next day when working in a project that uses a different build tool.

projectdo solves that problem. It executes project actions (such as build, run, test, etc.) with the appropriate tool for the project in the current working directory. The appropriate tool is intelligently detected based on the context where projectdo is executed. For instance, projectdo test runs cargo test if a Cargo.toml is found and npm test if a package.json file is found.

By combining projectdo with shell aliases, project commands can be run in any project with minimal typing. As an example, with the alias alias b='projectdo build', you can build any project simply by typing b+enter.

Install

projectdo can be installed through a number of package managers or by manually downloading the shell script.

Homebrew

projectdo can be installed with Homebrew on macOS and Linux.

brew install paldepind/tap/projectdo

AUR (Arch Linux)

The AUR package can be installed manually or using an AUR helper.

yay -S projectdo

npm

projectdo is not related to Node.js or JavaScript, but npm works perfectly fine for distributing shell scripts and can be a handy installation method if you're already using npm:

npm i -g projectdo

From source

Download the script and place it somewhere in your path. For instance if ~/bin is in your path:

curl https://raw.githubusercontent.com/paldepind/projectdo/main/projectdo -o ~/bin/projectdo
chmod +x ~/bin/projectdo

From repository

Clone the project repository:

git clone https://github.com/paldepind/projectdo; cd projectdo

Install it with this command:

make install
Or to uninstall
make uninstall

Shell integration

For the Fish shell use the Fish plugin. For Bash and Zsh setup shell aliases.

Fish Plugin

projectdo ships with a plugin for the Fish shell. The plugin includes auto-completion and functions for use with Fish's abbreviation feature.

The Fish plugin can be installed manually or with Fisher:

fisher install paldepind/projectdo

The plugin exposes four shell functions that should be configured with abbreviations as desired. For instance:

abbr -a b --function projectdo_build
abbr -a r --function projectdo_run
abbr -a t --function projectdo_test
abbr -a p --function projectdo_tool

With the above configuration, t will expand to cargo test, p will expand to cargo, etc. depending on the project.

Note that you need to have the script in your path in order for the Fish plugin to work!

Aliases

projectdo can be configured with shell aliases in any shell. For instance:

alias t='projectdo test'
alias r='projectdo run'
alias b='projectdo build'
alias p='projectdo tool'

Usage

Note: When executed with the -d flag, projectdo performs a dry run and only prints information about what it would do without actually doing anything. It is a good idea to do a dry run when using projectdo in a project for the first time to verify that it does the right thing.

Usage: projectdo [options] [action] [tool-arguments]
Options:
  -h, --help             Display this help.
  -n, -d, --dry-run      Do not execute any commands with side-effects.
  -q, --quiet            Do not print commands as they are about to be executed.
  -v, --version          Display the version of the program.
Actions:
build, run, test       Build, run, or test the current project.
tool                   Invoke the guessed tool for the current project.
Tool arguments:
Any arguments following [action] are passed along to the invoked tool.

Supported tools and languages

Note: If a tool you're interested in is not supported, please open an issue or a pull request.

Tool	Language	Detected by	Commands
bun	JavaScript, etc	package.json and bun.lock/bun.lockb	bun build bun start bun test
Cabal	Haskell	*.cabal	cabal build cabal run cabal test
Cargo	Rust	Cargo.toml	cargo build cargo run cargo test
CMake	C, C++ and Obj-C	CMakeLists.txt	cmake --build . --target test
Dune	OCaml	dune-project	dune build dune exec dune runtest
Go	Go	go.mod	go test
Gradle	Java, etc.	build.gradle or build.gradle.kts	gradle compile gradle run gradle test
just	Any	justfile	just build just run just test
Lake	Lean	lakefile.lean or lake-manifest.json	lake build lake run lake test
Leiningen	Clojure	project.clj	lein test
Mage	Go	magefile.go with a test/check target	mage test/check
make	Any	Makefile	make make test/check
Maven	Java, etc.	pom.xml	mvn compile run n/a mvn test
Meson	C, C++, etc.	meson.build	meson compile run n/a meson test
.NET	C# and F#	*.csproj, *.fsproj or *.sln	dotnet build dotnet run dotnet test
nix (flake)	nix	flake.nix	nix build nix run nix flake check
nix (non-flake)	nix	default.nix	nix-build
npm	JavaScript, etc.	package.json	npm build npm start npm test
pnpm	JavaScript, etc	package.json and pnpm-lock.yaml	pnpm build pnpm start pnpm test
Poetry	Python	pyproject.toml with [tool.poetry]	poetry build run n/a poetry run pytest
Shell script	Any	build.sh	sh -c build.sh
Stack	Haskell	stack.yaml	stack build stack run stack test
Tectonic	LaTeX	Tectonic.toml	tectonic -X build
yarn	JavaScript, etc.	package.json and yarn.lock	yarn build yarn start yarn test