Everything you need to use zap, from setup to advanced configuration.
Get started — npm install -g zap-git
Setup wizard
Interactive first-time setup. Creates a git repo if needed, sets your identity, configures your git remote (add or update URL), generates .gitignore from your project stack, and connects to your dashboard.
Usage
Example
$ zap init
◆ Setting up your project...
✓ Initialized empty Git repo
✓ Identity set — Alex
✓ .gitignore generated (12 entries)
✓ Dashboard linked
→ Ready in 1.2s
Note: zap init is interactive. It will prompt you for any information it needs. Re-run anytime to reconnect a different dashboard or update your remote URL.
Push
The default command. Stages all changes, generates a commit message, and pushes to the current branch. If the project hasn't been initialized yet, runs the setup wizard first.
Usage
Example
$ zap
◆ Pushing to feat/login
✓ Staged 3 files
✓ Committed as a3f91c2
✓ Pushed to origin/feat/login
→ Done in 1.8s
Options
--aiGenerate commit message with AI
--dry-runSimulate the full flow without making changes
--checkForce pre-push checks (lint/test/build)
--skip-checkSkip pre-push checks for this push
--undoUndo the last commit (soft reset)
AI commit messages
Analyzes your repo context — file tree, changed files, README — and writes an accurate Conventional Commit with AI. Accept, edit, or regenerate the suggestion.
Note: AI commit messages require an API key. Set your key in the environment or run zap init to configure.
Undo last commit
Soft-resets your last commit (git reset --soft HEAD~1) while keeping your changes staged. Safe, instant, no force push needed.
Usage
Example
$ zap --undo
◇ Resetting HEAD~1
✓ Commit undone — changes are staged
→ HEAD is now at a3f91c2
→ Run zap to recommit
Configuration
View or update your local CLI configuration — pre-push check behavior, AI defaults, main branch warnings, and more.
Usage
Example
$ zap config --show
initialized yes
check mode ask
ai default off
warn on main on
default branch main
dashboard connected
AI key configured
Options
--showShow all current configuration
--check <mode>Set pre-push check behavior: always | never | ask
--ai <state>Set default AI mode: on | off
--warn-main <state>Main branch warning: on | off
--resetReset all configuration to defaults
Push history
View recent push history across your repos. Shows time, branch, commit message, and hash. If connected to a dashboard, fetches from the cloud; otherwise reads from local cache.
Usage
Example
$ zap log -n 5
TIME BRANCH MESSAGE HASH
2m ago feat/login feat(auth): add OTP verificati… a3f91c2
1h ago main fix: header alignment on mobile b8e2d1f
3h ago feat/login chore: update deps e7c3a9b
1d ago main docs: update README f1d4e5c
2d ago main feat: add dark mode toggle 9a2b3c4
Options
-n, --limit <number>Number of entries to show (default: 20)
Smart .gitignore
Auto-detects your project stack — Node, Next.js, React, Python, Django, Go, Rust, and more — and generates the right .gitignore. Generated automatically during zap init.
