Reference

Dives and depth

Everything a dive can be told to do, and the exact rule for who gets through at each depth.

The three depths

Depth, duration, and who reaches you
Depth	Default	Who gets through	Everything else
`shallow`	25 min	Anyone on your team	Delivered normally
`mid`	50 min	Escalation path, plus direct mentions	Held until you surface
`deep`	90 min	Escalation path, marked urgent	Held until you surface

Held is held, not dropped. Surfacing releases everything in the order it arrived, with the ones marked urgent first.

The configuration file

Optional. Everything here has a default, and the defaults are what most people run. The file lives at ~/.config/viva/config.toml and is re-read at the start of every dive, so you can edit it mid-session without restarting anything.

[dive]
default_depth  = "mid"
warn_before    = "5m"      # a single nudge before you surface
auto_surface   = true      # end the dive when the timer runs out

[dive.durations]
shallow = "25m"
mid     = "50m"
deep    = "90m"

[escalation]
# At most five. The product will refuse a sixth, on purpose.
people = ["kit@example.com", "ines@example.com", "ops-oncall@example.com"]

[hold]
release_order  = "urgent-first"
summarise      = true      # one digest instead of forty notifications

The CLI

Four commands do everything. The rest of the surface is viva help.

viva dive <depth> [--note TEXT] [--for DURATION] [--at TIME]
viva status [--json]
viva surface [--release-quietly]
viva shoal [--watch]

--for overrides the configured duration for one dive. --at schedules one to begin later, which is how a current is expressed on a single machine.

--json on status is the supported way to put your depth in a shell prompt or a status bar. The shape is stable and covered by the same versioning promise as the API.

$ viva status --json
{
  "depth": "deep",
  "started_at": "2026-08-10T14:12:00Z",
  "surfaces_at": "2026-08-10T15:42:00Z",
  "note": "rewriting the tiler",
  "held": { "messages": 4, "mentions": 1, "urgent": 0 }
}

Starting a dive from a calendar event

Any event whose title begins with Dive: starts one, at the depth named after the colon if there is one and at default_depth if there is not. The dive lasts as long as the event.

This is how most people end up using Currents without ever opening the Currents screen, and it is the reason the calendar integration is on the Reef plan rather than being an add-on.

The Shoal API Back to quickstart

VivaOcean is a fictional product. This site exists to show a theme, and every number on it was made up to fill a layout.