npm package: @gitconductor/cli
Description: CLI for gitconductor — intercept git commands, enforce safety rules, and recover from mistakes
Author: gitconductor contributors
Latest version: 0.1.5

# @gitconductor/cli

> Prevent git mistakes before they happen — rules, education, and recovery guidance.

gitconductor intercepts your `git` commands and enforces safety rules — blocking force-pushes to protected branches, detecting committed secrets, warning about direct commits to `main`, and more. Works entirely offline; AI is optional.

## Install

```bash
npm install -g @gitconductor/cli
```

Then set up the shell alias (intercepts all `git` commands):

```bash
gitconductor install --global
source ~/.zshrc   # or ~/.bashrc for bash, or open a new terminal
```

Or set up for a single repo only (no shell alias):

```bash
gitconductor install
```

## Requirements

- Node.js ≥ 18
- bash, zsh, or fish shell (macOS, Linux, or Windows via Git Bash / WSL)

## Commands

| Command | Description |
|---|---|
| `gitconductor install [--global]` | Set up for this repo, or globally with the shell alias |
| `gitconductor status` | Show active config and all rules |
| `gitconductor check` | Proactive workspace health scan |
| `gitconductor rescue [scenario]` | Step-by-step recovery from common git mistakes |
| `gitconductor explain <rule>` | Deep docs for a rule: why it exists, how to recover |
| `gitconductor log [--limit N]` | Recent interception history |
| `gitconductor ask "<question>"` | AI-powered git Q&A (requires AI provider) |
| `gitconductor config set <key> <value>` | Change a config value |
| `gitconductor config show` | Print merged config as YAML |
| `gitconductor uninstall [--global]` | Remove gitconductor |

## 13 Built-in Rules

| Rule | Default | Severity |
|---|---|---|
| `forcePushProtectedBranch` | on | block |
| `secretDetection` | on | block |
| `wipCommit` | on | block |
| `directCommitToProtectedBranch` | on | warn |
| `hardResetWithChanges` | on | warn |
| `largePush` | on | warn |
| `rebaseSharedBranch` | on | warn |
| `deleteBranchWithOpenPR` | on | warn |
| `mergeIntoProtectedBranch` | on | warn |
| `tagDeletion` | on | warn |
| `stashDrop` | on | warn |
| `amendPublishedCommit` | on | warn |
| `commitMessageFormat` | **off** | warn |

## Configuration

gitconductor merges config from three sources (in order):

1. Built-in defaults
2. `~/.gitconductor/config.yml` (global)
3. `.gitconductor.yml` in the repo root

Example `.gitconductor.yml`:

```yaml
protectedBranches:
  - main
  - master
  - release/*

rules:
  commitMessageFormat:
    enabled: true
    severity: warn

ai:
  provider: anthropic
  model: claude-opus-4-6
```

Set config from the CLI:

```bash
gitconductor config set rules.commitMessageFormat.enabled true
gitconductor config set ai.provider anthropic --global
gitconductor config unset ai.apiKey --global
```

## AI Providers (optional)

gitconductor works fully without AI. Configure one for richer analysis:

```bash
# Anthropic
gitconductor config set ai.provider anthropic --global
export GITCONDUCTOR_AI_KEY=sk-ant-...

# OpenAI
gitconductor config set ai.provider openai --global
export GITCONDUCTOR_AI_KEY=sk-...

# Ollama (local, no API key needed)
gitconductor config set ai.provider ollama --global
gitconductor config set ai.model llama3 --global
```

## Disable Temporarily

```bash
gitconductor config set enabled false
# ... do your thing ...
gitconductor config set enabled true
```

## Links

- [Documentation](https://gitconductor.dev)
- [GitHub](https://github.com/itsshirazhere/gitconductor)
- [Changelog](https://github.com/itsshirazhere/gitconductor/blob/main/CHANGELOG.md)
- [`@gitconductor/core`](https://www.npmjs.com/package/@gitconductor/core) — rule engine (for building custom integrations)

## License

MIT