pj-sh 0.0.4

project shell > hyperspace velocity

pj

pj, the project shell, has four commands:
pj init creates the entire nbdev project infrastructure and pushes to GitHub,
pj sync runs nbdev_prepare then commits and pushes,
pj ship bumps up GitHub version and releases to PyPI.org, pj kill stops background processes.
That’s it.

Install

Install from PyPI, ideally with uv:

$ uv tool install pj-sh

or latest from the GitHub repository:

$ uv tool install git+https://github.com/kitled/pj.git

Usage

pj init my-project  # start
pj sync             # work
pj kill             # end

Create complete nbdev project with pj init: GitHub repository, virtual environment, registered Jupyter kernel, direnv activation, dark theme toggle, initial commit pushed.

Subsequent pj sync runs the full export-test-clean-add-commit-push workflow in one invocation.

Find all options with --help after any command.

pj --help
pj init --help

init

Create new project

Start with pj init proj_name to create a GitHub repo, setup nbdev fully, and push ready to code.

pj init my-project -v \
 --desc "ML utilities" \
 --public \
 --python 3.12 \
 --license apache2

Everything is logged to init.log by default; use -v flag to see stdin/out.

sync

Automated nbdev_prepare, git commit and push.

Use pj sync to update remote;
flag -m "commit message" (default: “save”).

pj sync -m "Add new feature"

kill

Stop all servers

pj kill will terminate all running Jupyter, nbdev, Quarto processes on the host.

Why pj?

Purpose

Create a fully-configured GitHub + nbdev project with one command.
No manual setup, no forgotten steps. From zero to ready-to-code.

1. Checks - Validate prerequisites
2. Setup - Create repo, nbdev structure, venv, kernel, direnv
3. Sync - Prepare nbdev, commit, push

Features

• Clean output: One line per operation
• Verbose mode: Show commands and boxed output with -v
• Fail fast: Stop on first error
• Sensible defaults: Private repos, log to init.log, push immediately

Devs

If you are new to using nbdev here are some useful pointers to get you started.

Install pj in Development mode

# make sure pj package is installed in development mode
uv pip install -e .

# make changes under nbs/ directory
# ...

# compile to have changes apply to pj
nbdev_prepare

Documentation

Documentation can be found hosted on this GitHub repository’s pages.
Additionally you can find package manager specific guidelines on pypi.

See also uv docs if needed.