Configuration

Config file

Create a YAML file (e.g., cueapi-worker.yaml):

# API key. Or set CUEAPI_API_KEY env var, or run `cueapi login`
# api_key: cue_sk_your_key_here
 
# API base URL (default: https://api.cueapi.ai)
# api_base: https://api.cueapi.ai
 
# Worker ID (default: hostname)
# worker_id: my-laptop
 
# Poll interval in seconds (default: 5)
poll_interval: 5
 
# Heartbeat interval in seconds (default: 30)
heartbeat_interval: 30
 
# Max concurrent handler executions (default: 4)
max_concurrent: 4
 
# Handlers: map task names to commands
handlers:
  my-task:
    cmd: "python3 handler.py"
    cwd: "/home/user/scripts"
    timeout: 120
    env:
      MY_VAR: "{{ payload.my_field }}"

Settings

API key resolution

The worker resolves API keys in this order:

1. api_key in the YAML config file
2. CUEAPI_API_KEY environment variable
3. ~/.config/cueapi/credentials.json (from cueapi login)

Outcome reporting

When a handler completes, the worker daemon automatically reports the outcome:

• Success - Handler exits cleanly. outcome_state set to reported_success.
• Failure - Handler throws an exception. outcome_state set to reported_failure with the error message.
• Timeout - Handler exceeds its timeout. outcome_state set to reported_failure with timeout message.

To attach evidence (external IDs, result URLs) after the handler completes, use PATCH /v1/executions/{id}/evidence:

curl -X PATCH https://api.cueapi.ai/v1/executions/$EXECUTION_ID/evidence \
  -H "Authorization: Bearer $CUEAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "tweet:123", "result_url": "https://twitter.com/user/123"}'

If the cue has a verification policy (e.g., require_external_id), the outcome transitions to verified_success once the required evidence is attached.

Minimal config

If you've already run cueapi login, the minimal config is just handlers:

handlers:
  my-task: "python3 handler.py"