pik

README

pik

file-based task runner mepik.dev

the goal

are you ever uncertain what to do after cloning a repository? pik aims to fix this by making tasks findable, predictable and programmable.

running pik in any repository will index its own file-based task system, as well as supported external systems.

installing

go install

go install github.com/ewy1/pik@latest

manual install

• git clone https://git.ewy.one/pik/
• cd pik

if you were already using pik, pik install would suffice!

thankfully you can pik yourself:

• bash .pik/install.sh

wow! you just learned about piks simplest usage!

getting started

1. if you are already using a supported external runner from here, you can use it with pik by simply replacing the command with pik.

2. create a .pik folder in your project

3. put a script in there, for example: .pik/build.sh containing go build .

4. run pik to view all targets or pik build to start the build script.

5. you can now access this script from almost anywhere with pik build. If you want to trigger a specific projects build, specify pik project build, where project is the folder name.

scripts will always run in the project directory, not in the .pik folder.

killer features

pik comes equipped with a tui that allows for target browsing and invoking. open it by running pik. the output also gently reminds you how to run the invocation next time!

pik remembers your projects, and you can invoke stuff almost anywhere. to view everything pik knows, try pik -a!

pik reads the first comment line from your targets and informs you in the tui!

current features

• run targets by their approximate name: pik build will trigger .pik/build.sh, or .pik/build.py, or make build depending on what's possible.
  • including external targets from here
• specify source names to search for the target in that source explicitly: pik myproject build can run ../../myproject/.pik/build.sh and `
• unless overridden, targets will run in the directory where the .pik folder resides.
• use --all flag to start out-of-tree targets without having to navigate to the directory.
• --here to run the target in the current working directory instead of the source directory.
  • --at to run the target in an arbitrary location
• target tags in filenames which trigger flag behaviours
• aliases to sources through the .alias file
• y/n confirmation with yes as default
  • will be used if we have an uncertain target guess
  • --yes to automatically confirm y/n prompts
• autoload .env files
  • both the project root and .pik folder will be searched
  • values specified with --env will be tried as pre- and suffixes: --env asdf will load .env-asdf and asdf.env if they exist.
  • env files are reread for every trigger, meaning you can have a pre-trigger fetch credentials and save it in .env
• create any kind of target: high-level support for shell and python, and arbitrary shells with the shebang.
• tab completion
  • currently bring-your-own integrations: pik --completion echoes bash completion logic

tui

• tui for viewing and running targets
• descriptions for targets based on first comment in a target
• external targets will also show up in the tui
• search with / and ?, scroll results with n and N

supported pik runners

• python
• shell
• executable files
• java- and typescript

supported external runners

• just
• make
• pyproject.toml
• if you want any more let me know and it should be done very fast

planned features

As this program has already gone through a number of iterations and forms, this (hopefully permanent) version will need time to catch up with all the features it used to have. This list is not exhaustive, but it is ordered by importance I attach to these features.

• whitelists for external runners in .pik
  • adding descriptions to external targets
• expand tui:
  • support for categories and ordering of targets through the .order file
  • more hotkeys (filter jumping, toggle all, etc.)
• git pre-commit and pre-push triggers
• linking sources together by .include and .wants files

thanks

this repository lives here

this software is and was intentionally produced without llms