1.6.1 • Public • Published


Project management for power users.


$ npm install -g projects


If the majority of your projects are subdirectories of one folder then the easiest way to get started is this (in my case my projects live underneath ~/p/):

$ npm install -g projects
echo "alias p=projects" >> ~/.bashrc
source ~/.bashrc
$ vim ~/.config/projects
# edit like so (note: this file will probably become JSON soon!) 
username = beaugunderson
directory = ~/p
$ p import ~/p/*
$ p github  # if you want to import metadata about your GitHub projects too 

Try p remind, p git-status, p git-unpushed, and p not-git for examples of the time savings and management functionality I'm trying to enable.

Note that the color scheme currently assumes a dark background; if you find it hard to read try DISABLE_COLOR=true in your environment (a revamp of all colors is coming in the next version).

Shell completion

For autocompletion you can redirect projects --completion to a file in ~/.bash_completion (zsh is also supported) or use which also contains a fallback to _filedir so that you can still complete files and directories (I've opened an issue to get that improvement back into omelette, the completion library we use).


Command Description
alias output shell aliases
clone git clone a project
each run a command in each project directory
edit edit projects files
gc compact the projects database
get get an attribute for a project
git-status git status across all repositories
git-unpushed display repositories with unpushed commits
github fill your projects database with your GitHub repositories
glob glob across all project directories
import import a directory into projects
info show the JSON for a given project
json-in import your projects from plain JSON
json-out export your projects to plain JSON
ls list your porojects
open open a project's homepage
not-git list projects not in git
query query your projects
remind get a reminder of what you were last working on
set set an attribute to a given value for a project

Writing your own commands

Projects is primarily a framework for making it easy to execute actions on one or more of your projects. For example, you could write a command to check the clean/dirty status of all of your checked out git repositories and list the dirty ones.

If you have an executable file in your PATH that starts with projects- then you can execute it underneath projects (and you're encouraged to share them with others!)


alias p=projects
$ cat ~/.config/projects
username = beaugunderson
directory = ~/p
$ p info vim-scss-instead
$ p set vim-scss-instead homepage
Set vim-scss-instead:homepage to ""
$ p open vim-scss-instead # opens a web browser to the homepage URL 
$ p clone vim-scss-instead
Cloning into '/Users/beau/p/vim-scss-instead'...
remote: Counting objects: 5, done.
remote: Compressing objects: 100% (4/4)done.
remote: Total 5 (delta 0), reused 5 (delta 0)
Receiving objects: 100% (5/5)done.
$ p github
Adding vim-scss-instead
Adding vim-human-dates
$ p git-unpushed
node-helmsman: 6 commits ahead of origin
projects: 3 commits ahead of origin

You can also use something like fzf to make selecting a project via the CLI very easy:

contract-home() {
  sed "s|^$HOME|~|"
# cd to a project via fzf 
pd() {
  cd $(projects ls -1 | \
    fzf --query="$1" | \
    xargs -I {} projects get --porcelain "{}" directory)
# open a project's URL via fzf 
po() {
  open $(projects ls -1 | \
    fzf --query="$1" | \
    xargs -I {} projects get --porcelain "{}" homepage)
# edit a project file with $EDITOR via fzf 
# note: requires gnu findutils 
# on OS X you'll want to: 
# `npm install -g ignore-pipe` 
# `brew install findutils --with-default-names` 
pe() {
  FILTERS='-type f '
  # filter out .git and node_modules with -prune to make the find much faster 
  FILTERS+='-not -path \*/.git/\* -prune '
  FILTERS+='-not -path \*/node_modules/\* -prune '
  if PROJECT_DIRECTORY=`projects resolve --relative .`; then
    FILE=$(bash -c "find $PROJECT_DIRECTORY \
      $FILTERS $ADDITIONAL_FILTERS 2> /dev/null" | \
        ignore-pipe | contract-home | fzf)
    FILE=$(projects glob --expand | \
      xargs -I {} bash -c "find "{}" \
        $FILTERS $ADDITIONAL_FILTERS 2> /dev/null" | \
         ignore-pipe | contract-home | fzf)
  # bash -c needed to handle tilde expansion 
  [ ! -z "$FILE" ] && bash -c "${EDITOR:-vim} "$FILE""
# edit a project file modified within in the last 7 days 
per() {
  pe "-mtime -7"



Package Sidebar


npm i projects

Weekly Downloads






Last publish


  • beaugunderson