git-pls / git-please

A CLI tool that translates natural language requests into Git commands, powered by AI (OpenAI, Anthropic Claude, or Google Gemini).

Installation

npm install -g git-pls

Usage

git-pls and git-please are identical aliases — use whichever you prefer.

git-pls "save all changes and push"

git-please "undo my last commit but keep the files"

git-pls "create a branch called feature/auth"

git-pls "rebase this branch onto main"

git-pls "why is my branch not merging"

git-pls "prepare this branch for a PR"

Example workflow

$ git-pls "save all changes and push"

Analyzing repository...
✓ Analyzed

Repository: my-project
Branch: feature/auth

Generating Git plan...
✓ Generated

Commands:

1. git add .
2. git commit -m "Update files"
3. git push

Risk: LOW

Explanation:
Adds all modified files, creates a commit, and pushes to the remote.

Run? [Y/n]

Commands

| Command | Description | |---------|-------------| | git-pls <request> | Translate a natural language request to Git commands | | git-pls <request> --dry-run | Generate commands without executing | | git-pls explain <topic> | Explain a Git concept | | git-pls config show | Show current configuration | | git-pls config set-provider <name> | Set AI provider (openai, anthropic, gemini) | | git-pls config set-openai-key | Configure OpenAI API key | | git-pls config set-anthropic-key | Configure Anthropic API key | | git-pls config set-gemini-key | Configure Gemini API key |

Configuration

Setting up an API key

You can configure keys interactively:

git-pls config set-openai-key
git-pls config set-anthropic-key
git-pls config set-gemini-key

Keys can also be set via environment variables:

export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export GEMINI_API_KEY=...

Environment variables override stored configuration.

Selecting a provider

git-pls config set-provider openai
git-pls config set-provider anthropic
git-pls config set-provider gemini

Default provider is openai.

Viewing configuration

git-pls config show

Output:

Configuration:
  Provider: openai
  OpenAI API Key: configured
  Anthropic API Key: not configured
  Gemini API Key: configured

Explain mode

Explain Git concepts without executing commands:

git-pls explain "git rebase"
git-pls explain "git merge vs git rebase"
git-pls explain "detached HEAD state"

Dry run mode

Generate commands but never execute them:

git-pls --dry-run "save my changes"
git-pls --dry-run "undo my last commit"

How it works

1. Context collection — the tool inspects your repository: current branch, status, remotes, recent commits, and diff stats
2. AI generation — sends the context + your request to the configured LLM provider
3. Validation — parses and validates the JSON response with Zod
4. Security check — rejects any commands that don't start with git or contain shell operators
5. Danger detection — flags destructive commands (reset --hard, clean -fd, push --force, etc.)
6. Confirmation — shows the commands and risk level, asks for confirmation
7. Execution — runs commands sequentially via execa, stops on first failure

Security model

The AI is never trusted. Every generated command is validated before execution:

• Commands must start with git
• Shell operators (&&, ;, |, >, <, $(), backticks) are rejected
• Non-git executables (rm, curl, wget, node, python, bash, etc.) are rejected
• JSON responses are validated with Zod schemas
• Malformed responses trigger automatic retries (up to 3 attempts)

Dangerous commands

Commands that can cause data loss require explicit confirmation. The user must type DELETE to proceed:

• git reset --hard
• git clean -fd / git clean -fdx
• git push --force / git push --force-with-lease
• git branch -D
• git checkout -- .
• git restore

Architecture

src/
├── cli.ts                      # Entry point
├── commands/
│   ├── main.ts                 # Main command flow
│   ├── config.ts               # Configuration commands
│   ├── explain.ts              # Explain mode
│   └── dryrun.ts               # Dry run mode
├── providers/
│   ├── provider.ts             # Provider factory + system prompt builder
│   ├── openai.ts               # OpenAI provider
│   ├── anthropic.ts            # Anthropic Claude provider
│   └── gemini.ts               # Google Gemini provider
├── git/
│   ├── context.ts              # Git repository context collection
│   ├── execute.ts              # Command execution
│   ├── validator.ts            # Security command validation
│   └── danger.ts               # Dangerous command detection
├── config/
│   ├── store.ts                # Configuration persistence
│   └── schema.ts               # Zod config schema
├── validation/
│   └── gitplan.ts              # GitPlan response validation
├── utils/
│   ├── logger.ts               # Colored logging
│   ├── prompt.ts               # User prompts
│   ├── spinner.ts              # Loading spinners
│   └── repair.ts               # JSON repair utilities
└── types/
    └── index.ts                # Shared TypeScript types

Extending with new providers

Implement the AIProvider interface:

interface AIProvider {
  generate(request: string, gitContext: GitContext): Promise<GitPlan>;
}

Register the provider in src/providers/provider.ts.

Development

# Install dependencies
npm install

# Build
npm run build

# Test
npm test

# Watch mode
npm run dev

# Lint
npm run lint

# Format
npm run format

Requirements

• Node.js >= 18
• A Git repository (for command generation)
• API key for at least one AI provider

Publishing

npm run build
npm publish

License

MIT