// user guide & command reference

⚒ devforge

YOUR DEVELOPER COCKPIT — MODULAR · FAST · EXPRESSIVE

v0.3.9 — now on npm

01 // installation

terminal

$ npm install -g forged-cli

$ forged init

# then reload your shell — exec zsh

💡 devforge writes to ~/dev/dotfiles and adds a source hook to ~/.zshrc automatically. Your existing config is never overwritten.

02 // project workflow

⚡

dev

OPEN · BOOT · GO

dev open fuzzy project picker

dev myproject open directly by name

p fuzzy pick any project dir

pr pick project + launch editor

cd project → detect type → boot plugin

🆕

newproj

SCAFFOLD · INIT · PUSH

newproj interactive project creator

newproj myapp create with name pre-filled

name + template

node / python / rust / none

git init + README

.gitignore, .env.example auto-created

optional: create GitHub repo

via gh CLI — private by default

🔭

navigate

JUMP · EXPLORE · ARRIVE

j fuzzy jump (zoxide memory)

fcd [dir] fuzzy cd from any point

.. cd ..

take <dir> mkdir + cd in one step

Use Ctrl+E to open the file explorer widget from anywhere.

03 // git shortcuts

🌿

branch ops

CREATE · SWITCH · MERGE

cb create + switch to new branch

cm switch to main or master

gbr fuzzy switch any branch

gss <branch> git switch

📋

commit + sync

STAGE · COMMIT · PUSH

gs git status

git add . stage all changes

gc -m "msg" git commit -m

gca "msg" git commit -a -m (add + commit)

gp git push

gpl git pull

gl git log (graph, oneline)

gst / gstp git stash / stash pop

04 // keyboard shortcuts

⌨️

keybindings

WIRED TO ZLE — INSTANT ACCESS

Ctrl+P command palette — your entire ecosystem at a keystroke. fuzzy search every command, alias, plugin, and hook with live preview.

Ctrl+R fuzzy history search — enhanced with neon theme, preview pane, and full history navigation.

Ctrl+E file explorer widget — tab to enter dirs, shift+tab to go up, enter to cd or insert path.

Ctrl+G GitHub workflow — stage files, commit, open PRs, create issues with labels + assignee, auto-creates project board. The full issue → branch → PR loop without leaving the terminal.

Ctrl+D project dashboard — full UI with open, create, recent, GitHub, cache ops.

Tab fzf-powered completion — fuzzy search completions with live preview via fzf-tab.

05 // project auto-detection

🔍

project_detect()

FIRES ON EVERY cd — BOOTS THE RIGHT PLUGIN

📦

Node

package.json

🐍

Python

requirements.txt

🦀

Rust

Cargo.toml

🐹

go.mod

On cd, devforge fires the on_dir_enter hook → detects type → calls boot_project <type> → runs the registered plugin function.

📦

node boot

AUTO-INSTALL · DEV SERVER

check node_modules

installs if missing or package.json is newer

open VS Code in background

nohup code . — non-blocking

npm run dev

falls back gracefully if no dev script

🐍

python boot

VENV · INSTALL · REMEMBER

first-run preference

always auto-boot / always ask / skip — saved to ~/.config/forged/

create .venv if missing

python3 -m venv .venv

activate + install deps

source .venv/bin/activate → pip install -r requirements.txt

06 // github dashboard & issue workflow

⌨️

Ctrl+G — issue → branch → PR loop

THE FULL WORKFLOW WITHOUT LEAVING THE TERMINAL

Create Issue

Title → Body → Labels (Tab multi-select) → Assignee → Branch type — auto-creates fix/42-my-issue, sets status to In Progress, creates project board if none exists

Stage & Commit

Ctrl+G → Stage & Commit — fuzzy-pick changed files, enter commit message, done

Open PR

Ctrl+G → Open PR — pushes branch, pre-fills PR body with Closes #42 (detected from branch name), sets status to In Review. Merge → issue closes automatically.

💡 One-time setup: run gh auth refresh -s project to grant Projects v2 scope. After that, project boards are created and linked automatically for every repo.

🐙

github_ui / ghui

FULL TUI — NO BROWSER REQUIRED

ghui open GitHub dashboard

github_ui_prs list + act on pull requests

github_ui_issues list + act on issues

github_ui_repos browse your repos, clone or view

github_ui_clone fuzzy-pick a repo to clone

github_ui_new create a new GitHub repo

github_ui_sync_fork sync a fork with upstream

🔧

dev utilities

SERVER · ENV · PORTS

serve [port] local HTTP server (default 8080)

killport <port> kill whatever's running on that port

ports show all listening TCP ports

envload [file] load .env into current shell

reload exec zsh — full shell restart

safe zsh -f (no config, clean env)

07 // shell aliases

🔗

aliases

MUSCLE MEMORY SHORTCUTS

ll eza -la --icons (detailed list)

ls eza --icons

cat bat (syntax-highlighted)

grep grep --color=auto

mkdir mkdir -p (creates parents)

c clear

.. cd ..

sz source ~/.zshrc

reload exec zsh -l (full shell restart)

safe zsh -f (no config, clean env)

gs git status

gc git commit

gca git commit -a -m

gp git push

gpl git pull

gl git log --oneline --graph

gr git restore

gss git switch

gb git branch

gco git checkout

gst git stash

gstp git stash pop

ghui github_ui dashboard

08 // architecture

📂

load order

.ZSHRC IS A PURE LOADER — NO LOGIC

# .zshrc sources in this order:
plugins.zsh          # zinit external plugins
lib/plugin-registry # PLUGIN_REGISTRY assoc array
hooks.zsh            # hook dispatcher
plugins/project/*.zsh # lang boot plugins
lib/*.zsh            # cache, detect, project
env → tools → aliases → dev → starship

🪝

hook system

EVENT-DRIVEN SHELL BEHAVIOR

register_hook bind a function to an event

fire_hook execute all fns for an event

on_dir_enter fires on every cd (auto-venv, auto-nvm)

on_enter/rust fires only in Rust projects

auto-venv auto-nvm rust completions

09 // write a plugin

🔌

custom boot plugin

plugins/project/<lang>.zsh

# 1. Define the boot function
project_boot_mylang() {
  [[ -f marker.file ]] || return 1
  echo "🚀 mylang boot"
  # your setup logic here
}

# 2. Register it — priority 10 = high
register_plugin mylang project_boot_mylang 10

# 3. Done. devforge calls it automatically on cd.

⚠ Plugin file must be in plugins/project/*.zsh — it's auto-sourced by .zshrc at startup.

10 // cache + debug

💾

cache system

FAST DISCOVERY — fd BACKED

refresh-dev-cache regenerate ~/.dev-projects-cache

add-recent append PWD to ~/.dev-recent (cap 50)

~/.dev-projects-cache ~/.dev-recent

🔬

debug commands

INSPECT · PROFILE · VALIDATE

zsh -n file.zsh syntax check without executing

zprof profile shell startup time

vared PLUGIN_REGISTRY inspect registered plugins

vared _HOOKS inspect registered hooks

heredoc_lint file detect broken heredocs in any .zsh