pj-sh 0.0.2

ProJect management toolkit

pj

Installation

Install from PyPI:

$ uv tool install pj-sh

or latest from the GitHub repository:

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

How to use pj

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

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

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.

The Three Phases

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

Design Principles

• 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
pip install -e .

# make changes under nbs/ directory
# ...

# compile to have changes apply to pj
nbdev_prepare

Usage

Documentation

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