Oko
Oko/Docs

Command reference

oko telemetry calendar

The member calendar: each member's days keyed in that member's own timezone. --format html writes one self-contained page for every member, with the goals file beside them when named; --format svg writes one member's engaged calendar as a drawing, and --format png has the system Quick Look renderer rasterize it for the places a browser is not. --explain explains one day from the turns behind it.

Invocation#

Command
oko telemetry calendar --format html|png|svg --output PATH [--from DAY] [--to DAY] [--period P] [--all] [--limit N] [--member 'NAME|TIMEZONE|ROOT' ...] [--root PATH] [--name NAME] [--timezone ID] [--goals PATH] | oko telemetry calendar --day DAY --explain [--json] [--limit N] [--root PATH] [--name NAME] [--timezone ID]

Inputs and options#

  • --format and --output, or --day and --explain; --member repeats one entry per member, or --name, --timezone and --root describe one; --from and --to as yyyy-MM-dd (--format png and svg need --from, the first day drawn; --to defaults to yesterday); --period one of the declared periods (html only); --json prints the explanation as `{member, zone, day, prompts, first, last, engagedSeconds, segments, largeGaps, turns}`.

Output and state effect#

  • --format writes the page, drawing or image to --output and prints its path; --explain reads only and prints the prompts, span, engaged segments, large gaps and turns.

Refusals and safe exits#

  • `oko telemetry calendar takes --format html, png or svg with --output PATH, or --day DAY --explain`; `oko telemetry calendar --format takes html, png or svg; got <format>`; `oko telemetry calendar requires --output <text>` (exit 2); `unknown --period '<period>'; the periods are <list>`; `oko telemetry calendar --format png|svg takes --from YYYY-MM-DD, the first day to draw`; `oko telemetry calendar --explain takes --day YYYY-MM-DD`; `invalid --from: <text>; days are yyyy-MM-dd` and the same for --to and --day; `invalid --timezone: <zone>`; `render failed: /usr/bin/qlmanage could not start: <error>`; `render failed: qlmanage exited <status> without writing <path>: <output>`; `render failed: <path> cannot be created|written|moved to <path>: <error>`.
  • A member without --timezone (or a --member entry without its zone) takes this machine's zone; when the system cannot name it the command refuses with `this machine's time zone cannot be read (<error>); name it with --timezone` instead of drawing in UTC. A --from day with no start in the member's zone (a zone change at midnight) refuses with `oko telemetry calendar: <day> has no start in the local time zone <zone>`. The SVG a PNG is rendered from is removed after; one that cannot be removed is named on stderr.
  • A --from day after the --to day (the defaulted --to included) refuses with `--from <from> is after --to <to>; the window holds no day` and writes nothing, for the page and the drawing alike; --all, which takes its window from the prompts found, is not checked.
  • The goals the page marks its days with come from --goals PATH, else this machine's own goal document for a one-member run; no such file is a page without goals. A document that cannot be read, is not JSON, holds no goals list, holds promptMappings that is not a list, or holds a prompt mapping with no sessionId refuses the page naming the file: `the goal document <path> cannot be read: <error>`, `… is not JSON: <error>`, `… holds no goals list`, `… holds promptMappings that is not a list: <value>`, `… holds a prompt mapping with no sessionId: <mapping>`. A day with no midnight in the member's zone refuses with `the calendar day <day> has no midnight in the local time zone`, --limit below zero with `oko telemetry calendar: --limit counts transcripts and cannot be negative; got <n>`, and a --member entry with no name with `--member '<entry>' names no member; an entry is 'NAME|TIMEZONE|ROOT'`.

CLI reference#