Command line

The agent is configured by a .env file in the directory it runs from, plus flags on the command line. One invocation is one cycle unless --watch is passed.

Flags

Usage: sync-agent [options]   (version 1.0.0)

Reads .env from the current directory, syncs once, then exits.

Options:
  -w, --watch            Stay resident and repeat on the school's sync interval
      --interval=<min>   Override the interval, in minutes
      --plain            One timestamped line per cycle, no colour
  -v, --version          Print the version and exit
  -h, --help             Show this message

The version is also on the first line of --watch output, and every agent reports it to the server. The school's Overview shows which version each side runs.

--interval only changes how often the agent wakes, so it does nothing without --watch. It expects a positive number of minutes. An unrecognised flag exits before connecting to anything.

Environment variables

The agent reads .env from the directory it is run from. It does not search parent directories.

SYNC_SOURCE decides both halves of the agent's job: LOCAL captures UP tables and applies DOWN changes, ONLINE does the reverse. Any value other than ONLINE is treated as LOCAL.

A missing required variable stops the agent before it connects to anything, naming the variable it wanted.

Exit codes

A failed cycle in watch mode does not exit — the agent reports the error and waits for the next tick. When a watch-mode agent is stopped, its exit code reflects the last cycle it ran, so one that has since recovered exits 0.

A request to the monitoring server that gets no complete answer within 60 seconds fails the cycle rather than holding the run open.

Output

The agent writes for whoever is reading. Attached to a terminal it uses a compact coloured line per cycle, showing only the numbers that are non-zero:

15:35:50  DOWN applied 3, skipped 1 · UP pushed 12                          1.2s

A cycle that moved nothing reads idle rather than a row of zeros.

The moment output is piped or redirected — which is what a scheduler does — it falls back to one self-contained line per cycle:

2026-08-05T07:36:00.132Z [agent] PAC001 LOCAL — DOWN applied 0, skipped 0, failed 0 | UP scanned 0, pushed 0, dropped 0 across 1 table(s) | counted 0 table(s) | 911ms

Every number is always present here, so the line stays greppable and each entry carries its own timestamp. --plain forces this form in a terminal. NO_COLOR=1 keeps the compact layout but drops the escape codes.

Failures are called out on their own line with the cause attached, rather than a bare fetch failed:

15:32:50  cycle failed
          ! fetch failed (ECONNREFUSED)

When an apply fails, that line names the table and row id that stopped the queue, which is usually enough to diagnose without opening the dashboard.

What the numbers mean