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
 
# Multi-agent project with webhook service
zil init my-agent --agents vta,vtd --service webhook
 
# Scaffold with skills
zil init my-agent --agents vta,vtd --skills fd-explore-repo,fd-submit-changes
 
# Include MCP server scaffolding
zil init my-agent --mcp filesystem

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 serve [options]

data: {"type": "tool_call", "tool_name": "search", "args": {"q": "zil"}}

data: {"type": "tool_result", "tool_name": "search", "result": "..."}

data: {"type": "text", "text": "Based on the search results..."}

data: {"type": "done", "metadata": {"session_id": "abc-123"}}

# Start on default port
zil serve
 
# Custom port and host
zil serve --port 3000 --host 0.0.0.0
 
# With tracing
zil serve --trace
 
# Dev mode with auto-reload
zil serve --reload
 
# Disable A2A protocol
zil serve --no-a2a

# Build image and run container
zil serve --docker
 
# With full observability (Grafana OTEL-LGTM stack)
zil serve --docker --trace
 
# Custom port
zil serve --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
 
# 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

zil deploy --project my-project --region us-central1 --output json

{
  "agent": "my-agent",
  "version": "1.0.0",
  "service": "my-agent",
  "project": "my-project",
  "region": "us-central1",
  "url": "https://my-agent-abc123-uc.a.run.app",
  "endpoints": {
    "adk_web": "https://my-agent-abc123-uc.a.run.app/dev-ui",
    "webhook": "https://my-agent-abc123-uc.a.run.app/webhook",
    "hitl_respond": "https://my-agent-abc123-uc.a.run.app/human/respond"
  },
  "cloud_sql_instance": "my-project:us-central1:my-instance",
  "deployed_at": "2026-05-21T14:30:00Z"
}

→ 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