gjalla

Gjalla CLI

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

Installation

pip install gjalla

Requires Python >= 3.10.

Commands

Command	Description
auth login	Browser-backed sign in — saves a user-scoped API key locally
setup	Set up gjalla in a repository (interactive wizard, or use subcommands)
log	Semantic change history — what primitives changed, when, and by whom
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)
skills	View project skills (list, filter by category/persona, show detail)
sync	Upload pending attestations and refresh local cache
project	Manage gjalla projects

User Guide

Getting Started

gjalla auth login       # browser-backed sign in (one command)
gjalla setup            # link a project + install hooks + MCP server

auth login opens your browser to approve the request. Once approved, a user-scoped API key is saved locally and works for every project your account can access.

setup launches the interactive wizard:

• Check git repository
• Verify API key (or prompt to run auth login)
• Select or create a project
• Create .gjalla/ project config
• Install commit attestation guardrails
• Install MCP server for Claude Code

Non-interactive subcommands:

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

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

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:

git add <files>
gjalla attest            # interactive mode
git commit -m "message"

Programmatic (for agents/scripts):

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" \
  --provenance '{"type": "spec", "ref": "docs/specs/rate-limiting.md"}' \
  --rules '{"checked": true, "applicable": [...]}' \
  --arch-changes '{"architecture": {"elements": [{"name": "web-api", "change": "modified", ...}], ...}}'

Print attestation template:

gjalla attest --example

Refreshing Cache

gjalla sync

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

Checking Status

gjalla status

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

Viewing Skills

gjalla skills show                        # List all enabled skills
gjalla skills show --category context     # Filter by category
gjalla skills show --persona code-reviewer # Filter by persona
gjalla skills show analyze-before-coding  # Show full skill content

Configuration

Global config: ~/.gjalla/config.yaml

api_key: "your-api-key"
telemetry: true  # opt-in CLI usage analytics

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

Environment variables:

• GJALLA_API_KEY — overrides config file API key
• GJALLA_TELEMETRY — 1/0 to override telemetry consent
• SKIP_ATTESTATION — 1 to skip attestation for a commit
• GJALLA_NO_VERIFY — 1 to skip field validation (hash check still runs)

Data Collection

Gjalla collects commit attestations and allowlisted agent session telemetry. Memories are never harvested: users and agents add them explicitly through Gjalla's CLI or MCP. All collection is transparent and documented here.

1. Commit Attestations

When: Every git commit (via pre-commit validation + post-commit processing).

What's collected:

Field	Source	Required?
staged_diff_hash	SHA-256 of staged diff	Yes (user computes)
agent	Agent name (e.g., "claude-code")	Yes
agent_provider	Provider (e.g., "anthropic")	Yes
agent_model	Model ID (e.g., "claude-opus-4-6")	Yes
summary	Impact description of the change	Yes
provenance	What prompted this: {type: "spec|ticket|bug-fix|ad-hoc", ref: "..."}	Yes
rules	Rule compliance report: {checked: true, applicable: [...]}	Yes
changes	Architecture changes across 8 primitives (see below)	Yes
timestamp	ISO 8601 timestamp	Auto-generated
developer	{git_author_name, git_author_email} from git config	Auto-detected
agent_session_id	Session/conversation UUID	Auto-detected from agent runtime
telemetry	Session metrics (see section 2)	Auto-extracted

8 architecture primitives tracked in changes: architecture, data_model, data_flows, rules, capabilities, surface_area, external_services, tech_stack. Each is {changed: false} or {changed: true, details: [...]}.

Where stored locally:

• .gjalla/.commit-attestation.yaml — pending attestation (ephemeral, deleted after commit)
• .gjalla/attestations/<commit-hash>.yaml — archived attestation (permanent)
• .gjalla/log.jsonl — one JSON entry per commit with all fields above

Where uploaded: POST /api/agent/projects/{id}/attestations during gjalla sync.

2. Agent Session Telemetry

When: Auto-extracted at commit time from the active agent's local session files.

What's collected:

Field	Claude Code	Gemini CLI	Codex CLI	OpenCode	Aider
Token counts (in/out/cache)	Yes	Yes (OTel)	No	Best-effort	No
Duration (seconds)	Yes	Yes	Yes	Best-effort	No
Model name	Yes	Yes	Yes	Best-effort	Partial
Tool call count	Yes	Yes	No	Best-effort	No
Tool names + categories	Yes	Yes (OTel spans)	Best-effort	Best-effort	Best-effort

Tool categories: builtin (Read, Edit, Bash), mcp (mcp__gjalla__*), skill (Skill tool), agent (Agent tool).

Security: The Claude Code adapter reads session JSONL files with a strict field allowlist (type, message, timestamp, sessionId, durationMs). It never reads message content, tool arguments, tool results, or any user-authored text. Tool names (e.g., "Read", "mcp__gjalla__get_context") are metadata, not content.

Where stored: Embedded in the attestation's telemetry field → same local + upload path as attestations.

3. Gjalla Memory

Gjalla memory is explicit. Agents and users create or update memories with gjalla memory add (or the compatible memory save spelling) or the save_memory MCP tool and recall them with gjalla memory show or get_memories.

Personal memory stays local. Hosted team, system, and project memory uses explicit --scope / MCP scope arguments. Anyone with access to a hosted scope can read and contribute; owners/admins can archive and restore with gjalla memory archive|restore or the matching MCP tools.

gjalla sync downloads hosted memory into Gjalla's own cache for offline recall. It does not scan, import, modify, or delete Claude Code, OpenCode, Codex, Gemini, Cursor, or other provider-native memory. It also does not embed memory bodies in provider guidance files.

Where stored locally:

• Personal: ~/.gjalla/user/memory/*.md
• Connected project cache: .gjalla/.platform/memories.json

Provider-native memory remains owned entirely by the provider and user.

4. CLI Usage Analytics (opt-in)

When: On each CLI command execution, if the user has opted in.

What's collected: Command name, CLI version, OS, Python version, install ID (persistent UUID), whether a project is linked. Never collects: code, project data, file contents, credentials.

Consent: Prompted on first run. Stored in ~/.gjalla/config.yaml as telemetry: true|false. Override with GJALLA_TELEMETRY=0.

Where sent: POST /api/cli/telemetry (fire-and-forget, 2s timeout). Error tracking via Sentry (same consent gate, 10% sample rate, sensitive keys scrubbed).

Local Storage Structure

.gjalla/                              # Project root (gitignored)
├── config.yaml                       # Project config (project_id, api_key)
├── .commit-attestation.yaml          # Pending attestation (ephemeral)
├── example-attestation.yaml          # Template for agents
├── log.jsonl                         # Cumulative attestation log
├── attestations/                     # Archived attestation YAMLs
│   └── <commit-hash>.yaml
└── cache/                            # Pulled from platform by `gjalla sync`
    ├── gjallastate.yaml              # Architecture, capabilities, data model
    ├── gjallarules.yaml              # Rules, principles, ADRs, checks
    ├── gjallamap.yaml                # Element-to-file mappings
    ├── architecture.txt              # Rich-formatted architecture overview
    ├── rules.md                      # Markdown-formatted rules
    ├── state.json                    # Full project state (JSON)
    ├── context.md                    # Agent guidance from platform
    ├── skills/                       # Available project skills (one .md per skill)
    │   └── <slug>.md
    ├── memories.json                 # Merged memories from all agents
    ├── system-context.md             # Cross-project context
    ├── system-mappings.yaml          # Cross-project element mappings
    └── specs/                        # Domain behavioral specs
        └── <domain>/spec.md

~/.gjalla/                            # Global config
└── config.yaml                       # API key, telemetry consent, install ID

Questions or feedback: [e-mail]