CLI Reference

zil init <name> [options]

# Interactive mode (prompts for LLM provider)
zil init my-agent
 
# Non-interactive with defaults
zil init my-agent --non-interactive
 
# Specify LLM provider directly
zil init my-agent --llm vertex

zil validate [options]

# Validate current directory
zil validate
 
# Validate a specific directory
zil validate --project-dir ./my-agent
 
# JSON output for CI/CD pipelines
zil validate --format=json

{
  "valid": true,
  "exit_code": 0,
  "errors": 0,
  "warnings": 0,
  "checks": [
    { "status": "pass", "message": "manifest.yaml — schema valid" },
    { "status": "pass", "message": "identity/persona.md — present" }
  ]
}

zil audit [options]

# Audit the current project
zil audit
 
# Audit a specific project
zil audit --project-dir ./my-agent
 
# Show fix suggestions
zil audit --fix
 
# JSON output for CI/CD
zil audit --format=json

╭─ Zil Security Audit ─────────────────────────────╮
│ Project: my-agent  v1.0.0                          │
╰───────────────────────────────────────────────────╯

Guardrail Coverage ─────────────────────────────── 4/5
  ✓ Prompt injection detection enabled
  ✓ PII output detection enabled
  · PII input detection disabled (optional)
  ✓ Output constraints: max 4000 chars
  ⚠ Denied topics: none configured

Injection Resilience ──────────────────────────── 19/20
  ✓ Ignore instructions (4/4)
  ✓ DAN jailbreak (3/3)
  ⚠ System prompt extraction (2/3) — 1 bypass
  ✓ Tag injection (4/4)
  ✓ Rule override (3/3)
  ✓ Instruction forget (3/3)

Output Leakage ─────────────────────────────────── PASS
  ✓ System prompt not reproducible in output

Indirect Injection Surface ─────────────────────── WARN
  ⚠ tool: fetch_data() — returns external data (HTTP)
  ✓ tool: calculate() — pure computation

Instruction Consistency ────────────────────────── PASS
  ✓ No contradictions between persona and guardrails

Context Window Risk ────────────────────────────── PASS
  ✓ System prompt: ~500 tokens (0.4% of 128,000 context)

Identity Hardening ─────────────────────────────── PASS
  ✓ Refusal boundaries — present
  ✓ Scope definition — present
  ✓ Response format — present

Summary: 0 critical, 2 warnings

zil pack [options]

my-agent-1.0.0.zil
├── manifest.yaml
├── adapters/
├── identity/
├── evals/
├── observability/
├── {module_name}/
├── BUILD_META.json
├── SBOM.cyclonedx.json
└── EVAL_RESULTS.json (if evals ran)

# Package with all defaults
zil pack
 
# Skip evals during development
zil pack --skip-evals
 
# Custom output directory
zil pack --output-dir ./artifacts
 
# Sign with keyless (Sigstore OIDC)
zil pack --sign
 
# Sign with a private key
zil pack --sign --key cosign.key

zil inspect <archive> [options]

# Summary view
zil inspect dist/my-agent-1.0.0.zil
 
# Show a specific file
zil inspect dist/my-agent-1.0.0.zil --show manifest.yaml
zil inspect dist/my-agent-1.0.0.zil --show identity/persona.md
 
# JSON output for CI/CD
zil inspect dist/my-agent-1.0.0.zil --json
 
# Verify signature (keyless)
zil inspect --verify dist/my-agent-1.0.0.zil
 
# Verify with public key
zil inspect --verify dist/my-agent-1.0.0.zil --key cosign.pub

Zil Package: my-agent
  Version:     1.0.0
  Description: A customer support agent.
  Framework:   adk (python)
  Created:     2026-05-07T22:37:15+00:00
  Size:        0.1 MB

  SBOM:        5 dependencies
  Evals:       96.0% (passed)

               Components
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━┓
┃ Component           ┃ Files ┃   Size ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━┩
│ adapters/           │     2 │  305 B │
│ identity/           │     3 │ 1.4 KB │
│ manifest.yaml       │     1 │  502 B │
│ my_agent/           │     4 │ 1.0 KB │
│ SBOM.cyclonedx.json │     1 │ 1.0 KB │
└─────────────────────┴───────┴────────┘

zil push <archive> --registry <url>

# Push to Google Artifact Registry
zil push dist/my-agent-1.0.0.zil \
  --registry us-docker.pkg.dev/my-project/agents
 
# Push to GHCR
zil push dist/my-agent-1.0.0.zil \
  --registry ghcr.io/my-org/agents

zil eval <subcommand> [options]

# Run baseline eval suite
zil eval run
 
# Verbose with per-case details
zil eval run --verbose
 
# JSON output for CI
zil eval run --json-output
 
# Interactive case builder
zil eval add --group edge-cases
 
# Record a session
zil eval record --auto-accept
 
# Generate cases from identity
zil eval generate --count 20 --category guardrails --no-review

{
  "suite": "baseline",
  "score": 0.92,
  "passed": true,
  "threshold": 0.85,
  "total_cases": 5,
  "passed_cases": 5,
  "failed_cases": 0,
  "groups": [
    {
      "name": "accuracy",
      "pass_rate": 1.0,
      "weight": 0.5,
      "cases": [...]
    }
  ]
}

zil run [options]

# Run from the project directory
zil run
 
# Run from a different directory
zil run --project-dir ./my-agent
 
# Run with tracing to OTLP collector
zil run --trace
 
# Run with console span output (no infra needed)
zil run --trace-console

zil web [options]

# Start on default port
zil web
 
# Custom port
zil web --port 3000
 
# Start with tracing enabled
zil web --trace

# Build image and run container
zil web --docker
 
# With full observability (Grafana OTEL-LGTM stack)
zil web --docker --trace
 
# Custom port
zil web --docker --port 3000

zil deploy [options]

# Deploy with explicit project and region
zil deploy --project my-project --region us-central1
 
# Use env vars instead of flags
export GOOGLE_CLOUD_PROJECT=my-project
export GOOGLE_CLOUD_REGION=us-central1
zil deploy
 
# Deploy with Cloud Trace telemetry
zil deploy --project my-project --region us-central1 --trace
 
# Include the ADK web UI (dev/staging only)
zil deploy --project my-project --region us-central1 --with-ui
 
# Skip evals for a quick re-deploy
zil deploy --project my-project --region us-central1 --skip-evals
 
# Deploy from a local .zil archive
zil deploy --from dist/my-agent-1.0.0.zil \
  --project my-project --region us-central1
 
# Deploy from an OCI registry
zil deploy --from us-docker.pkg.dev/my-project/agents/my-agent:1.0.0 \
  --project my-project --region us-central1

→ Running pre-deploy eval check...
✗ Eval suite failed: 72.0% (threshold: 85.0%). Deploy blocked. Use --skip-evals to override.

zil deploy --project my-project --region us-central1 --skip-evals

# Environment variables
gcloud run services update my-agent \
  --set-env-vars="GOOGLE_API_KEY=your-key" \
  --region=us-central1
 
# Secret Manager (recommended)
echo -n "your-key" | gcloud secrets create google-api-key --data-file=-
gcloud run services update my-agent \
  --set-secrets="GOOGLE_API_KEY=google-api-key:latest" \
  --region=us-central1