DEV Community

Cover image for project-butler: An easy tool to manage multiple projects
David Lorenz
David Lorenz

Posted on


project-butler: An easy tool to manage multiple projects

In my time of "silence" lately I have been working on getting project-butler to a final release.

GitHub logo activenode / project-butler

A cli project manager

CLI Project Manager

Known Vulnerabilities License: MIT

Build status master Build status develop
activenode activenode


  1. Install package npm -g install project-butler and follow the helper to select your shell
  2. Reload your shell
  3. DONE. You can use it now by calling p


Usage as Videos

Adding and switching between projects


Removing aliases and removing projects


Usage as Documentation

$ p [options] [COMMAND] [args]
    p                             | list available projects
    p add                         | adds current directory to projects
    p remove project-name         | removes an alias (not the whole project)
    p cd project-name             | opens the given project (explicit version of `p script-name`)
    p project-name                | opens the given project (shortcut for `p cd`)
    p script-name                 | if inside a project you can trigger a script with this
    p --help                      | show help menu

Why would I choose p cd project over p project?

Well since project-butler is able to run your scripts the following could…


npm i project-butler -g will install a terminal alias called p with which you can switch between projects without cd and without even writing out the full name. E.g. switch to your /bla/foo/todolist by simply calling p todo

It also reads the package.json if exists and the existing scripts and can run them if needed.


If you are like me you will probably have multiple projects laying around, probably in your home directory somewhere below ~/codestuff/... .

If I know exactly that I want to work on e.g. project-butler I dont want to cd into the directory but i just wanted to go like p but or even p b (whatever fits me best).

I wanted to make project-butler as universal as it can get such that in the future it can complement all of the other tools that I am having.

How it works

project-butler will create a hidden directory called .project-butler in your home directory and store the configuration.

In the configuration it will simply create a table with mappings from aliases -> project.

Imagine it like that:

Aliases Mapped path
todolist,todos ~/my-stuff/angular/todolist
butler,foobar ~/my-stuff/project-butler

The above table would indiciate that calling p todos or even p dos (since there is a "next-best-match-search") would always bring you to the angular todolist directory.

Adding a project

Adding a project in project-butler

p add [aliases...] if you are in the directory that you want to add
p add -d ./relative/path [aliases...] if you are outside of the directory

If you set the optional param aliases you can map the directory to whatever you want e.g.
p add my-alias and then you can open it with p my-alias.

Calling p add for the same directory multiple times will simply update it.

Removing an alias from a project

p remove alias - since aliases are unique you dont have to be in the directory nor do you have to provide the directory

Removing a project in project-butler

Removing a complete project from the list

p remove alias -a will remove ALL aliases and therefore the mapping.

Alternative version: p project-name && p remove will jump to the project and then remove it.

Calling an npm script with project-butler

Make sure that you have added the project directory to project butler.

Now you can go to the project with p project-alias and simply call p script-name. It will read the package.json and try to run the script-name. If it does not find it it will instead try to find the fitting project with that name.

List all existing mappings

p list-all

What are YOU missing in project-butler?

I know that at this very point project-butler is just at the start of its path and it can go a good way to become an even better daily helper.

Is there anything you can imagine this tool should solve for you? Just comment below or even try a detailed explanation on the GitHub Issues and even potentially try to contribute if you want:

Top comments (2)

mredel profile image

That's pretty neat, perhaps I'll have a look. Right now I use autojump for a similar usecase:

activenode profile image
David Lorenz

autojump is very cool as well. Slightly different functionality but I was thinking to merge them eventually in a sense of pj etc. 🧐

Join us at DEV Want to join the conversation?

It's easy! Become a DEV member to follow this post, comment, and more.