Notify
cmd/crewship/cmd_notify.go manages OS-level desktop notifications. Crewship can
ping you when an opted-in run completes after the long-run threshold, and you can
send or test a notification directly. Server-side category preferences and
templates are separate from this local desktop setting.
The preference is stored in ~/.crewship/cli-config.yaml (notifications: true|false).
crewship notify enable
Opt in. Sets notifications: true in the config file.
crewship notify disable
Opt out.
crewship notify status
Show the current setting.
crewship notify test
Fire one notification right now via cli.OSNotify. It does not change the
preference and returns an error if the host notification integration fails.
crewship notify prefs
Manage the authenticated user’s server-side category × channel preference
matrix. Both subcommands require an authenticated workspace. get prints a
CATEGORY, CHANNEL, STATE table; --format json returns the server’s
{"cells": [...]} payload. set prints a confirmation and changes one cell.
set requires all three flags. --category accepts a category shown by
crewship notify prefs --help or * to mute the channel; --channel is a
channel ID from notifychannel list; and --state accepts only off or
immediate (the flag’s CLI default is empty, so omitting it is an error).
Unset cells are treated by the server as off.
crewship notify templates
Manage authenticated workspace overrides for wording generated by Crewship.
This does not rewrite text from a routine notify step or an agent message.
Templates can use {{ vars.<fact> }}, {{ source.title }},
{{ source.body }}, {{ source.category }}, and {{ source.kind }}. Missing
event facts render empty; an entirely empty rendered field falls back to the
producer’s wording.
list prints CATEGORY, CHANNEL, TITLE, and BODY (workspace-wide rows
show (all) for the channel). set requires --category and at least one of
--title or --body; --channel is optional and otherwise applies to every
channel. rm requires --category; its optional --channel removes only the
channel-specific override. Set and remove print confirmation lines. All three
commands support the normal formatter flags.
crewship notify send <title> <body>
Ad-hoc notification — scripting hook.
send requires exactly one title and one body. It writes no success line; a
successful exit means the OS notification command accepted the request.
crewship notify prefs — server-side notification preferences
Distinct from everything above: notify prefs manages your server-side category × channel preference matrix (issue #1412) — which of your workspace/personal notification channels (email, webhook, Slack, Discord, Telegram; created with crewship notifychannel add) get pinged for which category of event (approvals, escalations, failed runs, chat replies, …). See the full Outbound notifications guide for the category list, the notifychannel command family, and the two-layer (admin + user) preference model.
A cell you never set defaults to
off — nothing is delivered externally until you opt in.
Long-run threshold
The internal helpermaybeNotifyRunComplete only fires for completed or failed
run/pipeline/watch paths when:
- The user opted in via
notify enable, and - The run took longer than the threshold (default
30s).
CREWSHIP_NOTIFY_LONG_RUN=<seconds> — tighter cadence for quick feedback, looser cadence to suppress noise from short routine runs.
Failed runs land with the title Crewship — run FAILED at Critical urgency;
normal completion lands as Crewship — run done at Info. Approval and
escalation desktop notifications are not emitted by the current CLI helper.
See also
crewship config— direct view of thenotificationskey.crewship escalation— escalations are one of the events that fire notifications.crewship wait— script-blocking alternative to desktop pings.