zap ⚡

Push code. Just type zap.

Replace git add + git commit + git push with a single command. Track everything on your dashboard at zap-cli-web.vercel.app.

Quick start

1. Create a dashboard account

Go to zap-cli-web.vercel.app → Get started → create an account. Navigate to Settings → API Keys and generate a new key.

2. Install

npm install -g zap-git
cd your-project
zap init

When prompted, paste your dashboard URL and API key from step 1.

3. Push

zap          # stage, commit (with a suggested message), and push

  ◆  zap  —  3 files changed on feat/login

  M  src/auth/Login.jsx
  A  src/auth/OTP.jsx
  D  src/auth/old.jsx

  ○  Commit message
  │  feat(auth): add OTP verification to login

  ◇  Pushing to feat/login...

  ✓  Done in 1.2s
     → commit a3f91c2
     → github.com/yourname/repo/commit/a3f91c2

Commands

zap

The default flow:

1. Verifies you're in a git repo with uncommitted changes.
2. Lists changed files (M/A/D/R).
3. Warns before pushing to main/master (configurable).
4. Suggests a commit message (or uses --ai).
5. Stages everything, commits, and pushes.
6. Prints commit hash, duration, and GitHub link.
7. Logs the push locally and to your dashboard.

zap --ai

Same flow, but the commit message is generated by Groq AI from your git diff. You can accept, edit, or regenerate. Falls back to file-name suggestion if AI is unavailable.

zap --undo

git reset --soft HEAD~1 — undoes the last commit, keeps changes staged.

zap --dry-run

Simulates the full flow without staging, committing, or pushing. Every line is prefixed with [DRY RUN].

zap --check / --skip-check

Runs lint/test/build before staging. Stops at the first failure.

zap log

Shows your last 20 pushes. Fetches from dashboard if connected, otherwise reads local log.

2h ago   feat/login    feat(auth): add OTP verification    a3f91c2
1d ago   main          chore: update dependencies          b8e22d1
3d ago   fix/navbar    fix(nav): broken link on mobile     c91a3f4

zap init

First-time setup: git identity, remote (add or update URL), .gitignore, dashboard connection, AI toggle.

zap config

zap config --show                   # show all current config
zap config --check always|never|ask # pre-push check behavior
zap config --ai on|off              # default AI mode
zap config --warn-main on|off       # main branch warning
zap config --reset                  # reset all config

.gitignore generation

Detects your project type — Node, Next.js, React, Python, Django, Laravel, Go, Rust, Java — and writes a merged .gitignore from bundled templates.

Environment variables

ZAP_API_KEY=          # dashboard API key (set by zap init)
ZAP_SUPABASE_URL=     # dashboard URL (set by zap init)
GROQ_API_KEY=         # self-hosted AI key (optional — falls back to dashboard)

Environment variables always take precedence over stored config.

Error handling

✗  Not a git repository
   Run git init first, then zap init to connect.

✗  Nothing to commit
   No changes detected in this directory.

✗  No remote configured
   Run: git remote add origin https://github.com/you/repo.git

✗  Push rejected (remote has changes)
   Pull first: git pull origin feat/login

✗  AI commit failed (API error)
   Falling back to manual message prompt.

✗  lint check failed
   Fix errors or run: zap --skip-check to push anyway.

Reliability

• Every git operation is wrapped with human-readable errors.
• Dashboard sync and AI calls are non-blocking with short timeouts — if unreachable, zap still completes the push.
• All core features (push, undo, log, config, dry-run, checks, .gitignore generation) work fully offline.

Development

cd packages/cli
npm install
npm run build   # compile TypeScript -> dist/
npm test        # run the unit + integration test suite
npm link        # try the `zap` command locally