Goalfeed

Configuration reference

Every CLI flag, YAML key, and GOALFEED_* environment variable Goalfeed reads, with type, default, and a worked example.

Minimal working config.yaml

Copy this, edit the URL/token and team codes, and you have a working install:

config.yaml 
home_assistant:
  url: "http://homeassistant.local:8123"
  access_token: "your-long-lived-access-token"

watch:
  nhl:
    - WPG
  mlb:
    - TOR
  cfl:
    - BC
    - OTT

Goalfeed looks for this file as ./config.yaml in its working directory, reads it once at startup with Viper, and layers environment variables and CLI flags on top. Precedence, lowest to highest:

config file  →  GOALFEED_* env var  →  CLI flag

Complete option table

CLI flagYAML keyEnv varType DefaultDescription
--nhlwatch.nhl GOALFEED_WATCH_NHLstring list[] NHL team codes to watch, e.g. WPG, or * for every team
--mlbwatch.mlb GOALFEED_WATCH_MLBstring list[] MLB team codes to watch
--cflwatch.cfl GOALFEED_WATCH_CFLstring list[] CFL team codes to watch
—watch.nfl GOALFEED_WATCH_NFLstring list[] NFL team codes to watch — no CLI flag exists, YAML or env only
—watch.olympic_men GOALFEED_WATCH_OLYMPIC_MENstring list [] Olympic Men's Hockey team codes — no CLI flag; see the leagues reference for this league's WIP status
—watch.olympic_women GOALFEED_WATCH_OLYMPIC_WOMENstring list [] Olympic Women's Hockey team codes — no CLI flag; same WIP status
—watch.iihf GOALFEED_WATCH_IIHFstring list[] IIHF team codes — only affects the on-demand /api endpoints, not the live-polling goal loop (see leagues reference)
—home_assistant.url GOALFEED_HOME_ASSISTANT_URLstring "" Home Assistant base URL. Ignored and auto-detected when running as the HA Supervisor add-on
—home_assistant.access_token GOALFEED_HOME_ASSISTANT_ACCESS_TOKENstring "" Home Assistant long-lived access token. Also ignored under the Supervisor
—home_assistant.allow_remote_url GOALFEED_HOME_ASSISTANT_ALLOW_REMOTE_URLbool false Allow home_assistant.url to be a public/remote address. Default rejects anything that isn't loopback/private/link-local-adjacent or a clearly local hostname — see Security
—web.allow_config_writes GOALFEED_WEB_ALLOW_CONFIG_WRITESbool false Let POST /api/homeassistant/config persist changes to config.yaml on disk. By default it only updates the running process's in-memory config for the current session
--test-goalstest-goals hyphenated key, see note belowbool false Fire a synthetic TEST goal event once a minute, through the same code path as a real goal — see the getting-started tutorial
--webweb hyphenated keyboolfalse Start the REST/WebSocket/web UI server alongside the polling loop. Without it, Goalfeed runs headless
--web-portweb-port hyphenated keystring"8080" Port for the web server
—app_log.path GOALFEED_APP_LOG_PATHstring "app.log.jsonl" Path to the JSONL application log behind /api/logs and /api/events; parent directory is created if missing
—nfl.fastcast.enabled GOALFEED_NFL_FASTCAST_ENABLEDbool true Use ESPN's Fastcast WebSocket for near-real-time NFL updates alongside polling
—nfl.fastcast.ping_interval_sec GOALFEED_NFL_FASTCAST_PING_INTERVAL_SECint (seconds) 20Fastcast keepalive ping interval
—nfl.fastcast.pong_wait_sec GOALFEED_NFL_FASTCAST_PONG_WAIT_SECint (seconds) 60Fastcast pong timeout
—nfl.fastcast.reconnect_base_ms GOALFEED_NFL_FASTCAST_RECONNECT_BASE_MSint (ms) 2000Fastcast reconnect backoff base
—nfl.fastcast.reconnect_max_ms GOALFEED_NFL_FASTCAST_RECONNECT_MAX_MSint (ms) 30000Fastcast reconnect backoff ceiling

Notes that bite people

  • There is no --config flag. Goalfeed always looks for ./config.yaml (or .yml) in the current working directory. If it's missing, the read fails silently and every key falls back to its zero value — see Troubleshooting.
  • CLI flags exist only for --nhl/--mlb/--cfl. NFL, IIHF, and Olympic Men's/Women's Hockey team lists are config-file or environment-variable only — there's no flag for them, and none is planned to appear here without one being added to main.go.
  • Precedence is config file → environment variable → CLI flag — a flag always wins over an env var, which always wins over the YAML file.
  • test-goals, web, and web-port use hyphenated Viper keys, which most shells reject in export NAME=value. Set them via CLI flag, YAML, or env 'GOALFEED_WEB=true' goalfeed instead of a plain export.
  • watch.* accepts "*" as a wildcard meaning "every team in this league" — useful for testing, noisy for daily use.
  • The Home Assistant Supervisor add-on ignores home_assistant.url and home_assistant.access_token entirely when SUPERVISOR_API/SUPERVISOR_TOKEN are present in the environment — which they always are under the add-on. Setting those keys has no effect there.

Worked examples

Watch every NHL team, with test events on, in web mode

config.yaml 
watch:
  nhl:
    - "*"
test-goals: true
web: true
web-port: "8080"

NFL, no CLI flag — YAML only

config.yaml 
watch:
  nfl:
    - CLE
    - GB

Same NFL example as environment variables

bash 
export GOALFEED_WATCH_NFL=CLE,GB
export GOALFEED_HOME_ASSISTANT_URL=http://homeassistant.local:8123
export GOALFEED_HOME_ASSISTANT_ACCESS_TOKEN=your-long-lived-token
./goalfeed --web

A remote Home Assistant instance, explicitly allowed

config.yaml 
home_assistant:
  url: "https://myhome.duckdns.org:8123"
  access_token: "your-long-lived-access-token"
  allow_remote_url: true   # required — see Security

Without allow_remote_url: true here, Goalfeed refuses to send events to this URL at all — see Security for why, and Troubleshooting for the exact error text.

Next

Turn these into a running instance — Install — or wire the resulting events into Home Assistant — Home Assistant automations.