Heka CLI¶

The heka CLI provides campaign administration commands for human developers. It communicates with the Heka server via HTTP.

Installation¶

The CLI is installed automatically with the heka package:

uv pip install -e .

The entry point is registered as heka in pyproject.toml.

Configuration¶

Environment variable	Default	Description
`HEKA_ADMIN_BASE_URL`	`http://localhost:8000`	Heka server base URL
`HEKA_ADMIN_TOKEN`	(empty)	Bearer token for authentication
`HEKA_DB_PATH`	`heka_conversations.db`	Database path (for local commands)

For production:

export HEKA_ADMIN_BASE_URL=https://heka-operator.fly.dev
export HEKA_ADMIN_TOKEN=your-jwt-token

Commands¶

Campaign phase management¶

Update phase instructions¶

heka campaign phase update <campaign_id> <phase_id> --instructions "New agent instructions..."

Updates the AI agent's instructions for a specific pipeline phase. The instructions define how the agent should behave when interacting with contacts in that phase.

Arguments:

campaign_id — Campaign identifier (e.g. camp-amate-2026-q3)
phase_id — Phase identifier: welcome, qualify, nurture, close, followup
--instructions — New natural-language instructions text

Campaign resource management¶

List resources¶

heka campaign resource list <campaign_id>

Returns JSON array of all resources attached to the campaign context (documents, media).

Add resource¶

# Text-only resource
heka campaign resource add <campaign_id> \
  --id prices-2026 \
  --title "Price List 2026" \
  --content "Monthly tuition: $2,500 MXN..."

# With media file upload
heka campaign resource add <campaign_id> \
  --id promo-video \
  --title "Promotional Video" \
  --content "30-second school tour" \
  --media-file ./promo.mp4 \
  --media-type video

# With pre-hosted media URL
heka campaign resource add <campaign_id> \
  --id school-photo \
  --title "School Photo" \
  --content "Front view of the school" \
  --media-url "https://cdn.example.com/school.jpg" \
  --media-type image

Update resource¶

heka campaign resource update <campaign_id> <resource_id> \
  --title "Updated Title" \
  --content "Updated content"

At least one field (--title, --content, --media-url, --media-type) is required.

Delete resource¶

heka campaign resource delete <campaign_id> <resource_id>

Lead state sweep¶

heka sweep-lead-states

Recalculates lead_state for all contacts that may have gone cold or stalled. Reads from the local database (requires HEKA_DB_PATH). Safe to run multiple times — idempotent.

Output format¶

All commands output JSON to stdout, errors to stderr. Pipe to jq for formatting:

heka campaign resource list camp-amate-2026-q3 | jq '.resources[] | .title'