PushScript™ – User Guide

Everything you need to install, configure, and get the most out of PushScript.

---

1 · What is PushScript?

A drop‑in CLI that turns every Git commit into a Conventional Commit, scans for dependency problems, and blocks accidental secrets – all powered by your favourite LLM (Gemini by default; OpenAI, Groq, Anthropic also supported).

---

2 · Quick start (30 s)

# 1. Install Node ≥ 18
# macOS
brew install node

# 2. Run PushScript once via npx
export GEMINI_API_KEY="AIza…"       # get a free Gemini key
npx pushscript@latest                # generates a commit + push helper

First time on a freshly‑cloned repo? Skip npm install and just run: PUSHSCRIPT_SELF_HEAL=true npx pushscript@latest

---

2.1 · Global installation (optional)

For permanent installation across all projects:

# npm users
npm install -g pushscript@latest

# pnpm users  
pnpm add -g pushscript@latest

# Then use anywhere
pushscript --help

---

2.2 · Auto-setup for team projects

Add convenient npm scripts to any project automatically:

pushscript setup

This will interactively ask to add these shortcuts to your package.json:

{
  "scripts": {
    "push": "pushscript",           // commit + push with AI message
    "commit": "pushscript commit",  // commit only with AI message  
    "pushscript": "pushscript"      // direct CLI access
  }
}

Features:

• 🤖 CI-aware - Skips prompts in automated environments
• 🛡️ Safe - Won't overwrite existing scripts
• ⚡ One-time - Remembers your choice with .pushscript-setup marker
• 👥 Team-friendly - Each team member can choose their preference

After setup, teammates can use: npm run push, npm run commit, etc.

---

3 · Project‑level integration

// package.json
"scripts": {
  "push":   "pushscript",          // commit + push
  "commit": "pushscript commit"     // commit only
}

Teammates can now run npm run push. If your project uses pnpm, the equivalent commands are pnpm push and pnpm commit.

---

4 · Configuration

Create .env.local (or .env) in the repo root:

PUSHSCRIPT_LLM_PROVIDER=gemini  # default; see below for others
GEMINI_API_KEY=AIza...          # your key
GEMINI_PUSHSCRIPT_MODEL=gemini-2.0-flash  # optional

# Advanced
# PUSHSCRIPT_JSON_SIZE_LIMIT=256000
# PUSHSCRIPT_AUTO_GITIGNORE_JSON=true
# PUSHSCRIPT_SELF_HEAL=true

4.1 Other providers

Provider env	API key env	Default model
groq	GROQ_API_KEY	llama-3.3-70b-versatile
openai	OPENAI_API_KEY	gpt-4o
anthropic	ANTHROPIC_API_KEY	claude-3.7-sonnet

Just flip PUSHSCRIPT_LLM_PROVIDER and add the key—PushScript picks the model automatically.

4.2 · Configuration files (advanced)

PushScript supports custom configuration files to override defaults. Create one of these files in your project root:

Supported formats (priority order):

• .pushscript.json
• .pushscript.yml
• .pushscript.yaml
• package.json (in pushscript field)

Example .pushscript.json:

{
  "commit_style": "As a fintech expert, create concise commit messages focusing on business impact and technical precision.",
  "patterns": [
    {
      "path": "api/**",
      "scope": "api",
      "type_hint": "feat"
    },
    {
      "path": "frontend/**", 
      "scope": "ui",
      "type_hint": "feat"
    }
  ],
  "validation": {
    "max_length": 72,
    "require_conventional": true,
    "allowed_types": ["feat", "fix", "docs", "refactor", "perf", "test", "chore", "hotfix"]
  }
}

Example package.json field:

{
  "name": "my-app",
  "pushscript": {
    "commit_style": "Custom AI prompt...",
    "validation": {
      "max_length": 100
    }
  }
}

Features:

• 🔍 Hierarchical search - Searches up directory tree to find config
• 🧩 Smart merging - Partial configs merge with sensible defaults
• 🎯 Pattern-based - Different rules for different file paths
• ⚡ Hot reload - Changes take effect immediately

---

5 · CLI reference

Run pushscript --help or npx pushscript --help to see all flags.

Use‑case	Command
Generate & push with AI message	pushscript
Custom message, same branch	pushscript "fix: edge case"
Commit only	pushscript commit
Push to main	pushscript --main
Push to a branch name	pushscript "feat: ui" dev
Add npm scripts to project	pushscript setup
Dry‑run (no network)	pushscript --dry

Environment variables summary:

Variable	Meaning
PUSHSCRIPT_LLM_PROVIDER	gemini (default), openai, groq, anthropic
PUSHSCRIPT_LLM_MODEL	Model to use (required for most providers)
PUSHSCRIPT_JSON_SIZE_LIMIT	Max bytes before JSON blocked
PUSHSCRIPT_AUTO_GITIGNORE_JSON	true auto‑ignores large JSON
PUSHSCRIPT_SELF_HEAL	true installs missing deps on first run

---

6 · Advanced features

JSON file exclusion

• Flags any staged `*.json` larger than limit (default 250 kB). • Pattern‑based ignore for filenames containing `debug`. • Auto‑adds to `.gitignore` when `PUSHSCRIPT_AUTO_GITIGNORE_JSON=true`.

Self‑healing mode

If you skip `npm install`, set `PUSHSCRIPT_SELF_HEAL=true`. The wrapper will install `dotenv`, `node-fetch`, and optional AI SDKs using pnpm → npm → yarn fallback.

---

7 · Troubleshooting

Symptom	Fix
MODEL_NOT_FOUND	Run node src/utils/check-models.js to list models for your API key.
Missing module error	npm install or PUSHSCRIPT_SELF_HEAL=true.
Cannot find module auto-package.js	Update: npm update -g pushscript / pnpm update -g pushscript OR reinstall: npm install -g pushscript@latest / pnpm add -g pushscript@latest
Network timeout	Check VPN/firewall; PushScript needs outbound HTTPS.

---

8 · Roadmap

• v0.2 – Enhanced JS/TS CLI with bug fixes (current)
• v0.3 – Python dependency scan
• v0.4 – GitHub App with org dashboard
• v0.5 – VS Code extension Star ⭐ the repo to follow releases.

---

9 · Contributing

Good first issues are tagged good first issue. Follow Conventional Commits (feat:, fix:…) and keep CI green. Full details in CONTRIBUTING.md.

---

10 · License & trademark

MIT License © 2025 PushScript Team. PushScript™ and the logo are trademarks; forks must supply their own branding.