gjalla 0.4.27
Gjalla CLI — architecture guardrails for AI coding agents
License: MIT
Requires Python: >=3.10

# Gjalla Pre-commit CLI

Pre-commit analysis CLI for validating changes against team rules.

## Installation

```bash
pip install -e .
```

## Commands

| Command | Description |
|---------|-------------|
| `init` | Initialize gjalla in a repository |
| `commit` | Analyze staged changes before commit |
| `bypass` | Bypass analysis for a commit |
| `status` | Show current status |
| `hook` | Manage git hooks (install/uninstall) |
| `caps` | Show available capabilities |
| `sync` | Sync configuration |
| `auth` | Authentication management |
| `impact` | Show impact analysis |
| `mcp` | MCP server mode |

---

## User Guide

### Initial Setup

1. **Configure API key:**
   ```bash
   gjalla init
   ```
   - Prompts for API key (or set `GJALLA_API_KEY` env var)
   - Discovers available projects from API
   - Links current repository to a project

2. **Install pre-commit hook (optional):**
   ```bash
   gjalla hook install
   ```

### Daily Usage

**Automatic (via pre-commit hook):**
- Hook runs `gjalla commit` automatically on each `git commit`
- Blocks commit if violations are found

**Manual:**
```bash
git add <files>
gjalla commit
git commit -m "message"
```

### Analysis Flow

When `gjalla commit` runs:
1. Opens WebSocket connection to analysis service
2. Sends staged changes for analysis
3. Executes tool calls from the service (file reads, searches)
4. Displays results: violations, warnings, suggestions
5. Stores analysis receipt on successful analysis

### Reading Output

- **Violations** (red): Must fix before commit proceeds
- **Warnings** (yellow): Should review, won't block commit
- **Suggestions** (blue): Optional improvements
- **Receipt**: Analysis ID stored for audit trail

### Bypassing Analysis

When you need to skip analysis:
```bash
gjalla bypass -m "reason for bypass"
git commit -m "message"
```
Logs bypass with timestamp and reason.

### Checking Status

```bash
gjalla status
```
Shows: project linkage, hook status, last analysis receipt.

### Hook Management

```bash
gjalla hook install    # Install pre-commit hook
gjalla hook uninstall  # Remove pre-commit hook
gjalla hook status     # Check hook installation
```

### Configuration

**Global config:** `~/.gjalla/config.yaml`
```yaml
api_key: "your-api-key"
api_url: "https://api.gjalla.io"
projects:
  /path/to/repo: "project-id"
```

**Project config:** `.gjalla.yaml` (in repo root)
- Project-specific rules and settings

**Environment variables:**
- `GJALLA_API_KEY` - Overrides config file api_key
- `GJALLA_API_URL` - Overrides config file api_url

---

## Development Guide

### Setup

```bash
git clone <repo-url>
cd gjalla-precommit
python3 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
pre-commit install  # Install hooks after cloning
```

### Running Tests

```bash
python3 -m pytest tests/ -v
```

### Project Structure

```
gjalla_precommit/
  cli.py              # Entry point, command group
  commands/           # CLI command implementations
    init.py           # gjalla init
    commit.py         # gjalla commit
    bypass.py         # gjalla bypass
    status.py         # gjalla status
    hook.py           # gjalla hook install/uninstall
    caps.py           # gjalla caps
    sync.py           # gjalla sync
    impact.py         # gjalla impact
    mcp.py            # gjalla mcp
  config/             # Configuration management
    settings.py       # Settings loading, config paths
  protocol/           # WebSocket protocol handling
  display/            # Terminal output formatting (rich)
  tools/              # Tool implementations for analysis
tests/                # Test suite
```

### Dependencies

- `click` - CLI framework
- `rich` - Terminal formatting
- `websockets` - WebSocket client
- `gitpython` - Git operations
- `pyyaml` - Config file parsing
- `pydantic` - Settings validation
- `httpx` - HTTP client
- `pathspec` - Gitignore-style pattern matching

### Dev Dependencies

- `pytest` - Test runner
- `pytest-asyncio` - Async test support