Metadata-Version: 2.4
Name: gjalla
Version: 0.5.3
Summary: gjalla CLI — visibility and control for your software architecture.
License: Proprietary
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: License :: Other/Proprietary License
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Requires-Dist: gitpython>=3.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: pydantic>=2.0
Requires-Dist: httpx>=0.25
Requires-Dist: packaging>=21.0
Requires-Dist: pathspec>=0.11
Requires-Dist: sentry-sdk>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: vulture>=2.11; extra == "dev"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Provides-Extra: monitor
Requires-Dist: watchdog>=3.0; extra == "monitor"
Dynamic: license-file

<!-- mcp-name: io.gjalla/mcp-server -->
# Gjalla CLI

Visibility and control for your software architecture. Agentic engineering made magical.

## Installation

```bash
pip install gjalla
```

Requires Python >= 3.10.

## Commands

| Command | Description |
|---------|-------------|
| `setup` | Set up gjalla in a repository (interactive wizard, or use subcommands) |
| `status` | Show configuration status |
| `state` | Navigate project state (architecture, tech stack, capabilities, etc.) |
| `rules` | View and manage project rules, principles, ADRs, and invariants |
| `attest` | Create commit attestation (interactive or programmatic) |
| `check` | Validate commit attestation (used by pre-commit hook) |
| `sync` | Upload pending attestations and refresh local cache |
| `project` | Manage gjalla projects |

---

## User Guide

### Initial Setup

```bash
gjalla setup
```

Launches the interactive wizard:
1. Check git repository
2. Configure API key
3. Verify API key
4. Select project
5. Create `.gjalla/` project config
6. Install commit attestation guardrails
7. Install MCP server for Claude Code

**Non-interactive subcommands:**

```bash
gjalla setup auth <api-key>         # Save and verify an API key
gjalla setup project <pid>          # Link this repo to a project
gjalla setup project --check-access # List accessible projects
gjalla setup hooks                  # Install git hooks
gjalla setup mcp                    # Install MCP server entry
```

### Viewing Project State

```bash
gjalla state show                                # List top-level keys with entry counts
gjalla state show -c architecture                # Full architecture section
gjalla state show -c architecture -v             # Architecture + file evidence
gjalla state show -e architecture.api-server     # Drill into a single element
gjalla state show -e architecture.api-server -v  # Element + file evidence
gjalla state show -c tech_stack                  # Tech stack, frameworks, vendors
gjalla state show -c capabilities                # Project capabilities and status
gjalla state show -c data_model                  # Data entities, domains, attributes
gjalla state show -c services                    # External services and integrations
gjalla state show -c surface_area                # API endpoints and auth requirements
gjalla state show --system                       # Cross-project system context
```

### Viewing Project Rules

```bash
gjalla rules show                # List rule categories with counts
gjalla rules show -c adr         # Show only ADRs
gjalla rules show -c principle   # Show only principles
gjalla rules show -c invariant   # Show only invariants
gjalla rules add -n "No ORM" -d "Use raw SQL queries"  # Add a rule
```

### Daily Usage

**Automatic (via pre-commit hook):**
- `gjalla check` runs on each `git commit` and validates the attestation

**Manual / Agent workflow:**
```bash
git add <files>
gjalla attest            # interactive mode
git commit -m "message"
```

**Programmatic (for agents/scripts):**
```bash
gjalla attest \
  --staged-diff-hash $(git diff --staged | shasum -a 256 | cut -d' ' -f1) \
  --agent claude-code --provider anthropic --model claude-opus-4-6 \
  --summary "Added rate limiting to auth endpoints" \
  --rules '{"checked": true, "applicable": [...]}' \
  --arch-changes '{"architecture": {"elements": [{"name": "web-api", "change": "modified", ...}], ...}}'
```

**Print attestation template:**
```bash
gjalla attest --example
```

### Refreshing Cache

```bash
gjalla sync
```

Uploads pending attestations and refreshes the local cache from the remote server.

### Checking Status

```bash
gjalla status
```

Shows: git repo, global config, API key, project mapping, project config, guardrails, telemetry, attestation log.

### Configuration

**Global config:** `~/.gjalla/config.yaml`
```yaml
api_key: "your-api-key"
```

**Project config:** `.gjalla/config.yaml` (in repo root)

**Environment variables:**
- `GJALLA_API_KEY` — overrides config file API key

---

Questions or feedback: hello@gjalla.io
