Environment Variables

Built-in and custom environment variables available to handler scripts.

Built-in variables

Every handler script receives these environment variables automatically:

Variable	Description	Example
`CUEAPI_EXECUTION_ID`	Execution UUID	`550e8400-e29b-41d4...`
`CUEAPI_CUE_ID`	Cue ID	`cue_a1b2c3d4e5f6`
`CUEAPI_TASK`	The `payload.task` value	`draft-linkedin`
`CUEAPI_SCHEDULED_FOR`	ISO timestamp	`2026-03-13T09:00:00Z`

Custom environment variables

Define custom env vars in the handler config:

yaml

handlers:
  my-task:
    cmd: "python3 handler.py"
    env:
      MY_STATIC_VAR: "hello"
      MY_PAYLOAD_VAR: "{{ payload.instruction }}"

Template syntax

Use {{ payload.field }} to inject payload values:

yaml

env:
  INSTRUCTION: "{{ payload.instruction }}"
  CONTEXT_REF: "{{ payload.context_ref }}"
  AGENT: "{{ payload.agent }}"

Nested fields

Dot notation for nested objects:

yaml

env:
  OUTPUT_DIR: "{{ payload.config.output_dir }}"
  FORMAT: "{{ payload.config.format }}"

Missing fields

If a referenced payload field doesn't exist, it resolves to an empty string ("").

System environment

Handler scripts inherit the system environment. You can reference system env vars with ${} syntax:

yaml

env:
  OPENAI_API_KEY: "${OPENAI_API_KEY}"
  ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY}"
  HOME: "${HOME}"

Example: Full handler env

yaml

handlers:
  draft-linkedin:
    cmd: "python3 linkedin_agent.py"
    timeout: 300
    env:
      # From payload
      INSTRUCTION: "{{ payload.instruction }}"
      CONTEXT_REF: "{{ payload.context_ref }}"
      CONTEXT_MODE: "{{ payload.context_mode }}"
      AGENT: "{{ payload.agent }}"
      # From system
      ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY}"

In the handler script:

python

import os
 
instruction = os.environ["INSTRUCTION"]
context_ref = os.environ["CONTEXT_REF"]
execution_id = os.environ["CUEAPI_EXECUTION_ID"]  # Built-in

Previous← Handler Routing NextRunning →