CLI Reference

Send events from any shell environment — cron jobs, CI pipelines, bash scripts, or Claude Code hooks. No SDK required.

Setup

Install & Register

curl -fsSL https://raw.githubusercontent.com/notilens/sdk-shell/main/notilens.sh \
  -o /usr/local/bin/notilens && chmod +x /usr/local/bin/notilens

notilens init --name my-app --token YOUR_TOKEN --secret YOUR_SECRET

# Multiple sources
notilens init --name scraper --token TOKEN_A --secret SECRET_A
notilens init --name mailer  --token TOKEN_B --secret SECRET_B

# List / remove
notilens sources
notilens remove-source my-app

Notify

Send a one-off notification without any task context.

notilens notify order.placed    "Order #1234"      --name my-app
notilens notify disk.space.full "Only 1GB left"    --name my-app --type warning
notilens notify report.ready    "Report is ready"  --name my-app --download_url https://example.com/r.pdf

Task Commands

Task Lifecycle

--task is a semantic label (e.g. email, report). Each start creates an isolated run — concurrent executions of the same label never conflict.

notilens queue     --name my-app --task email
notilens start     --name my-app --task email
notilens progress  "Fetching data"   --name my-app --task email
notilens loop      "Step 3 of 10"    --name my-app --task email
notilens retry     --name my-app --task email
notilens pause     "Rate limited"    --name my-app --task email
notilens resume    "Resuming"        --name my-app --task email
notilens wait      "Awaiting tool"   --name my-app --task email
notilens error     "Step 3 failed"   --name my-app --task email
notilens complete  "All done"        --name my-app --task email
notilens fail      "Unrecoverable"   --name my-app --task email
notilens timeout   "Took too long"   --name my-app --task email
notilens cancel    "User cancelled"  --name my-app --task email
notilens terminate "Out of memory"   --name my-app --task email

Output & Input

Output, Input & Generic Events

# Output events
notilens output.generate "Report ready"      --name my-app --task email
notilens output.fail     "Model unavailable" --name my-app --task email

# Input / human-in-the-loop
notilens input.required "Please confirm"  --name my-app --task email
notilens input.approve  "Confirmed"       --name my-app --task email
notilens input.reject   "Rejected"        --name my-app --task email

# Generic / custom events
notilens track order.placed    "Order #1234"        --name my-app
notilens track disk.space.full "Only 1GB remaining" --name my-app --type warning

Metrics

Numeric values accumulate across calls and are included in every notification.

notilens metric tokens=512 cost=0.003 --name my-app --task job_001
notilens metric records=1500          --name my-app --task job_001

notilens metric.reset tokens          --name my-app --task job_001
notilens metric.reset                 --name my-app --task job_001

Options

All Options

Flag	Required	Description
`--name`	Yes	Source name identifying the app, script, or agent
`--task`	Yes*	Semantic task label. Required for all task.* commands.
`--type`	No	`info` `success` `warning` `urgent`
`--meta key=value`	No	Custom metadata (repeatable)
`--image_url`	No	Attach an image URL
`--open_url`	No	URL to open on tap
`--download_url`	No	URL to download
`--tags`	No	Comma-separated tags
`--is_actionable`	No	`true` or `false`
`--force_send`	No	Bypass ML filtering (`true`) or route through it (`false`). See defaults below.

force_send

force_send Defaults

Controls whether a notification bypasses NotiLens's ML-based filtering layer. High-signal events default to true (always sent); status events default to false (ML decides).

Command	Default
`notify` · `fail` · `timeout` · `terminate`	`true` — always delivered
`input.required` · `output.generate` · `output.fail`	`true` — always delivered
`start` · `progress` · `loop` · `retry` · `pause` · `resume` · etc.	`false` — ML filtered

# Override — force-deliver a progress update
notilens progress "Critical step" --name my-app --task email --force_send true

# Override — let ML decide on a failure
notilens fail "Unrecoverable" --name my-app --task email --force_send false

Claude Code Hooks

Claude Code Hooks Example

Use the CLI with Claude Code hooks to get notified on every AI task automatically.

{
  "hooks": {
    "PreToolUse": [{ "matcher": "Task", "hooks": [{ "type": "command",
      "command": "notilens start --name claude --task ai" }] }],
    "PostToolUse": [{ "matcher": "Task", "hooks": [{ "type": "command",
      "command": "notilens complete \"Task done\" --name claude --task ai" }] }],
    "Stop": [{ "hooks": [{ "type": "command",
      "command": "notilens complete \"Session ended\" --name claude --task ai" }] }],
    "Notification": [{ "hooks": [{ "type": "command",
      "command": "notilens input.required \"Claude needs input\" --name claude --task ai" }] }]
  }
}

← PreviousJava / Kotlin SDK Next →Webhooks