Gjalla CLI

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

Installation

pip install gjalla

Requires Python >= 3.10.

Commands

User Guide

Getting Started

gjalla auth login       # email and code sign in (one command)
gjalla setup            # link a project + install hooks + MCP server

auth login asks for your email, sends a 6-digit code, and verifies it, with no browser and no password. Once verified, a user-scoped API key is saved locally and works for every project your account can access.

setup launches the interactive wizard:

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

Working in an ephemeral cloud container (Claude Code on the web, a Codespace, CI)? See Cloud and container setup — a clone carries the committed harness, but the API key, git hooks, and synced context each need their own answer.

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 ensure --agent <a>     # Heal an agent's wiring (never installs the plugin)
gjalla setup doctor                 # Each agent's delivery and every piece's state

gjalla setup is the one installer and is safe to re-run: for Claude Code it installs the gjalla plugin, for every other agent it writes the instruction block, hook rows and MCP entry, and a second run changes nothing. The old gjalla setup hooks, gjalla setup mcp and gjalla mcp install still work for one release; each runs gjalla setup.

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"}' \
  --task-type feature \
  --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, a record of commits that carried no attestation, 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:

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.

1b. Commits With No Attestation

When: Every git commit that produces no attestation. Two ways that happens: the gate ran and you waived it (SKIP_ATTESTATION=1), or the gate never ran because this repo has no .gjalla/.platform/config.yaml — which is the case in a fresh clone or a cloud container that has not run gjalla sync yet.

Capture is deliberately decoupled from the gate. Whatever policy the gate takes, the commit and the agent session behind it are recorded, so adopting gjalla in a container does not mean losing everything that happened there.

What's collected: the environmental half of an attestation and nothing else — commit, branch, timestamp, agent, agent_provider, agent_session_id, developer, and telemetry (section 2). There is no summary, no changes, no rules block: those are things an agent asserts, and by definition nothing was asserted here.

How to see them: gjalla status counts them on the Attestation Log row, reported as skipped (you waived it) or unattested (the gate never ran) — separately, because they are different facts.

Where stored: .gjalla/.platform/log.jsonl, as an entry carrying event: attestation_skipped or event: commit_unattested.

Where uploaded: the same project-addressed endpoint as attestations. A repo with no linked project cannot upload them; they stay local and gjalla status says so.

To turn it off: gjalla setup remove (removes gjalla's hooks entirely), or delete just the post-commit hook from your hooks directory. There is no separate opt-out, because this is the same collection the attestation path already performs — it just no longer requires an attestation to exist first.

2. Agent Session Telemetry

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

What's collected:

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

Security: This adapter (the attestation-time telemetry above, not gjalla scan below) 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.

2b. gjalla scan

gjalla scan discovers local Claude Code / Codex CLI session transcripts from the last N days and uploads them for the Observe dashboard (sessions, tokens, cost, where time goes).

Sign-in: if there's no API key yet, scan runs the same email+code login as gjalla auth login inline first, enter your email, then the 6-digit code sent to it. No browser, no password.

Uploads are gzip-compressed. On success, scan prints a one-time dashboard link.

Live sessions: with the gjalla plugin installed, the agent's hooks upload the same data as each turn ends. For a Claude Code session the hook also sends the signed-in Claude account's email and account ID (metadata.identity, from Claude Code's environment) so the dashboard can attribute the session to a person.

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: hello@gjalla.io