Introduction

aviso is ECMWF’s notification system for data-driven workflows. It runs as a client and a server: aviso-server tracks streams of events and pushes them out in close to real time; clients connect, subscribe to the streams they care about, and react when a dataset they were waiting for has landed.

This site documents the client side. This repo holds three clients: a command-line tool, a Rust library, and a Python package. Pick the one that fits how you work.

From the command line

The aviso binary publishes notifications, listens for new ones, and replays history. It runs on Linux and macOS.

aviso listen --event mars --identifiers '{"class":"od"}'

Start with the CLI overview.

From Python

The pyaviso package wraps the Rust core through PyO3, so you get a real Python API: typed value objects, structured exceptions, for-iteration over a watch stream, and the same trigger surface the CLI uses.

import os
import pyaviso

client = pyaviso.AvisoClient(base_url=os.environ["AVISO_BASE_URL"], auth=pyaviso.Env())

for notification in client.listen("mars", filter={"class": "od"}):
    print(notification.sequence, notification.payload)

Start with the Python overview.

From a Rust program

The Rust library powers the CLI and is on crates.io. Use it when you want notifications inside a Rust binary or service.

use aviso::AvisoClient;

let client = AvisoClient::builder()
    .base_url("https://aviso.example")
    .build()?;

Start with the library guide.

New here?

• What aviso does and how the pieces fit together.
• Install the CLI or the library.
• Quickstart: your first publish and your first listener.

Reference

• CLI flags: every flag, every subcommand.
• Listener YAML: the file format the CLI reads.
• State file: what aviso writes to disk to remember where it left off.
• Rust API: types, traits, and functions.

What aviso is

aviso is ECMWF’s notification system for data-driven workflows. It runs as a client-server pair: aviso-server is the source of truth for streams of events; the client connects, asks for the events you care about, and tells you when they arrive. This page is about the client.

The pieces

flowchart LR
    server["aviso-server<br/>(someone else runs this)"]
    client["aviso<br/>(you run this on your box)"]
    triggers["triggers run here:<br/>echo, log, webhook,<br/>command, teams, post"]

    client -->|HTTP| server
    server -->|SSE stream| client
    client --> triggers

The server is the source of truth. Your aviso client subscribes, processes incoming notifications through any triggers you have configured, and remembers where it left off so it can resume cleanly after a restart.

What an event looks like

The server speaks in events. Every event has:

• a type that names what kind of thing happened (for example mars),
• a set of identifiers that describe which one (class=od, stream=oper, a date, a step, and so on),
• an optional JSON payload with whatever the publisher attached (often the location of a file),
• a sequence number that strictly increases per event type.

You ask aviso to listen for a type and the identifiers you care about. The server streams every matching new event to you over a long-lived HTTP connection.

Four ways to use it

The CLI and the library are the same code. Pick the surface that matches the program you are writing.

What aviso takes care of for you

• Reconnects. The server intentionally closes a listener every so often. aviso reconnects without losing your place.
• Resume. When the process restarts, aviso picks up from the last notification it fully processed. Normal restarts avoid skipping events.
• At-least-once delivery. Each notification reaches your triggers at least once. Design your triggers to be idempotent.
• Backpressure. If your code is slow to handle a notification, aviso slows down its read from the network rather than buffering forever in memory.
• Heartbeat watchdog. If the network goes quiet for too long, aviso assumes the connection is dead and reconnects.

Where to go next

• New here and want to try it in 5 minutes? Quickstart.
• Want to set up a long-running listener? Listen for notifications.
• Want to understand the model in more depth? Concepts.

Install

Most users need exactly one command:

pip install pyaviso
aviso --version

The Python package carries both surfaces: the importable pyaviso library and the aviso command-line tool. The wheel installs the CLI as a console script that runs the Rust core in-process, so there is no Rust toolchain to set up and no separate binary to download.

Command line without Python

If you do not use Python, cargo builds the same CLI from source:

cargo install aviso-cli
aviso --version

cargo install puts the binary in ~/.cargo/bin/aviso, which is on your PATH if you installed Rust through rustup. Both install paths give you the same aviso command and behaviour.

The CLI install page covers the from-source path and how to verify your install.

Rust library, in your Cargo.toml

[dependencies]
aviso = "2.0"
tokio = { version = "1.53", features = ["macros", "rt-multi-thread"] }
serde_json = "1.0"

aviso is async and runs on tokio. The full library guide is in the developers section.

What you need on the server side

Whichever surface you pick, you will need:

• The base URL of an aviso-server you can talk to (your team or ECMWF gives you this).
• Credentials, when the server requires them (usually a bearer token).

See authentication providers for the five ways to attach credentials.

Quickstart

The fastest path from nothing to a working notification. Pick the surface you have, follow the four steps, and you are done.

1. Get the binary

pip install pyaviso
aviso --version

The Python package bundles the aviso command-line tool, so pip is all you need. If you prefer a Rust-native install, cargo install aviso-cli gives you the same command. The full install guide is at Install.

2. Point at a server

Tell aviso where the server is and how to authenticate. The simplest way is environment variables:

export AVISO_BASE_URL=https://aviso.example
export AVISO_TOKEN=your-bearer-token

Or pass them on the command line each time, with --base-url and --token.

If you would rather keep them in a file, see CLI configuration.

3. Discover notification types

First, see which notification types the server offers:

aviso schema list

For a server configured with just the example mars type, the terminal output is:

1 schema(s) registered (status: success)
- mars

This lists registered notification types, not stored notifications or data files. Pick a type from your server’s list and inspect its schema to see which identifiers you can filter on:

aviso schema get mars

Example output from a server with a minimal mars schema:

{
  "event_type": "mars",
  "schema": {
    "identifier": {
      "class": {
        "description": "MARS class.",
        "required": true,
        "type": "EnumHandler",
        "values": [
          "od",
          "rd"
        ]
      }
    },
    "payload": {
      "required": false
    }
  },
  "status": "success"
}

Here, class is required in the listener’s filter. EnumHandler means its value must come from the listed values, od or rd. We will choose od below. The payload is optional for notifications of this type.

This JSON describes the schema already registered on the server; it is command output, not a configuration file to install. Your server may offer other types or require more identifiers. Use its schema to choose the event type and supply all required identifiers in the examples below.

4. Listen for something

For the example schema above, listen for mars notifications with class=od:

aviso listen --event mars --identifiers '{"class":"od"}'

Press Ctrl+C to stop.

Every matching notification prints to your terminal as JSON. When you redirect the output to a file or pipe it into another tool, the format changes to one compact JSON object per line so you can chain it with jq:

aviso listen --event mars --identifiers '{"class":"od"}' | jq -r '.payload'

That is it. You have a working listener.

What just happened

• aviso connected to the server and opened a long-lived stream.
• It asked for mars events with class=od.
• It echoed each match to your terminal.
• It remembered the last notification it printed in ~/.config/aviso/state.json, so the next run starts after that point.

Re-running the same command resumes from where you left off. A notification can still be redelivered after a crash or failed checkpoint, so production triggers should be safe to run more than once. To start fresh next time, add --no-state-store.

Calling aviso from Python

The same listener as step 4, through the native Python API. The pip install pyaviso from step 1 already gave you the pyaviso package, and pyaviso.Env() reads the same environment variables you exported in step 2:

"""Listen for mars notifications and print each one as it arrives."""

import os
import pyaviso

client = pyaviso.AvisoClient(base_url=os.environ["AVISO_BASE_URL"], auth=pyaviso.Env())

for notification in client.listen("mars", filter={"class": "od"}):
    print(f"seq={notification.sequence} payload={notification.payload}")

Notifications arrive as typed objects with sequence, identifier, and payload fields, so there is no JSON to re-parse. Publishing, resuming across restarts, async, and error handling are covered in the Python section, starting with its quickstart.

Calling aviso from a Rust program

use std::collections::BTreeMap;
use aviso::{
    watch::{Trigger, WatchRequest},
    AvisoClient,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = AvisoClient::builder()
        .base_url("https://aviso.example")
        .build()?;

    let mut filter = BTreeMap::new();
    filter.insert("class".to_string(), serde_json::json!("od"));

    let req = WatchRequest::watch("mars")
        .with_filter(filter)
        .with_triggers(vec![Trigger::echo()]);

    let mut stream = client.watch(req)?;
    while let Some(notification) = stream.recv().await {
        let n = notification?;
        println!("seq {}: {}", n.sequence, n.payload);
    }
    Ok(())
}

The filter must include any identifier the event type’s schema marks required: true (run aviso schema get <TYPE> to see which).

The full library walkthrough is in the library guide.

Next

• Publish a notification (your first aviso notify).
• Listen with a YAML file: named listeners, multiple triggers, the configuration you keep around.
• Concepts: the five ideas you need to get fluent.

Concepts in five minutes

The five ideas you need to get fluent with aviso. Each links to a deeper page if you want more.

Notifications

A notification is one event from the server. It has an event type, a set of identifiers, an optional JSON payload, and a sequence number that strictly increases.

You ask the server “let me know when something of type mars arrives matching these identifiers”, and the server streams the matching events to you.

Read Notifications for the wire format and the fields.

Streams

When you listen, aviso opens a long-lived HTTP connection (an SSE stream) to the server. The server pushes events to you as they happen. The connection deliberately closes after a configured maximum duration; aviso reconnects automatically. Reconnects are normal, not an error.

Read Streams for the reconnect rules and the heartbeat watchdog.

Filters

A filter is the set of identifiers you want notifications for. {"class":"od","stream":"oper"} says “only events where the identifier map matches both of these”. The server enforces filters; aviso just passes them along.

Some identifier fields are required by the server’s schema, others are optional. Omitted optional fields act as wildcards.

Read Filters for the matching rules and the spatial filter shapes.

Resume and state

When aviso processes a notification end-to-end (including running every required trigger), it writes the sequence number to a small JSON file. On restart, aviso reads that file and resumes from the next sequence. You will not miss events and you will not skip ahead.

The file lives at ~/.config/aviso/state.json by default. You can change it, disable it for a one-off run, or delete it when you want to start fresh.

Read Resume and state for the durability rules and the rewind workflow.

Triggers

A trigger is what aviso does with each notification. Six built-in kinds are available:

• echo prints the notification.
• log appends it to a file.
• command runs a shell command (Unix only).
• webhook makes an HTTP request to a URL of your choice.
• teams posts to a Microsoft Teams channel.
• post forwards the original event envelope to another service.

You can attach as many triggers as you want to a listener. They run in order, and the sequence number only advances when every required trigger succeeds.

Read the Triggers overview for the dispatcher contract and pick a kind to dive into.

Where to go next

• Quickstart if you want to try it now.
• CLI overview if you are setting up a listener.
• Library guide if you are embedding aviso in your own Rust code.

CLI overview

aviso is a single binary that talks to an aviso-server. Use it to publish notifications, listen for new ones, replay history, and look around (schemas, configuration).

Use it when you want to:

• Subscribe to a stream and pipe the output to jq, a log file, or any line-oriented tool.
• Run a long-lived listener that ships notifications to a webhook, a Teams channel, a log file, or a custom shell command.
• Drop a notification into a stream from a script.
• Inspect what schemas the server publishes, or wipe a stream during testing.

Subcommands at a glance

When to use the CLI vs the library

Both surfaces are built on the same code, so behaviour is identical at the wire level.

What comes next

• Install the binary.
• Quickstart: the smallest useful run, end to end.
• Publish and listen: the two commands you will use most.

Install the CLI

The fastest way to get aviso is pip. The Python package bundles the CLI, so one install works even if you never write a line of Python.

From PyPI

pip install pyaviso
aviso --version

The wheel installs a console script that runs the Rust CLI in-process through the extension, so you do not need a Rust toolchain. See the Python install page for wheel coverage and details.

From crates.io

If you have a Rust toolchain and prefer a native binary:

cargo install aviso-cli
aviso --version

cargo install builds from source and puts the binary in ~/.cargo/bin/aviso. That directory is on your PATH when you installed Rust through rustup. Both install paths give you the same aviso command and behaviour.

From a git checkout

For an unreleased version, or when contributing:

git clone https://github.com/ecmwf/aviso-client.git
cd aviso-client
cargo install --path crates/aviso-cli

Verify

aviso --version
aviso --help

You should see the subcommands listed.

Where the binary lives

The binary is called aviso, not aviso-cli. The crate name carries the -cli suffix to leave the unprefixed aviso for the library, but the installed executable is plain aviso so it reads cleanly on the command line.

# Linux, macOS
which aviso
# pip install: <venv-or-user-base>/bin/aviso
# cargo install: /home/you/.cargo/bin/aviso

Shell completions

aviso completions <shell> prints a completion script for bash, zsh, fish or elvish. Save it where your shell looks for completions, then open a new shell. The right place depends on the shell and, for zsh, on how it is set up, so check the notes below if aviso <Tab> does nothing.

Run the commands with the same aviso you use day to day. If it lives in a virtual environment, activate it first; the script is generated by the binary, so it matches that version’s subcommands and flags.

Bash

mkdir -p ~/.local/share/bash-completion/completions
aviso completions bash > ~/.local/share/bash-completion/completions/aviso

This needs the bash-completion package, which most distributions install and load from /etc/bash.bashrc or /etc/profile.d. It picks up files in that directory by command name the first time you press Tab after the command. If complete -p aviso in a new shell says “no completion specification”, bash-completion is not loaded; install it, or source the file yourself from ~/.bashrc:

source ~/.local/share/bash-completion/completions/aviso

Zsh

Zsh only searches the directories in $fpath, and the file must be named _aviso. Which directory that is depends on your setup:

# Plain zsh: create the directory and add it to fpath before compinit in
# ~/.zshrc, then save the script there.
mkdir -p ~/.zsh/completions
aviso completions zsh > ~/.zsh/completions/_aviso
# in ~/.zshrc, above `compinit`:
#   fpath=(~/.zsh/completions $fpath)

# oh-my-zsh: its custom completions directory is already in fpath.
mkdir -p ~/.oh-my-zsh/custom/completions
aviso completions zsh > ~/.oh-my-zsh/custom/completions/_aviso

Zsh caches the list of completion functions in ~/.zcompdump. After adding a new file, delete that cache and start a new shell:

rm -f ~/.zcompdump*
exec zsh

To check it worked, whence -w _aviso in the new shell prints _aviso: function. If it prints nothing, the directory holding the file is not in $fpath; print -l $fpath lists the ones zsh searches.

Fish

aviso completions fish > ~/.config/fish/completions/aviso.fish

Fish loads the file on the next Tab; no restart is needed.

Elvish

aviso completions elvish > ~/.config/elvish/lib/aviso.elv

The script registers the completer when it is evaluated, so add eval (slurp < ~/.config/elvish/lib/aviso.elv) to ~/.config/elvish/rc.elv.

Upgrading

• pip: pip install --upgrade pyaviso.
• cargo: cargo install aviso-cli again. Cargo replaces the binary in place; add --force to rebuild from scratch.

Uninstalling

pip uninstall pyaviso        # pip install
cargo uninstall aviso-cli    # cargo install

A cargo-installed binary can also be deleted from ~/.cargo/bin/aviso by hand. Configuration and state files in ~/.config/aviso/ are left alone; remove them if you want a clean slate:

rm -rf ~/.config/aviso

What next

• Quickstart: your first run.
• Configuration: config files, environment variables, TLS settings.

CLI quickstart

Consumers use Aviso to receive notifications from data providers. Start by discovering event types, then listen for new notifications or replay past ones. Providers publish notifications to announce data; the optional publishing section below is for them. You do not need to publish anything to listen.

First install the CLI and point at a server.

Set these to the URL and credentials supplied by your server operator:

export AVISO_BASE_URL=https://aviso.example
export AVISO_TOKEN=your-bearer-token

See what the server knows

aviso schema list

You get one event type per line. This lists notification schemas, not available datasets or access rights. You need permission to receive notifications.

These examples assume your operator has configured a small mars event type with the schema below. Check your server’s schema and adapt the event name and filters if it differs:

aviso schema get mars

Example response (JSON, with spacing compacted):

{
  "event_type": "mars",
  "schema": {
    "identifier": {
      "class": {
        "required": true,
        "type": "EnumHandler",
        "values": ["od", "rd"]
      },
      "step": {
        "range": null,
        "required": false,
        "type": "IntHandler"
      }
    },
    "payload": {"required": false}
  },
  "status": "success"
}

The schema tells you which labels, called identifiers, describe a notification and can be used as filters. Here, class is required in filters and must be od or rd (EnumHandler means a choice from a list). In this example, od means operational data. step is a whole number (IntHandler) used for forecast hours; you can omit it from filters. range: null sets no extra range limit. The server checks these values. The optional payload carries extra information, such as a file location, rather than labels to filter on.

Listen for live notifications

Select mars notifications whose class is od. Leaving out the optional step filter selects all forecast steps:

aviso listen --event mars --identifiers '{"class":"od"}'

On a first run, you will see matching new notifications as providers publish them. Silence can simply mean none have arrived. Press Ctrl+C to stop. Later runs resume from saved progress and may first deliver missed notifications.

If you have jq installed, show just the payload:

aviso listen --event mars --identifiers '{"class":"od"}' | jq -r '.payload'

When piped or redirected, output is one JSON object per line (NDJSON).

Replay history

To run through past notifications from a cursor (a sequence id or a date):

aviso replay --event mars --identifiers '{"class":"od"}' --from 2026-05-01
aviso replay --event mars --identifiers '{"class":"od"}' --from 1000

Replay reads retained history up to the boundary captured when the run starts. Notifications published after that boundary are not included. The date refers to notification publication time. Replace 1000 with a sequence id from your stream. Read more at Replay history.

Catch up, then keep listening

To read past notifications and then keep listening:

aviso listen --event mars --identifiers '{"class":"od"}' --from 2026-05-01

This replays retained matches, then waits for new ones. See all Configuration: --from formats.

Unlike replay, it saves progress. Run the same listener without --from to resume from where it stopped.

Run a production listener with a YAML file

To save your filters and log notifications, create my-listeners.yaml in your current directory:

listeners:
  - name: mars-od
    event: mars
    identifiers:
      class: od
    triggers:
      - type: log
        path: mars-od.log

aviso listen my-listeners.yaml

Matching notifications are appended to mars-od.log. Press Ctrl+C to stop. For more triggers and multiple listeners, see Listen with a YAML file.

Publish a notification

Optional, for providers with permission to publish. Using the schema above, announce an operational forecast at step 12:

aviso notify 'event=mars,class=od,step:=12,data={"location":"file:///data/forecast.grib"}'

Keep the comma-separated parameters inside single shell quotes. event=mars names the event type; class and step are its identifiers. class=od sends text. step:=12 uses := to send a JSON number, rather than the text "12" sent by step=12. Both are accepted by this schema’s integer validator, but := makes the number explicit in the request. Keep event= for the event name.

data= already parses JSON and supplies the payload; it does not need :=. The location here is an example file reference. Publishing sends a notification, not the file, and does not grant consumers access to it. An active matching listener receives the notification, including this payload.

For shell variables, use repeated --identifier arguments to keep each value in its own quoted argument. This works with notify, listen, and replay; see repeated identifiers for scripts.

For nested arrays and spatial identifiers, see Publish and listen.

See what configuration is in effect

aviso config dump --redact

This shows resolved settings and their sources. --redact masks tokens and passwords for sharing in an issue.

What next

• Publish and listen: the daily-use guide.
• Configuration: config files, environment variables, TLS.
• Troubleshooting: the common things that go wrong.

Publish and listen

For providers: use aviso notify to announce data or events.

For users: use aviso listen to receive matching notifications. Go straight to Listen; you do not need to publish anything first.

Schema assumptions

The following mars examples assume your server operator has installed this small schema, also used in the CLI quickstart. This is a server YAML configuration section, not a client listener file:

notification_schema:
  mars:
    topic:
      base: mars
      key_order: [class, step]
    identifier:
      class:
        type: EnumHandler
        values: [od, rd]
        required: true
      step:
        type: IntHandler
        required: false
    payload:
      required: false

Providers must include both class and step. In listener filters, class is required and step is optional: required: false applies to filters, not to publishing. The payload is optional and can carry a data location.

Use the connection and authentication settings from Configuration. Inspect your server with aviso schema get mars and adapt the examples if its schema differs. This command reads a schema; only the server operator configures one. See the server schema guide. The spatial and weather examples below state their own schema assumptions.

Publish

This section is for providers with permission to publish to the event type. aviso notify sends one notification to the server; it does not upload the data the notification describes.

aviso notify 'event=mars,class=od,step:=12,data={"location":"s3://bucket/path"}'

The single argument is a comma-separated list:

• event=<TYPE> is required. It names the event type.
• data=<JSON> supplies the notification’s payload. It is optional for this mars schema; other schemas may require it.
• Every other key=value pair lands in the identifier map.
• Use key:=JSON when an identifier must be a JSON scalar rather than a string.

Bare scalar values are sent as strings: step=12 sends "12", while step:=12 sends the JSON number 12. Both are accepted by this schema’s integer validator. Keep event= for the event name; data= already parses JSON. The := form also accepts other JSON values, but the server’s schema must allow the field and its value. If a string itself starts with [ or {, wrap the value in double quotes inside the outer shell quotes to keep it as text.

Repeated identifiers for scripts

Use one --identifier argument per field to pass shell variables without building a comma-separated parameter list or interpolating JSON:

MARS_CLASS=od
STEP=12
aviso notify 'event=mars,data={"location":"s3://bucket/path"}' \
  --identifier "class=$MARS_CLASS" --identifier "step:=$STEP"

event= and the optional data= stay in the required positional argument. Repeated identifiers supplement its identifier map. Duplicate keys, including keys already in that map, are errors. --identifier event=... and --identifier data=... are rejected; use the positional parameters for them.

For all three commands (notify, listen, and replay):

• --identifier key=value sends everything after the first = as an exact string. Commas, whitespace, literal quotes, backslashes, and later = or := sequences are preserved. JSON-looking strings are still strings.
• --identifier key:=JSON parses an explicit JSON value, including numbers, booleans, null, arrays, objects, and JSON strings. STEP above must contain valid JSON numeric text: 12 works, but 012 does not.
• Keys are trimmed and must not be empty. A colon immediately before the first = selects JSON syntax, so that form cannot express a string key ending in a colon. Other key syntax and supported values are checked by the server.
• Missing =, duplicate keys (even across the two forms), or invalid explicit JSON cause exit code 2 before a request is sent.

Double-quote the whole "class=$MARS_CLASS" argument. The shell expands the variable once; the CLI does not expand variables or evaluate shell code. Spaces, commas, quotes, literal dollar signs, and command-substitution text inside a variable stay data in that single argument. Do not use eval. The mars schema still restricts class to od or rd; arbitrary text needs a schema field that accepts it.

For structured values, put complete valid JSON in a variable and pass it as one quoted argument. Do not build JSON by inserting arbitrary strings between JSON quotes. This filter uses the weather schema:

SEVERITY_FILTER='{"gte":5}'
aviso listen --event weather --identifier date=20260913 \
  --identifier "severity:=$SEVERITY_FILTER" \
  --identifier 'anomaly:={"between":[40,50]}' \
  --identifier 'region:={"in":["north","south"]}' \
  --from 0 --no-state-store

With the five weather records below, this selects B and C.

Free-form string schema

For a literal-text example, the operator can install this synthetic server schema. The mars schema above does not have a label field.

notification_schema:
  text_example:
    topic:
      base: text_example
      key_order: [label]
    identifier:
      label:
        type: StringHandler
        required: true
    payload:
      required: false

LABEL='commas,"quotes",$HOME,$(false),back\slash=a:=b'
aviso notify event=text_example --identifier "label=$LABEL"
aviso replay --event text_example --identifier "label=$LABEL" --from 0

The quotes inside LABEL are literal characters. Neither $HOME nor $(false) inside its value is evaluated. The CLI sends the string as supplied; the server may canonicalise identifiers according to its handler rules. This example has no spaces because label forms part of the routing subject, and NATS subjects cannot contain whitespace.

Spatial schema assumptions

The observations examples assume the operator has installed the server’s point-cloud schema. It declares date (DateHandler, format %Y%m%d) and point_cloud (PointCloudHandler, at most 10,000 points), both required, plus a required payload. Providers send date, point_cloud, and data. Subscribers send date and a closed polygon instead of point_cloud.

Identifier values beginning with [ or { are parsed as JSON. This sends a point cloud as an array rather than a quoted JSON string:

aviso notify 'event=observations,point_cloud=[[46,8],[47,9]],date=20260601,data={"source":"stations"}'

A point has shape [latitude,longitude]. A polygon and a point cloud both use [[latitude,longitude],...]. Polygons need at least four pairs, with the first pair repeated last. Clouds do not need a closing repeat. The outer single quotes protect the argument from the shell. Do not add double quotes around the array.

Alternative coordinate format

The same observations listener can use a comma-separated polygon string instead of an array. Inside the JSON filter, keep the string in double quotes:

aviso listen --event observations \
  --identifiers '{"date":"20260601","polygon":"46,8,46,9,47,9,47,8,46,8"}'

This filter matches the cloud above because its points lie on the polygon’s boundary. The HTTP API also accepts point strings such as "46,8" in watch and replay filters where the schema supports them. Point clouds have no string format. Prefer arrays for spatial values; CloudEvent spatial identifiers are always arrays.

Identifier fields the server requires

Publishing requires every identifier field declared by the schema, even fields marked required: false for filters. If you omit one, the server rejects the notification with a helpful error.

To see what fields a schema asks for:

aviso schema get mars

What you see on success

When aviso notify succeeds, it prints the server’s response. In your terminal you get a human-readable line; piped to a file or another command, you get one line of compact JSON.

Listen

aviso listen opens a long-lived connection to the server and prints (or trigger-handles) each matching notification as it arrives.

There are two ways to set up a listener: a YAML file (for anything you care about), and inline flags (for quick exploration).

Listen with inline flags

aviso listen --event mars --identifiers '{"class":"od"}'

This runs one listener with a single echo trigger. Press Ctrl+C to stop.

Alternatively, use repeated identifiers with the same mars schema:

MARS_CLASS=od
STEP=12
aviso listen --event mars \
  --identifier "class=$MARS_CLASS" --identifier "step:=$STEP"

This selects class=od, step=12 and keeps listening for live notifications. Choose either --identifiers or repeated --identifier; combining them is an error. Either source requires --event, and --event requires one source. Omit all inline flags to use YAML or configured listeners. Inline mode takes precedence over those listeners, with one default echo trigger.

--identifiers takes a JSON object literal. Values may have any JSON shape:

aviso listen --event observations \
  --identifiers '{"date":"20260601","polygon":[[46,8],[46,9],[47,9],[47,8],[46,8]]}'

For observations, use the spatial schema assumptions above. Providers send point_cloud; subscribers send a closed polygon and the required date. A cloud matches when any point is inside or on the boundary.

For an empty identifier map (every notification of this event type), pass '{}'. The server may still require certain fields to be present, depending on the schema.

The inline mode runs with one default trigger: echo. For any other trigger, use a YAML file.

Listen with a YAML file

Write the listeners you want once, and run them on demand or under systemd:

# my-listeners.yaml
listeners:
  - name: mars-od
    event: mars
    identifiers:
      class: od
    triggers:
      - type: log
        path: /var/log/aviso/mars-od.log
      - type: webhook
        url: "{{ env.WEBHOOK_URL }}"
        headers:
          Authorization: "Bearer {{ env.WEBHOOK_TOKEN }}"

  - name: mars-rd
    event: mars
    identifiers:
      class: rd
    triggers:
      - type: command
        command: "./on-mars.sh {{ notification.identifier.step }}"

Run them:

aviso listen my-listeners.yaml

The CLI spawns one task per listener and runs them concurrently. Each listener resumes independently from the state file.

A full reference for the file format is at Listener YAML.

Triggers, briefly

A trigger is the action aviso takes for each matching notification. Six kinds are built in:

• echo prints the notification.
• log appends it to a file.
• command runs a shell command (Unix only).
• webhook makes an HTTP request to a URL of your choice.
• teams posts to a Microsoft Teams channel.
• post forwards the original event envelope.

You can attach as many triggers as you want to a listener. They run in declaration order.

What aviso listen prints

On a TTY, the echo trigger prints a multi-line pretty JSON block per notification with a one-line header. When the output is piped to a file or another command, it switches to one compact JSON object per line, so aviso listen | jq and aviso listen >> notifications.ndjson both work.

Other triggers write to their own destinations (a file, a webhook, a shell command); the CLI itself stays quiet on stdout for those.

Stopping

Ctrl+C drains in-flight work and exits. A second Ctrl+C within five seconds exits immediately (return code 130).

Resuming

When you stop and restart aviso listen against the same server and identifiers, it resumes from the last notification it fully processed. The cursor lives in ~/.config/aviso/state.json by default. For a one-off run that does not write to the file, pass --no-state-store.

To start from an explicit point (a sequence id or a date) just for this run:

aviso listen my-listeners.yaml --from 2026-05-01
aviso listen my-listeners.yaml --from 1000

The full rules for --from (pure-digit input is always a sequence id, dashes mean a date, and so on) live in Configuration.

Listening for several event types at once

Put multiple listeners in the same YAML file (or in separate files; the CLI accepts a list). For example, save the mars and observations filters above in listener files named mars.yaml and observations.yaml:

aviso listen mars.yaml observations.yaml

Each listener has its own request, its own resume cursor, and its own triggers. A failure in one does not stop the others. Listeners share connections to the server, up to 64 on each.

Worked example: weather constraints

This synthetic example uses no external data services. You need a test server whose operator has installed the following schema in its server configuration. This is server YAML, not a client listener file. It declares the complete weather event type; it is not a schema shipped on every server.

The operator adds this block to the server configuration; see the schema guide. The client can inspect a schema, but aviso schema get does not install one.

notification_schema:
  weather:
    topic:
      base: weather
      key_order: [date, severity, anomaly, region]
    identifier:
      date:
        type: DateHandler
        required: true
        canonical_format: '%Y%m%d'
      severity:
        type: IntHandler
        required: false
        range: [0, 10]
      anomaly:
        type: FloatHandler
        required: false
        range: [-100, 100]
      region:
        type: EnumHandler
        required: false
        values: [north, south, west]

Set AVISO_BASE_URL in both terminals to your test server’s address, using the connection and authentication settings from Configuration. For example, http://127.0.0.1:8000 is only a placeholder for a locally running server; it is not a hosted service. Inspect the installed schema before running the example:

aviso schema get weather

All four fields are required when publishing. Only date is required in a filter; omitting an optional filter field accepts all its values. Each seed below has a distinct combination of routing identifiers, so the records do not replace one another on a backend that retains only the latest record per subject. Use a fresh test stream to get exactly the results shown.

Start the listener first

In the first terminal, run:

aviso listen --event weather \
  --identifiers '{"date":"20260913","severity":{"gte":5},"anomaly":{"between":[40,50]},"region":{"in":["north","south"]}}' \
  --from 0 --no-state-store

Leave it running, then publish in the second terminal. --from 0 reads retained records after sequence zero and continues with live notifications, without reading or writing a saved cursor. On this fresh test stream, seeds published before or during connection setup are still included; there is no readiness message to wait for. This cannot recover records removed by retention.

The filter means severity at least 5, anomaly from 40 through 50 inclusive, and region either north or south. See Filters for the operator rules.

Publish five records

In the second terminal, run these commands in order:

aviso notify 'event=weather,date=20260913,severity:=3,anomaly:=39.5,region=north,data={"id":"A"}'
aviso notify 'event=weather,date=20260913,severity:=5,anomaly:=40,region=NORTH,data={"id":"B"}'
aviso notify 'event=weather,date=20260913,severity:=6,anomaly:=42.5,region=south,data={"id":"C"}'
aviso notify 'event=weather,date=20260913,severity:=7,anomaly:=50,region=west,data={"id":"D"}'
aviso notify 'event=weather,date=20260913,severity:=8,anomaly:=50.5,region=south,data={"id":"E"}'

severity:=5 sends a JSON number; severity=5 sends a string. These commands use concrete numbers, not constraint objects. data={"id":"B"} is the payload label used to recognise a record, not a filter or the server’s notification ID. The single quotes protect each complete argument from the shell.

The listener prints two notifications, with payload.id values B then C. Press Ctrl+C to stop it. To read the same retained records again, use replay with this filter. To keep the filter in a file, use the YAML equivalent.

What next

• Replay history: re-read past notifications.
• Configuration: config files, environment variables, TLS.
• Triggers overview: pick the right trigger.
• Troubleshooting: the usual snags.

Replay history

aviso replay re-reads past notifications and runs them through your triggers, just like aviso listen does for live ones. The difference: replay always starts from a cursor you supply, ends at a fixed history boundary or at an end point you supply with --until, and never touches the state file.

Use it when:

• You want to backfill a new downstream system with what already happened.
• You missed a window of notifications and want to re-process them.
• You are debugging a listener and need to feed it past traffic for repeatable runs.

A first replay

These examples assume your server operator has installed the same small mars schema used in Publish and listen. This is server YAML, not a client listener file:

notification_schema:
  mars:
    topic:
      base: mars
      key_order: [class, step]
    identifier:
      class:
        type: EnumHandler
        values: [od, rd]
        required: true
      step:
        type: IntHandler
        required: false
    payload:
      required: false

In filters, class is required and step is optional. The integer step has no configured range, and the payload is optional. Use the connection and authentication settings from Configuration, then inspect the installed schema:

aviso schema get mars

This command only reads the schema; the operator configures it. Adapt the filter if your server’s schema differs. Replay reads notifications already published by providers. You do not need to publish your own; for test history, see the publish example.

aviso replay --event mars --identifiers '{"class":"od"}' --from 2026-05-01

This selects stored mars notifications with class=od, with no restriction on step. The date selects publication time from midnight UTC on 1 May 2026, not a date in the notification’s metadata. Replay prints matching retained notifications and stops at the history boundary captured when the run starts. It does not wait for new notifications.

Retention limits what is available, and a server replay cap can stop a run before catch-up completes. See the server’s historical replay limits. An empty matching history prints no notifications.

--from takes either a sequence id or a date. The rules are the same as for aviso listen --from; full list at Configuration: --from formats.

You can also save this client listener as my-listeners.yaml. Its echo trigger prints each matching notification:

listeners:
  - name: mars-od
    event: mars
    identifiers:
      class: od
    triggers:
      - type: echo

aviso replay --from 0 my-listeners.yaml

--from 0 reads retained history after sequence zero. To resume from a known notification, replace 0 with its actual sequence id; only later sequences are selected. If a file defines several listeners, select one by name:

aviso replay --from 0 --listener mars-od my-listeners.yaml

Stop at an end point

--until ends the replay at an end point instead of at the history boundary. It takes the same forms as --from: a sequence id is the last one delivered, inclusive, and a date ends with the last notification published at or before that time.

aviso replay --event mars --identifiers '{"class":"od"}' \
  --from 2026-05-01 --until 2026-05-02

This prints the matching notifications published from midnight UTC on 1 May 2026 up to and including midnight UTC on 2 May, and stops. A date without a time means midnight UTC. The start is exclusive and the end inclusive for sequence ids: --from 10 --until 20 prints the matching notifications with sequences 11 to 20. The banner shows both ends. A replay also stops at the history boundary, so an end point in the future ends there.

A sequence --until that is not greater than a sequence --from is refused before anything is sent, with exit code 2, since the replay would print nothing. --until needs aviso-server 0.13.0 or later; an older server rejects the request with HTTP 400.

Repeated identifiers

For shell scripts, pass each identifier as a separate argument:

MARS_CLASS=od
STEP=12
aviso replay --event mars \
  --identifier "class=$MARS_CLASS" --identifier "step:=$STEP" --from 0

This reads retained mars records with class=od and step=12. key=value preserves the exact string; key:=JSON parses a typed value. See scripting rules for quoting and validation. Choose repeated --identifier or one --identifiers JSON object; the two sources conflict. Either requires --event, which requires a source. Inline arguments take precedence over YAML and --listener, with a default echo trigger.

Replay does not write the state file

The state file (~/.config/aviso/state.json) is for aviso listen only. Replay never reads or writes it.

The reason: a replay run shares the same resume key as the equivalent listen run, and letting replay update the cursor could push the listen cursor past notifications the listen has not actually processed. To keep the at-least-once delivery guarantee, replay stays stateless by design.

The trade-off: if you interrupt a replay, the next replay needs an explicit --from to resume. There is no “resume my replay” mode.

--identifiers accepts structured JSON values just like aviso listen. Quote the whole object for the shell, but leave arrays unquoted inside it.

The following assumes the operator has installed the server’s point-cloud schema, also used in Publish and listen. Its date is required (DateHandler, format %Y%m%d). Providers publish the required point_cloud array and payload; replay filters supply date and a closed polygon array instead of point_cloud. Coordinates are [latitude,longitude], with the first pair repeated last to close the polygon.

aviso replay --event observations \
  --identifiers '{"date":"20260601","polygon":[[46,8],[46,9],[47,9],[47,8],[46,8]]}' \
  --from 2026-05-01

A cloud matches when any point lies inside or on the polygon’s boundary.

Replay the weather example

After publishing the five records in the weather tutorial, reuse exactly the same identifier filter:

aviso replay --event weather \
  --identifiers '{"date":"20260913","severity":{"gte":5},"anomaly":{"between":[40,50]},"region":{"in":["north","south"]}}' \
  --from 0

The same filter can be supplied as repeated arguments instead:

aviso replay --event weather --identifier date=20260913 \
  --identifier 'severity:={"gte":5}' \
  --identifier 'anomaly:={"between":[40,50]}' \
  --identifier 'region:={"in":["north","south"]}' --from 0

On the fresh test stream either form prints payload.id values B and C, then exits. Do not combine the two identifier sources in one command. --from 0 reads retained history after sequence zero; it cannot recover records that the backend no longer retains. The wire filter is the same object used by listen, with JSON numbers inside the constraint objects. The operator rules are shared by both commands.

Replay vs listen

When you want both

To read retained history and continue with new notifications, use listen with --from and the same schema and filter:

aviso listen --event mars --identifiers '{"class":"od"}' --from 2026-05-01

Press Ctrl+C to stop. Listen records progress in its state file. Running replay and then starting a separate listener without --from or saved state can leave a gap: that listener starts at the server’s current tip, after replay’s fixed boundary. Seeding a state file separately is not an exact-handover guarantee.

What next

• Publish and listen: the live equivalent.
• State file: what listen writes and how to edit it.

Operations

The supporting commands: schema inspection, destructive admin, configuration introspection, shell completions.

Schemas

The server publishes a schema per event type, describing which identifier fields exist, which are required, and what types they hold. Two commands let you look at them.

List event types

aviso schema list

On a terminal you get a header line and a bullet list of event types. When piped (or with --json), each entry comes out as a JSON object, one per line:

aviso schema list | jq -r .event_type

Get one schema

aviso schema get mars

You get the schema as pretty JSON. Use it to discover which identifiers the server insists on when publishing or filtering.

To fetch every schema in one command:

aviso schema list | jq -r .event_type | xargs -I{} aviso schema get {}

aviso does not validate notifications against schemas locally. The server is the single source of truth; these commands are for human discovery.

Admin

Three destructive commands sit under aviso admin. They all require a --yes flag on the command line; the flag cannot be set in the configuration file, by design.

Wipe one event-type stream

aviso admin wipe-stream mars --yes

Deletes every notification of type mars on the server. Useful in test environments. Operator-level credentials required.

Wipe everything

aviso admin wipe-all --yes

Deletes every notification of every type. Useful when you want a completely clean slate.

Delete a single notification

aviso admin delete 'mars@42' --yes

The argument is the notification id (the <event_type>@<sequence> form the server emits).

Configuration introspection

aviso config dump --redact

Prints the resolved configuration to stdout with a comment on each line saying where the value came from (flag, env, file, or default). --redact masks tokens and passwords.

The dump is what aviso would use right now, given your current flags, environment, and config file. It is the fastest way to debug “why is aviso not picking up my setting”.

For JSON output (so you can jq it):

aviso config dump --redact --json

The auth block is summarised rather than printed per-field. In the YAML form, provider is <set>, <set; redacted> with --redact, or <unset>. In the JSON form the same fact is the boolean provider_set, alongside a redacted boolean. source names where the credential came from (flag, environment, config file, or credentials file); an absent source is <unset> in YAML and null in JSON. Use source when the credential in use is not the one you expected. The listeners block is summarised by name, event, identifier count, and trigger count.

Shell completions

aviso completions <shell> prints a completion script for bash, zsh, fish or elvish. Where to save it, and what to do when Tab does nothing afterwards, is covered in Install: shell completions.

Exit codes

What next

• Configuration: where settings come from and how to override them.
• Troubleshooting: the common things that go wrong.

Configuration

How aviso decides what server to talk to, how to authenticate, what TLS settings to use, and where to keep state.

Tell aviso where the server is

The minimum aviso needs is a server URL and (usually) credentials. You have three ways to supply each one. They are checked in this order:

1. Command-line flag (--base-url, --token, …).
2. Environment variable (AVISO_BASE_URL, AVISO_TOKEN, …).
3. Config file (default ~/.config/aviso/config.yaml).

A flag beats an env var beats a config file. Layering is per-field: passing --base-url does not blank out a file-set auth.bearer_token.

To see what aviso actually resolved, run aviso config dump --redact.

The base URL must use http or https and point to the Aviso service, including any reverse-proxy path prefix. A website or login page is not a stream endpoint.

Listener startup timeout

aviso listen prints Connecting first. It prints Listening for each listener only after the server confirms an Aviso stream. No matching notification is needed: a confirmed stream can be healthy and idle.

--startup-timeout <DURATION> limits the initial connection and retries to 30 seconds by default. This gives transient failures time to recover while keeping a failed startup bounded. To change that budget for configured listeners:

aviso listen --startup-timeout 60s

Use --startup-timeout 0s to disable the initial budget. This listen-only flag has no YAML key or environment variable. It stops applying after the first confirmed handshake and does not restart on reconnect. Each connection attempt still has a separate ten-second deadline for response headers and the Aviso opening event. Missing it stops the listener only before the first confirmed handshake; after that, the reconnect is retried. Heartbeats and unrelated SSE events do not confirm startup.

Retry status goes to stderr at INFO level, with a listener name, cause, and delay. Repeated retries are coalesced to at most one message every five seconds. Notifications keep their configured trigger output. Ctrl+C while connecting stops the listener normally. A failed listener makes the eventual command exit with status 1; other listeners keep running.

The configuration file

# ~/.config/aviso/config.yaml

base_url: "https://aviso.example"

auth:
  bearer_token: "your-token-here"
  # Or use basic auth instead:
  # basic:
  #   username: "alice"
  #   password: "secret"

# Optional, with sensible defaults if omitted:
heartbeat_interval: 30s
state_file: "/path/to/state.json"

tls:
  ca_bundle:
    - "/path/to/internal-ca.pem"
  danger_accept_invalid_certs: false

listeners:
  - name: mars-od
    event: mars
    identifiers:
      class: od
    triggers:
      - type: log
        path: /var/log/aviso/mars-od.log

To point at a config file in another location, use --config <PATH> or set AVISO_CLIENT_CONFIG_FILE.

The optional YAML timeout is the total time allowed for an ordinary request, such as notify, schema or an admin command, response body included. It is unset by default. It does not apply to listeners, whose stream is meant to stay open; use --startup-timeout to bound how long a listener may take to start.

Environment variables

Authentication

aviso supports anonymous access (no Authorization header), HTTP Basic, and Bearer. It looks for a credential in four places and stops at the first one that has it:

The flags are the least safe of the four. A command line is visible to every local user in the process list and is kept in the shell history, so --token and --password belong to one-off tests, not to scripts or service definitions. aviso logs one WARN line, cli.auth.on_command_line, when a credential arrives this way. Use the environment variables or the credentials file instead.

Once an earlier source supplies a credential, the auth: block of the config file and the credentials file are not interpreted, so a stale entry in either cannot fail a command that was not going to use it. The config file itself is still parsed for its other settings, and a YAML error there is reported regardless. With nothing in any of the four, aviso connects anonymously.

The winning source decides the provider: the environment builds an Env, the credentials file a ConfigFile, and a flag or the config-file auth: block a Bearer or a Basic depending on which credential you set. Those names appear in logs and in the library API; see Authentication providers for what each one does.

The credentials file

When nothing else supplies a credential, aviso reads ~/.config/aviso/credentials.yaml. Set AVISO_CREDENTIALS_FILE to use a different path. The file holds one credential and nothing else:

# ~/.config/aviso/credentials.yaml
bearer:
  token: your-bearer-token

Or, for Basic authentication:

basic:
  username: your-username
  password: your-password

This file is meant for tools that fetch a token and write it out. It is read last, so a credential you set with a flag, in the environment, or in the auth: block of the config file is used instead. A missing file is fine. A file that exists but cannot be read is an error, so a typo is reported rather than ignored.

The credentials file is also the only source that is reread after a 401. A tool that refreshes the token in place therefore reaches a running aviso listen without a restart.

A credential from the environment or either file is not sent to a plain http:// address unless it is loopback. Use an https address, or pass the credential on the command line with --token, or --username and --password, to say you mean it. This applies when a command makes a request; config dump still reports the source it would have refused. A credential you named that goes to a non-loopback http:// address is sent, with one WARN line, client.auth.plaintext, the same way --danger-accept-invalid-certs is announced.

To see which source is in use:

aviso config dump | grep -A2 '^auth:'

On a 401, aviso retries once

If the server returns 401 Unauthorized, aviso asks the auth provider to refresh and retries the request once. For static credentials (bearer, basic) the refresh is a no-op; for providers backed by an OAuth or OIDC cache, the refresh rotates the token. A second 401 in the same attempt cycle is surfaced as an error.

The state file

Each successful listener run records its cursor in ~/.config/aviso/state.json. On restart, the listener resumes from the next sequence so it does not skip ahead. A notification can still be redelivered after a crash or failed checkpoint.

Change the location:

state_file: "/var/lib/aviso/state.json"

or:

aviso --state-file /var/lib/aviso/state.json listen ...

Disable persistence for one run:

aviso listen --no-state-store ...

The file is for aviso listen only. aviso replay does not touch it.

For the file format, edit safety, and how to genuinely reset a cursor, see State file.

--from value formats

Both aviso replay --from <VALUE> (required) and aviso listen --from <VALUE> (optional, overrides the listener’s defaults) accept these forms, tried in order:

1. Pure digits → sequence id. 42, 1234567.
2. YYYY-MM-DD → midnight UTC. 2026-05-01.
3. "YYYY-MM-DD HH:MM" (quotes required) → UTC. "2026-05-01 14:30".
4. "YYYY-MM-DD HH:MM:SS" (quotes required) → UTC.
5. YYYY-MM-DDTHH:MM:SS (T separator) → UTC.
6. YYYY-MM-DDTHH:MM:SSZ (T separator with Z) → UTC.
7. YYYY-MM-DDTHH:MM:SS.ffffffZ (with microseconds and Z) → UTC.

The pure-digit case is always a sequence id, never a date. 20260601 is sequence id 20260601, not 1 June 2026. To pass a date, use the dashed form (2026-06-01).

aviso replay --until <VALUE> accepts the same forms. There, a sequence id is the last one delivered, inclusive; see Stop at an end point.

How --from interacts with the state file

On aviso listen, when you pass --from <VALUE> and the state file already has a cursor for the listener:

• aviso uses your --from for the initial seek.
• As the rewind delivers notifications, the state file ignores updates whose sequence is at or below what is already on disk. Your --from cannot regress the cursor.
• Once the run advances past the previous high-water mark, normal updates resume.
• Restarting without --from honours the state file again.

Use --from as a one-shot rewind. Leaving it in a systemd unit means redelivery from that point on every restart.

Logging verbosity

Useful recipes for the env var:

AVISO_LOG=warn,aviso=debug              # aviso details, everything else quiet
AVISO_LOG=h2=debug,hyper=debug,aviso=debug  # also see HTTP transport

Color

--color auto|always|never. The default is never. The auto mode emits color when the target stream is a TTY and NO_COLOR is unset. always overrides NO_COLOR.

Color only ever applies to human-readable output. JSON output (piped or redirected) is always plain.

TLS

aviso talks HTTPS by default and uses the system trust store. Two flags adjust validation when that is not enough.

Trust an internal CA

When your aviso-server is fronted by a TLS endpoint whose certificate is signed by an internal certificate authority (a corporate root, a self-hosted ACME, a private cluster), point aviso at the CA file:

aviso --base-url https://aviso.internal.example.org --ca-bundle ~/.config/aviso/internal-ca.pem schema list

Or in the config file:

tls:
  ca_bundle:
    - internal-ca.pem

A relative path here is resolved against the config file’s own directory, so this entry means ~/.config/aviso/internal-ca.pem wherever you run aviso from. A relative --ca-bundle on the command line is resolved against the working directory, as you would expect of a flag.

The --ca-bundle flag is repeatable, so you can pass intermediate and root certificates separately (or put them all in one PEM file). The system trust store stays in effect; --ca-bundle only adds.

To fetch the CA’s certificate from a running server (for inspection or for use here):

openssl s_client -connect aviso.internal.example.org:443 -showcerts < /dev/null 2>/dev/null \
  | sed -n '/-----BEGIN CERTIFICATE-----/,/-----END CERTIFICATE-----/p' \
  > internal-ca.pem

openssl x509 -in internal-ca.pem -noout -subject -issuer

Bypass TLS validation (insecure)

For short-lived development against a self-signed certificate when shipping the CA file is impractical:

aviso --base-url https://localhost:8443 --danger-accept-invalid-certs schema list

aviso logs a WARN at every startup when this is set, so log scrapers can flag misuse. Do not use this in production.

The recommended order: try the system trust store first, fall back to --ca-bundle, use --danger-accept-invalid-certs only as a last resort during development.

What next

• Listener YAML reference: the file format the CLI reads.
• State file reference: annotated example, edit safety.
• Authentication providers: when to use which one.

Troubleshooting

Choose the symptom that matches what you see. Open a panel for checks and links to the relevant reference.

aviso listen --from 2026-06-01

error: no listeners to run

error: client error (Connect): invalid peer certificate: ...

... WARN cli.tls.insecure_mode: TLS certificate validation disabled by --danger-accept-invalid-certs ...

mkdir -p /var/log/aviso

error: aviso admin wipe-all requires --yes

aviso admin wipe-all --yes

How to file a useful issue

Every server response carries an X-Request-ID header. The same UUID appears in aviso’s tracing events as request_id. Quote it when reporting an issue against aviso-server or aviso-client.

If you can, attach the output of aviso config dump --redact (which masks tokens and passwords). It is the fastest way for someone else to see what aviso thinks it is configured with.

Python

Use pyaviso to receive Aviso notifications in your Python scripts. For example, your script can wait until a dataset is ready, then start processing it.

For users: listen for notifications or replay past ones. You do not need to publish anything yourself.

For notification providers: publish notifications to tell users that data or an event is available. Publishing requires permission on the server.

What you can do

• See what is available: discover the server’s notification types and their filter fields.
• Listen for updates: receive notifications matching the data you care about.
• Read past notifications: replay available history.
• React to a notification: run your Python code, write a log, or call another service.

Providers can also publish notifications from Python. A notification can include a file location or other useful information; publishing it does not transfer the file.

Start here

1. Install pyaviso.
2. Follow the Python quickstart to connect to a server, inspect its schema and start listening.

You will need your Aviso server’s address and, if required, credentials. The server’s schemas determine which notification types and filters you can use.

When you need more

• Listening: filters and reading notifications.
• Publishing: sending notifications as a provider.
• State and resume: remembering progress between runs.
• Triggers: running actions for matching notifications.
• Authentication and Troubleshooting: connection and access help.
• API reference: details of the available methods.

If your application already uses Python’s asyncio, see Async. Otherwise, start with the regular client used in the quickstart.

Install

Use Python 3.10 or newer. Install into the Python environment where you will run your scripts or notebook kernel.

From PyPI

pip install pyaviso

Wheels ship for Linux (manylinux, x86_64 and aarch64) and macOS (universal2). No Rust toolchain is needed; the compiled extension comes inside the wheel.

Verifying the install

python -c "import pyaviso; print(pyaviso.__version__)"

It prints the installed package version. This checks the import, not a connection to an Aviso server.

The bundled aviso command

Installing pyaviso also puts the aviso command-line tool on your PATH, so a single pip install gives you both the importable library and the CLI:

aviso --version

It is the same aviso command-line tool documented in the CLI section. The wheel installs it as a console script that runs the Rust CLI in-process through the extension (rather than shipping a separate compiled binary), so you do not need a cargo install. Pick whichever install path you prefer: pip install pyaviso and cargo install aviso-cli give you the same aviso command and behaviour.

From source

To build a checkout locally, including when contributing:

git clone https://github.com/ecmwf/aviso-client.git
cd aviso-client
uv venv
uv sync --locked --group dev
uv run maturin develop --release --locked

The --group dev flag pulls in maturin, ruff, ty, pytest, and the other dev tools alongside the runtime dependencies. --locked on both commands keeps the install reproducible from the committed uv.lock and Cargo.lock. The second command builds the Rust extension into the local virtualenv so import pyaviso works. The first build pulls the workspace’s Rust dependencies and compiles them; subsequent builds are incremental.

For a source build you need:

• Rust toolchain (rustup).
• uv (install instructions).
• A C compiler and linker on the path. macOS uses the Apple toolchain; on Linux the system gcc or clang is fine.

Python version

pyaviso targets Python 3.10 and newer. The extension is built with abi3-py310, so a single wheel works across every supported Python version on the same platform.

What next

• Quickstart shows how to discover schemas, listen for notifications, and replay history.
• Overview is the page-by-page guide to what the package gives you.

Quickstart

Use Python to receive notifications from data providers. Start by checking what your server offers, then listen for new notifications or replay past ones. You do not need to publish anything to listen.

Set the environment

You need Python 3.10 or newer and pyaviso installed in your Python environment. Ask your server operator for a server URL and credentials with permission to receive notifications.

Set these in your terminal, replacing the example values with yours:

export AVISO_BASE_URL=https://aviso.example.org
export AVISO_TOKEN=your-bearer-token

The scripts create the client with no arguments; it reads the address and the credential from these variables. If you have a username and password instead, unset AVISO_TOKEN and set AVISO_USERNAME and AVISO_PASSWORD. A token takes precedence when both are set. With neither set, the client looks in ~/.config/aviso/config.yaml and ~/.config/aviso/credentials.yaml, and requests go out anonymous only if those have no credential either. The first script prints what the client resolved, so you can check it picked up what you meant. See Configuration for where settings come from, and Authentication for naming a credential in code.

What is on your server

The server operator configures event types, each with a schema describing its notifications. The examples below use the same small mars schema as the CLI quickstart. Your server may have different event types or a different mars schema.

Save this as discover.py and run python discover.py in the terminal where you set the environment variables. It lists event types, then prints the schema for mars. If mars is absent, use a listed name and run again.

import json
import pyaviso

client = pyaviso.AvisoClient()
print(client.config)
print(client.schema().event_types)
print(json.dumps(client.schema_for("mars").as_dict(), indent=2, sort_keys=True))

On a server configured with only this example schema, the output starts with the resolved configuration (your paths and address will differ), then:

ResolvedConfig(
    base_url='https://aviso.example.org/'            (environment AVISO_BASE_URL),
    auth="bearer"                                    (environment AVISO_TOKEN or AVISO_USERNAME),
    timeout=None                                     (default),
    heartbeat_interval=None                          (default),
    ca_bundle=[]                                     (default),
    danger_accept_invalid_certs=False                (default),
)
['mars']
{
  "event_type": "mars",
  "schema": {
    "identifier": {
      "class": {
        "required": true,
        "type": "EnumHandler",
        "values": [
          "od",
          "rd"
        ]
      },
      "step": {
        "range": null,
        "required": false,
        "type": "IntHandler"
      }
    },
    "payload": {
      "required": false
    }
  },
  "status": "success"
}

The list names configured schemas, not available datasets or access rights. as_dict() makes the schema response printable as JSON.

Filters

Identifiers are labels you can filter on. Here, class must be od or rd (EnumHandler means a choice from a list). In this example, od means operational data. step is a whole number (IntHandler) for forecast hours; range: null adds no range limit.

required: true means a field must appear in a filter. You can leave out step to receive all steps. Publishing is different: a provider must supply every identifier field, including step. The optional payload carries extra information, such as a file location, rather than labels to filter on.

Use your server’s schema to adapt the event name and filters below. You do not need to configure a server schema to receive notifications from an existing service.

Listen for notifications

Save this as listen.py and run python listen.py in the same terminal. It selects mars notifications whose class is od, at any forecast step:

import pyaviso

client = pyaviso.AvisoClient()
for notification in client.listen("mars", filter={"class": "od"}):
    print(notification.payload)

The script waits for matching new notifications and prints each payload. Silence can simply mean none have arrived. For a notification carrying a file location, you would see:

{'location': 'file:///data/forecast.grib'}

Notifications with class=rd do not match. Press Ctrl+C to stop. This script does not save progress: restarting it waits for new notifications again.

Replay past notifications

To read retained history, replace the for loop in listen.py with this loop, keeping the imports and client initialization above it. Run python listen.py again:

for notification in client.listen(
    "mars", filter={"class": "od"}, start_from=0, mode="replay_only"
):
    print(notification.payload)

start_from=0 starts from the beginning of retained history. mode="replay_only" makes the script end when it catches up, rather than wait for new notifications. It prints matching payloads in sequence order. No output means no retained notifications match. Running it again reads the same retained history; it does not save a position.

Resume across restarts

For a listener that remembers its position, see State and resume. For more filters and replay options, see Listening.

What about async?

Use the regular client above for a simple script. If your application already uses asyncio, see Async for complete examples.

Publish a notification (optional, for providers)

You need permission to publish. With the schema above, save this as publish.py and run python publish.py to announce an operational forecast at step 12:

import pyaviso

client = pyaviso.AvisoClient()
response = client.notify(
    event_type="mars",
    identifier={"class": "od", "step": 12},
    payload={"location": "file:///data/forecast.grib"},
)
print(response.status)

It prints success when the server accepts the notification. Both class and step are supplied, even though step is optional in filters. The location is an example reference: publishing sends the notification, not the file, and does not grant access to the file.

An active matching listener receives this payload. To try it yourself, leave the live version of listen.py running and publish from another terminal with the same environment setup. A publish sent before the listener connects can be read with the replay loop. See Publishing for more options.

Configuration

A client needs a server address and, usually, a credential. Both can be passed in code. On a machine where the aviso command is already configured, they are defined once, in the environment or in ~/.config/aviso/config.yaml, and scripts need not repeat them. Every constructor argument is therefore optional, and any argument that is omitted is looked up:

import pyaviso

client = pyaviso.AvisoClient()
print(client.schema().event_types)

This page describes where each setting is read from, in which order, and how to inspect the configuration a client resolved.

Order of precedence

For each setting, the client uses the first source that provides a value:

The config file is ~/.config/aviso/config.yaml, or the file named by AVISO_CLIENT_CONFIG_FILE. The credentials file is ~/.config/aviso/credentials.yaml, or AVISO_CREDENTIALS_FILE. A missing file sets nothing; a file that exists but cannot be read raises pyaviso.ConfigError. Sections intended for the aviso command, such as listeners, are ignored.

The aviso command uses the same order, with its command-line options taking precedence, so a script and the command on the same machine use the same server and the same credential. Two consequences follow:

• The environment can change where a script connects. An AVISO_BASE_URL set in the shell determines where AvisoClient() connects. A script that must always use one server should pass base_url=.
• A discovered credential is protected. A credential read from the environment or a file is not sent to a plain http:// address unless the host is loopback; the client raises pyaviso.AuthError instead. Because the credential was not named in code, a mistyped host would otherwise receive it unencrypted. Passing auth= explicitly removes this restriction. See Authentication for details.

AvisoClient.from_file(path) is the same lookup with a named config file in place of the default one; that path must exist. AsyncAvisoClient takes the same arguments and follows the same order.

Inspecting the resolved configuration

When a connection fails, the first question is which server and which credential the client is using. Every client reports this:

import pyaviso

client = pyaviso.AvisoClient()
print(client.config)

ResolvedConfig(
    base_url='https://aviso.example.org/'            (environment AVISO_BASE_URL),
    auth="bearer"                                    (credentials file /home/me/.config/aviso/credentials.yaml),
    timeout=30.0                                     (config file /home/me/.config/aviso/config.yaml),
    heartbeat_interval=None                          (default),
    ca_bundle=[]                                     (default),
    danger_accept_invalid_certs=False                (default),
)

Each line shows a setting, its value and its source. The report contains no secrets: the credential is described by its kind and source, never by its value, and any user:password@ is removed from the address. The report can therefore be included as it is in a support request or a log.

The fields are also available as objects:

url = client.config.base_url
if url is not None:
    print(url.value, "from", url.source)

if client.config.auth is None:
    print("no credential found: requests are anonymous")

source is one of code, environment <NAME>, config file <path>, credentials file <path> or default. auth is None when no source had a credential; auth=pyaviso.Anonymous() is instead reported as kind anonymous from code, since that was an explicit choice. client.config.as_dict() returns the same information as plain values, for structured logging.

Inspecting the configuration without a client

pyaviso.resolve_config() produces the same report without creating a client. It takes the constructor arguments that take part in the lookup (base_url, auth, timeout, heartbeat_interval and danger_accept_invalid_certs; not user_agent, state_store or flush_cursor_on_exit, which are never looked up) and works even when a client could not be built:

import pyaviso

config = pyaviso.resolve_config()
if config.base_url is None:
    print("no server address in code, AVISO_BASE_URL or the config file")
elif config.auth is not None and config.auth.refused:
    print("credential found but not sent:", config.auth.refused)
else:
    print(config)

The second case is a common source of confusion: a credential is configured, yet AvisoClient() raises AuthError. The report shows the credential and the reason the client refuses to use it, for example:

    auth="bearer"                                    (config file /home/me/.config/aviso/config.yaml; refused: http://aviso.internal.example.org is plain http on a host that is not loopback, so the client will not be built. Use https, or name the credential in code to send it anyway.),

resolve_config() raises pyaviso.ConfigError when the config file or the credentials file exists but cannot be read, and pyaviso.AuthError when a credential source is present but unusable, such as AVISO_USERNAME with no AVISO_PASSWORD; that is the same point at which AvisoClient() would fail. All other conditions are reported in the returned object.

Setting values in code

Any value passed to the constructor is used as given and reported with the source code:

client = pyaviso.AvisoClient(
    base_url="https://aviso.example.org",
    auth=pyaviso.Bearer(token),
    timeout=10,
)

Here the address and credential are fixed regardless of the machine’s configuration, while heartbeat_interval and the TLS settings are still read from the file if it sets them. To send no credential even when one is configured on the machine, pass auth=pyaviso.Anonymous().

The aviso command

aviso config dump prints the same kind of report for the command, including the command-line flags the library does not have. See CLI configuration.

Publishing

Providers publish notifications to announce data or events. You need credentials with permission to publish to the event type. Publishing sends a notification, not the file it describes, and does not grant access to that file. Users who only want to receive notifications can go to Listening.

Discover what each event type requires

The server operator owns the schemas. The client can inspect them, but cannot install one. These examples use the same small mars schema as the quickstart. Your server may differ.

Start with pyaviso installed in your Python environment. Set AVISO_BASE_URL and either AVISO_TOKEN or AVISO_USERNAME/AVISO_PASSWORD, as in Set the environment. pyaviso.Env() requires credentials and prefers the token when both are set. For an anonymous server, pass auth=pyaviso.Anonymous() instead.

Save this as discover.py and run python discover.py. It lists event types and prints the complete schema response for mars. If mars is absent, use a listed name and run again:

import json
import os

import pyaviso

client = pyaviso.AvisoClient(
    base_url=os.environ["AVISO_BASE_URL"], auth=pyaviso.Env()
)
print(client.schema().event_types)
print(json.dumps(client.schema_for("mars").as_dict(), indent=2, sort_keys=True))

With only this example schema installed, output looks like this:

['mars']
{
  "event_type": "mars",
  "schema": {
    "identifier": {
      "class": {
        "required": true,
        "type": "EnumHandler",
        "values": [
          "od",
          "rd"
        ]
      },
      "step": {
        "range": null,
        "required": false,
        "type": "IntHandler"
      }
    },
    "payload": {
      "required": false
    }
  },
  "status": "success"
}

class must be od or rd; EnumHandler means a choice from a list. step is a whole number (IntHandler), with no range limit here. Publishing needs every identifier field, including step. The identifier’s required: false means it may be omitted from a listener filter, not from a notification. The payload is optional for this schema. Listing a schema does not prove you have permission to publish to it.

A complete publish script

Save this as publish.py and run python publish.py in the same terminal. It announces an operational forecast (class=od) at step 12:

import os

import pyaviso

client = pyaviso.AvisoClient(
    base_url=os.environ["AVISO_BASE_URL"], auth=pyaviso.Env()
)
response = client.notify(
    event_type="mars",
    identifier={"class": "od", "step": 12},
    payload={"location": "file:///data/forecast.grib"},
)
print(response.status)

On acceptance it prints:

success

notify takes keyword arguments: event_type names the schema, identifier supplies its labels, and payload carries extra information. Pass Python numbers and lists directly; 12 becomes a JSON number automatically. The Python keyword is payload, not data.

The server normalizes scalar identifiers in received notifications: this step comes back as the string "12". Payload numbers keep their JSON types.

The returned NotifyResponse has three string properties: status, request_id, and processed_at. The request ID is for tracing the HTTP request in server logs, not a notification ID or replay position. processed_at is the server’s timestamp. Success means the server accepted the notification, not that a user has received it or downloaded the file.

Publishing many notifications at once

To announce several datasets, put their notifications in a list and pass it to notify_many. Here we announce forecasts for steps 24 and 48. In publish.py, replace the response = client.notify(...) call and its print with this block, keeping the imports and client initialization:

notifications = [
    {
        "event_type": "mars",
        "identifier": {"class": "od", "step": 24},
        "payload": {"location": "file:///data/forecast-24.grib"},
    },
    {
        "event_type": "mars",
        "identifier": {"class": "od", "step": 48},
        "payload": {"location": "file:///data/forecast-48.grib"},
    },
]

results = client.notify_many(notifications)

for result in results:
    if result.response is not None:
        print("Notification accepted")
    else:
        print("Notification failed:", result.error)

Each notification has its own result. Check for failures even if others succeeded. Results are returned in the same order as the input list.

Each input is a dict using the same keys as notify. The schema still decides which fields must be supplied. Results are in input order; index starts at zero. ok is a boolean. On success, response is a NotifyResponse and error is None; on failure, response is None and error holds the exception.

The batch is not atomic: valid notifications can be stored even if another fails. Check the outcome before retrying. Malformed batch input, such as an item missing event_type, raises ValueError before sending any requests. A non-dict item raises TypeError. The optional concurrency argument limits how many notifications are sent at the same time. Omitting it or passing 0 allows up to 16 requests at a time.

The batch uses different step values from the single notification. On a backend that keeps only the latest notification per subject, publishing the same routing identifiers again replaces the retained record. Replay reads retained history, not every publish ever sent.

Error paths

For the mars schema above, leaving out step is an error even though it is optional in filters. This intentionally invalid example keeps the imports and client initialization from publish.py:

try:
    client.notify(event_type="mars", identifier={"class": "od"})
except pyaviso.HttpError as error:
    print(f"server rejected: status={error.status} request_id={error.request_id}")
    print(error.body)

The server rejects the missing identifier with HTTP 400. Use its error body to find the field to fix. An unknown event type, an unsupported identifier, or a value outside the schema’s choices can also be rejected by the server. The client does not decide which identifier names your server allows.

• pyaviso.HttpError means a non-2xx HTTP response. status is an integer, body is a string, and request_id is a string or None when unavailable.
• pyaviso.AuthError means the auth source could not produce credentials. pyaviso.Env() can raise it during setup, before notify is called.
• pyaviso.TransportError covers connection or response-transfer failures. A failure does not prove the server received nothing.

Publishes are not automatically retried after transport failures: the server may already have stored the notification. Check before resending to avoid duplicates. After HTTP 401, a client with an auth provider attempts credential refresh and retries once. See Authentication for credential setup.

Payload shape

The mars payload is optional. To publish without one, keep the imports and client initialization from publish.py and use:

response = client.notify(
    event_type="mars", identifier={"class": "rd", "step": 60}
)
print(response.status)

payload accepts JSON-compatible Python values, including nested dicts and lists, strings, numbers, and booleans. None means no payload in notify. The server schema determines whether a payload is required. Put extra details in the payload, rather than inventing identifier fields. Identifiers must match their handlers; arbitrary objects are not valid values for the mars enum and integer fields.

Identifier shapes

Spatial examples need a different schema. The following publish assumes the operator has installed the public server observations point-cloud schema. It requires date (DateHandler, format %Y%m%d), point_cloud (PointCloudHandler, at most 10,000 points), and a payload. Inspect it with client.schema_for("observations") before using this example.

Keep the imports and client initialization from publish.py:

response = client.notify(
    event_type="observations",
    identifier={
        "date": "20260601",
        "point_cloud": [[46.0, 8.0], [47.0, 9.0]],
    },
    payload={"source": "stations"},
)
print(response.status)

A point is [latitude, longitude]. Point clouds are lists of those pairs and accept arrays only. Pass Python lists, not json.dumps(...) strings. Clouds do not need a closing repeat; duplicate points are allowed and keep their order.

For this schema, subscribers filter with date and polygon, not point_cloud. A polygon is a list of at least four coordinate pairs, with the first pair repeated last. Any cloud point inside or on the boundary matches. See spatial filters. The reserved point field is a watch/replay filter for polygon streams, not a provider identifier. The alternative coordinate format applies to points and polygons, not clouds.

Admin operations

Operators can use wipe_stream(event_type) or wipe_all() to clear retained notifications, and delete_notification(notification_id) to remove one by ID. These are destructive operations requiring the appropriate permissions. A publish response’s request_id is not the notification ID to delete. See the API reference for the method signatures.

Async equivalent

If your application uses asyncio, the async client takes the same arguments:

import asyncio
import os

import pyaviso


async def main() -> None:
    client = pyaviso.AsyncAvisoClient(
        base_url=os.environ["AVISO_BASE_URL"], auth=pyaviso.Env()
    )
    response = await client.notify(
        event_type="mars",
        identifier={"class": "rd", "step": 72},
        payload={"location": "file:///data/forecast-72.grib"},
    )
    print(response.status)


asyncio.run(main())

This uses the same mars schema and prints success on acceptance. See Async for concurrent publishing and listening.

Listening

Receive notifications from data providers and use their labels to select what you need. You do not need to publish anything to listen.

Start with pyaviso installed. Set AVISO_BASE_URL and credentials with permission to receive notifications, as in Set the environment. The examples use pyaviso.Env(): set AVISO_TOKEN, or unset it and set both AVISO_USERNAME and AVISO_PASSWORD. For an anonymous server, pass auth=pyaviso.Anonymous() instead; Env() requires credentials.

A complete listener

These examples use the same small mars schema as the quickstart and Publishing. It has a required class filter (od or rd) and an optional whole-number step filter. If your server differs, use schema discovery below to choose its event type and fields.

Save this as listen.py:

import os

import pyaviso

client = pyaviso.AvisoClient(
    base_url=os.environ["AVISO_BASE_URL"], auth=pyaviso.Env()
)

try:
    with client.listen("mars", filter={"class": "od"}) as notifications:
        for notification in notifications:
            print(notification)
except KeyboardInterrupt:
    print("Stopped listening")

print(notification) displays the original server message as indented JSON.

Run python listen.py in the terminal where you set the environment. It waits for new mars notifications with class=od, at any step. Silence is normal when nothing matches. For a local trial, start this listener first, then run the publish script in another terminal with the same environment. Press Ctrl+C to stop.

That publish produces a notification like this (your sequence, timestamp and server URLs will differ):

{
  "data": {
    "identifier": {
      "class": "od",
      "step": "12"
    },
    "payload": {
      "location": "file:///data/forecast.grib"
    }
  },
  "datacontenttype": "application/json",
  "dataschema": "https://aviso.example/schema/mars",
  "id": "mars@1",
  "source": "https://aviso.example",
  "specversion": "1.0",
  "time": "2026-09-15T15:15:15.799578652Z",
  "type": "int.ecmwf.aviso.mars"
}

notification.identifier holds the notification’s labels. The server normalizes scalar labels, so the published integer step=12 arrives as the string "12". notification.payload holds extra information, such as a file location; receiving it does not download the file. It is None when absent. notification.sequence is a position used for replay, not a promise of strictly increasing delivery order or a count of your matches.

notification.cloudevent contains the original server message shown above. notification.as_dict() returns a convenience dictionary with event_type, sequence, identifier, payload, and cloudevent. That outer dictionary is created by the client; it is not the server’s wire format.

This script does not save a cursor to disk. Starting it again starts fresh at the live edge, rather than reading notifications published while it was off.

Check your server’s schema

Save this as discover.py and run python discover.py. It lists event types and prints the schema response for mars. If mars is absent, replace it with a listed name and run again. Discovery reads the operator’s configuration; it does not install schemas or prove your access rights.

import json
import os

import pyaviso

client = pyaviso.AvisoClient(
    base_url=os.environ["AVISO_BASE_URL"], auth=pyaviso.Env()
)
print(client.schema().event_types)
print(json.dumps(client.schema_for("mars").as_dict(), indent=2, sort_keys=True))

With only the small mars schema installed, the output is:

['mars']
{
  "event_type": "mars",
  "schema": {
    "identifier": {
      "class": {
        "required": true,
        "type": "EnumHandler",
        "values": [
          "od",
          "rd"
        ]
      },
      "step": {
        "range": null,
        "required": false,
        "type": "IntHandler"
      }
    },
    "payload": {
      "required": false
    }
  },
  "status": "success"
}

EnumHandler means a choice from a list; IntHandler means a whole number. Here step has no range limit. An identifier’s required: true means it must appear in a listener filter. required: false lets you omit that filter field. Providers still supply every identifier field, including step. The payload is optional for this schema.

Filtering

filter= selects identifier labels, not payload contents. Start with the required class, as in listen.py. To receive only step 12, replace its try/except block with this, keeping the imports and client initialization:

with client.listen("mars", filter={"class": "od", "step": 12}) as notifications:
    for notification in notifications:
        print(notification.identifier)

Both fields must match. An rd notification or an od notification at step 24 is excluded. Use Python numbers and lists directly, rather than JSON-encoded strings. The examples below also keep the imports and client from listen.py unless they show their own setup. Live examples wait until you press Ctrl+C; without the try/except, Python also prints a KeyboardInterrupt traceback.

Start from a specific position

Add start_from to read retained notifications before continuing with new ones. An integer starts after that sequence; start_from=0 requests retained history after sequence zero. A UTC date string such as start_from="2026-06-01T00:00:00Z" selects publication time, not a date field in the notification’s labels. To filter those labels, put date in filter= if the schema supports it.

The choice depends on the Python value’s type, not its size or appearance:

• start_from=20260915 is an integer: start after sequence 20260915, even though the number looks like a date.
• start_from="2026-09-15T00:00:00Z" is a string: start from that publication time.

Do not quote sequence numbers. start_from="20260915" is sent as a time string, not a sequence number. For time-based starts, use a full UTC timestamp like the one above so your intent is clear.

Replay only

start_from=0 starts from the beginning of retained history. mode="replay_only" finishes after that history instead of waiting for new notifications:

with client.listen(
    "mars",
    filter={"class": "od"},
    start_from=0,
    mode="replay_only",
) as notifications:
    for notification in notifications:
        print(notification)

Each notification is printed as indented JSON, as in the listener above.

An empty matching history prints nothing. Replay ends at the history boundary captured at the start, when the server signals replay_completed. It does not wait for new publications. Retention may have removed older records. If the server truncates replay at its cap, the client raises pyaviso.HistoryGapError; a failed run is not proof of full catch-up. See historical replay limits.

Stop at an end point

until ends the replay at an end point instead of at the last stored notification. An integer is the last sequence to deliver, inclusive; a UTC date string ends with the last notification published at or before that time. until implies mode="replay_only":

with client.listen(
    "mars",
    filter={"class": "od"},
    start_from="2026-06-01T00:00:00Z",
    until="2026-06-02T00:00:00Z",
) as notifications:
    for notification in notifications:
        print(notification.sequence, notification.identifier)

The script prints the matching notifications published from midnight UTC on 1 June 2026 up to and including midnight UTC on 2 June, then exits. Both dates are inclusive. An integer start is exclusive and an integer end inclusive: start_from=10, until=20 delivers the matching notifications with sequences 11 to 20. A replay also stops at the last notification stored when it starts, so an end point in the future ends there. Like start_from, a date refers to publication time, and the value’s type selects its meaning.

An integer until that is not greater than an integer start_from raises pyaviso.ConfigError, since the replay would deliver nothing. If the connection drops during the replay, the client resumes up to the same end point. An end point needs aviso-server 0.13.0 or later; an older server rejects the request with pyaviso.HttpError status 400.

Errors can arise when opening or iterating the listener. For example, a rejected filter can raise pyaviso.HttpError; inspect its status and body. Connection losses and retryable server failures normally trigger reconnection. A quiet listener is not itself an error. See error types and the API reference.

Numeric and enum constraints

After installing the schema and publishing the five seeds in the weather tutorial, point AVISO_BASE_URL at that test server. This replay prints B and C, then ends:

with client.listen(
    "weather",
    filter={
        "date": "20260913",
        "severity": {"gte": 5},
        "anomaly": {"between": [40, 50]},
        "region": {"in": ["north", "south"]},
    },
    start_from=0,
    mode="replay_only",
) as notifications:
    for notification in notifications:
        print(notification.payload["id"])

gte includes 5; between includes both endpoints; in accepts either listed region. These dicts are identifier predicates, not payload queries. See the shared constraint rules.

Spatial filters

Spatial examples need different schemas. The server’s public test_polygon example requires a polygon filter. Its date (DateHandler, %Y%m%d) and time (TimeHandler) are optional in subscriber filters. Providers supply all three identifiers and a required payload. Inspect it with client.schema_for("test_polygon") before using this replacement listener:

with client.listen(
    "test_polygon",
    filter={"polygon": [[0, 0], [1, 0], [1, 1], [0, 0]], "date": "20260601"},
) as notifications:
    for notification in notifications:
        print(notification.identifier)

Coordinates are [latitude, longitude]. A polygon needs at least four pairs, with the first pair repeated last. Pass nested Python lists, not an encoded string. Spatial identifiers arrive as arrays rather than normalized strings.

The public observations schema works differently: providers send a required date, a point_cloud array, and a payload. Subscribers filter with date and a closed polygon, not point_cloud. Any cloud point inside or on the polygon boundary matches. See Publishing: identifier shapes for the paired provider example.

Resume across restarts

To save a resume position, replace the client initialization in listen.py with this block. Keep its imports and try/except listener:

from pathlib import Path

state_path = Path.home() / ".config" / "aviso" / "state.json"
state_path.parent.mkdir(parents=True, exist_ok=True)
client = pyaviso.AvisoClient(
    base_url=os.environ["AVISO_BASE_URL"],
    auth=pyaviso.Env(),
    state_store=pyaviso.JsonFileStore(state_path),
)

Use a local filesystem. With no saved cursor, the first run starts at the live edge. Later runs with the same server, schema and filter resume after the saved position. The client commits a pending sequence before sending the next notification to the iterator’s buffer. This is not an acknowledgement that your loop finished its work. Make repeated handling safe; at-least-once redelivery depends on retained history and a usable saved cursor, and does not guarantee completion of application work. See State and resume for resume keys and storage details.

Clean shutdown with with

Exiting with calls the synchronous iterator’s close(), cancelling and waiting for its background task to finish. This also happens after a loop body raises or breaks. A break alone does not close an iterator you still hold; leave the context or call close() explicitly.

flush_cursor_on_exit defaults to False, leaving the last pending sequence uncommitted when no later notification arrives. With a state store, setting flush_cursor_on_exit=True on the client attempts to save that pending cursor during shutdown. Context exit waits for the attempt, but a storage failure can still prevent it. Flushing does not certify that your application processed every buffered notification. Without a saved cursor, a fresh run starts live.

Reusing a watch request

For reusable listener settings, use WatchRequest and pass it as request=. It cannot be combined with the event/filter/start/until/mode/trigger arguments used above. See Builder pattern for complete examples and Triggers for actions attached to a listener.

Multiple listeners

To receive notifications for several filters or event types through one loop, see Multiple listeners.

Async equivalent

For an application using asyncio, use AsyncAvisoClient, async with, and async for. Async context exit awaits aclose(), rather than the synchronous close(). With the default asyncio.run() signal handler, Ctrl+C cancels the main task first, allowing context cleanup; KeyboardInterrupt is then raised outside asyncio.run(). See Async for complete listener examples.

Multiple listeners

client.listen_many() opens several listeners and delivers their notifications through a single loop. Each listener has a name, an event type and, optionally, a filter; listeners may use different event types. Each item the loop yields is a pair of the listener name and the notification:

for name, notification in notifications:
    ...

The same method is available on AvisoClient and AsyncAvisoClient. It does not require threads or an asyncio event loop of the caller’s own.

When to use it

When the notifications of interest differ only in the value of one identifier key, a single listener is sufficient. The in operator accepts several values, and the loop can distinguish them:

with client.listen("mars", filter={"class": {"in": ["od", "rd"]}}) as notifications:
    for notification in notifications:
        if notification.identifier["class"] == "od":
            ...

Use listen_many when the listeners need different identifier keys, different event types, different triggers or different start positions.

Example

The example uses the quickstart environment and its mars schema: class is a required choice of od or rd, and step is an optional integer.

Save the following as listen_many.py and run python listen_many.py:

import pyaviso

client = pyaviso.AvisoClient()

listeners = {
    "operational": {"event_type": "mars", "filter": {"class": "od"}},
    "research": {"event_type": "mars", "filter": {"class": "rd", "step": 0}},
}

try:
    with client.listen_many(listeners) as notifications:
        for name, notification in notifications:
            print(name, notification.identifier)
except KeyboardInterrupt:
    print("Stopped listening")

The dictionary maps each listener name to the keyword arguments listen() accepts: event_type, filter, start_from, until, mode and triggers. The script waits for new notifications. With three notifications published from another terminal (class=od at step 12, class=rd at step 6, and class=rd at step 0), the output is:

operational {'class': 'od', 'step': '12'}
research {'class': 'rd', 'step': '0'}

The notification with class=rd at step 6 matches neither listener. Press Ctrl+C to stop. Leaving the with block closes every listener.

Listeners for different event types

Each listener has its own event type. On a server that also defines an alerts event type, with a region of north or south:

listeners = {
    "forecasts": {"event_type": "mars", "filter": {"class": "od"}},
    "alerts": {"event_type": "alerts", "filter": {"region": "north"}},
}

with client.listen_many(listeners) as notifications:
    for name, notification in notifications:
        print(name, notification.event_type, notification.identifier)

forecasts mars {'class': 'od', 'step': '12'}
alerts alerts {'region': 'north'}

Each event type defines its own filter keys, and the credential in use must grant read access to every event type listed.

Function triggers per listener

To process every notification with application code, without writing the loop, give each listener a Trigger.function and call run():

from functools import partial

import pyaviso
from pyaviso import Trigger


def save(notification, folder):
    print("save", notification.identifier, "to", folder)


client = pyaviso.AvisoClient()
listeners = {
    "operational": {
        "event_type": "mars",
        "filter": {"class": "od"},
        "triggers": [Trigger.function(partial(save, folder="/data/od"))],
    },
    "research": {
        "event_type": "mars",
        "filter": {"class": "rd"},
        "triggers": [Trigger.function(partial(save, folder="/data/rd"))],
    },
}

try:
    client.listen_many(listeners).run()
except KeyboardInterrupt:
    print("Stopped listening")

With the same three notifications published, the output is:

save {'class': 'od', 'step': '12'} to /data/od
save {'class': 'rd', 'step': '6'} to /data/rd
save {'class': 'rd', 'step': '0'} to /data/rd

The function receives the notification as its only argument. Bind any further arguments with functools.partial, as above, or with a lambda. run() processes notifications until every listener has ended or the process is interrupted, then closes all listeners.

Functions run in the calling thread, one notification at a time, in arrival order. They therefore need no synchronisation and may call blocking code. A slow function delays every listener; no notification is lost, because the client reads from the server more slowly. See Triggers for retries, required and the interaction with built-in triggers, which always run first.

Shared options

start_from, until and mode passed to listen_many apply to every listener that does not set its own. The following replays the retained history and then returns:

listeners = {
    "operational": {"event_type": "mars", "filter": {"class": "od"}},
    "alerts": {"event_type": "alerts", "filter": {"region": "north"}},
}

with client.listen_many(listeners, start_from=0, mode="replay_only") as notifications:
    for name, notification in notifications:
        print(name, notification.sequence, notification.identifier)
print("replay finished")

After the preceding examples, one possible output is:

alerts 1 {'region': 'north'}
operational 1 {'class': 'od', 'step': '12'}
operational 4 {'class': 'od', 'step': '12'}
operational 5 {'class': 'od', 'step': '12'}
replay finished

Sequence numbers are per event type: mars sequences 1, 4 and 5 are the od notifications published for the preceding examples, and alerts sequence 1 is the north alert. The loop ends when every listener has ended; a listener that ends earlier stops contributing.

A listener may also be given as a WatchRequest instead of a dictionary. A WatchRequest carries its own start position, so shared options do not apply to it.

Error handling

A listener can fail, for example because of a misspelt filter key, a missing read permission, or a replay that exceeds the server’s limit. A Trigger.function can raise an exception. The on_error argument defines the response:

Functions are required by default. A function created with required=False does not reach on_error: its failure is logged, and the notification is still delivered.

With "raise", the error keeps its type, its message begins with the listener name, and the listener attribute holds the name:

try:
    client.listen_many(listeners).run()
except pyaviso.HttpError as error:
    print(error.listener, error.status)

With "continue", each failure is logged as a warning and recorded in errors. In the following example the second listener misspells class, so the server rejects it for omitting a required key:

listeners = {
    "operational": {"event_type": "mars", "filter": {"class": "od"}},
    "typo": {"event_type": "mars", "filter": {"clas": "rd"}},
}

try:
    with client.listen_many(listeners, on_error="continue") as notifications:
        for name, notification in notifications:
            print(name, notification.identifier)
except KeyboardInterrupt:
    print("Stopped listening")

for failure in notifications.errors:
    print(failure.listener, failure.kind.value, type(failure.error).__name__)

listener 'typo': http 400 (...): {..."Required field 'class' missing for watch operation"...} (listener stopped; the other listeners continue)
operational {'class': 'od', 'step': '12'}
Stopped listening
typo listener HttpError

failure.kind is a pyaviso.ListenFailureKind: LISTENER when a listener stopped and TRIGGER when a function raised. Being a str enum, it also compares equal to "listener" and "trigger". The warnings are logged on the pyaviso.listen logger, so they can be routed or silenced with the standard logging configuration.

When on_error is a function, it is responsible for reporting, and no warning is logged:

def report(name, error):
    print(f"{name} failed: {error}")
    if isinstance(error, pyaviso.AuthError):
        raise error  # stop every listener

client.listen_many(listeners, on_error=report).run()

With "continue" or a function, if every listener fails, the loop raises pyaviso.AvisoError, whose failures attribute lists each failure. A script therefore cannot finish silently when every listener has failed. After the loop has stopped, for any reason, further iteration ends immediately.

Shared start_from, until and mode values are checked even when every listener sets its own.

Arguments are validated before any listener opens. An unknown key such as filtre, a missing event_type or an invalid on_error raises immediately, and no listener is left running.

Asynchronous client

On AsyncAvisoClient, the same method returns an asynchronous iterator. Functions may be defined with async def; they are awaited:

import asyncio

import pyaviso
from pyaviso import Trigger


async def save(notification):
    await asyncio.sleep(0.1)  # stands in for an asynchronous upload or write
    print("saved", notification.identifier)


async def main():
    client = pyaviso.AsyncAvisoClient()
    listeners = {
        "operational": {
            "event_type": "mars",
            "filter": {"class": "od"},
            "triggers": [Trigger.function(save)],
        },
        "alerts": {"event_type": "alerts", "filter": {"region": "north"}},
    }
    async with client.listen_many(listeners) as notifications:
        async for name, notification in notifications:
            print(name, notification.identifier)


try:
    asyncio.run(main())
except KeyboardInterrupt:
    print("Stopped listening")

saved {'class': 'od', 'step': '12'}
operational {'class': 'od', 'step': '12'}
alerts {'region': 'north'}

await notifications.run() replaces the loop. An on_error function may also be defined with async def.

Behaviour

• Order. Within one listener, notifications are delivered in the same order as with listen(). Across listeners the order is not defined: listeners are read in turn, so a busy listener cannot delay a quiet one.
• Saved positions. With a state_store, each listener keeps its own position, the same position listen() would use for that event type and filter. The listener name is not part of it, so renaming a listener keeps its position. Two listeners with the same event type and filter share a position, and the client logs a warning when this occurs.
• Resources. A listener is not a thread. All listeners run on the client’s existing background threads and share its connections.

Triggers

A trigger runs an action automatically for each matching notification, such as appending to a file or sending an HTTP request. Add triggers to client.listen() to run them before Python receives the notification in your loop. To run your own Python analysis in the loop, you do not need a trigger.

Triggers run in your client process. They do not keep listening or start new actions after your Python program exits.

A complete listener with triggers

Use the installation and environment setup from the quickstart, including AVISO_BASE_URL and credentials for pyaviso.Env(). For an anonymous server, pass auth=pyaviso.Anonymous() instead.

This uses the quickstart’s mars schema: class is a required choice of od or rd; step is an integer, optional in filters. Leaving it out selects all steps. Providers must supply both identifier fields when publishing. The optional payload can carry a file location. Check your server’s schema if it differs.

Save this as listen.py and run python listen.py in that terminal:

import os

import pyaviso
from pyaviso import Trigger

client = pyaviso.AvisoClient(
    base_url=os.environ["AVISO_BASE_URL"], auth=pyaviso.Env()
)
with client.listen(
    "mars",
    filter={"class": "od"},
    triggers=[Trigger.log('mars.log')],
) as notifications:
    for notification in notifications:
        print(notification)

The script waits for new mars notifications with class=od. For each one, it appends a JSON line to mars.log in your current directory, then prints the notification. A notification with class=rd causes neither action. Press Ctrl+C to stop; the with block closes the listener.

Run this from a directory you can write to. If the log file cannot be written, the listener stops with an error by default.

The two outputs contain different views of the same notification. print(notification) shows the original CloudEvent as indented JSON, including its specversion, type and data. The log contains a smaller JSON object on one line, with fields such as event_type, sequence, identifier and payload. A payload such as {"location": "file:///data/forecast.grib"} is a reference to a file; the log trigger does not copy that file.

When to use which

The six kinds

Each fragment below replaces the triggers=[...], line in listen.py. Keep the imports, client setup and loop. Run python listen.py again after each change. For HTTP examples, set the named environment variable to a receiver URL you control before running the script.

Echo

Print each matching notification, using the same smaller view as the log trigger:

    triggers=[Trigger.echo()],

In a terminal, echo prints a heading and indented JSON. When redirected or piped, it prints one compact JSON line. The loop still prints the CloudEvent afterwards, so you see both views.

Log

To keep a log and also echo each notification, put both actions in the list:

    triggers=[Trigger.log("mars.log"), Trigger.echo()],

Actions run in list order before the loop receives that notification. The log file opens on the first matching notification and appends to existing content.

Command (Unix only)

Append each forecast step to steps.txt in your current directory:

    triggers=[
        Trigger.command('printf "%s\\n" "$AVISO_IDENTIFIER_STEP" >> steps.txt')
    ],

This runs through /bin/sh -c. The client automatically supplies AVISO_IDENTIFIER_CLASS and AVISO_IDENTIFIER_STEP for this schema, plus AVISO_EVENT_TYPE, AVISO_SEQUENCE, AVISO_PAYLOAD_JSON and AVISO_NOTIFICATION_JSON. Quote shell variable expansions as above. Prefer these variables to inserting notification text into shell source with templates. Command stdout is captured, so write to a file when you want to keep the output. On non-Unix builds, the constructor raises pyaviso.ConfigError.

Webhook

Set FORECAST_WEBHOOK_URL to your HTTP receiver’s URL. Send it a JSON body with the forecast step:

    triggers=[
        Trigger.webhook(
            os.environ["FORECAST_WEBHOOK_URL"],
            body_template='{"step": {{ notification.identifier.step }}}',
        )
    ],

The default method is POST. Here the template writes step as a JSON number. Without body_template, the body is the smaller notification view used by log and echo. URL, header values and body templates can read notification fields and environment variables. See the template guide for syntax and escaping rules.

Teams

Set FORECAST_TEAMS_URL to your Teams workflow webhook URL:

    triggers=[Trigger.teams(os.environ["FORECAST_TEAMS_URL"])],

The client builds an Adaptive Card from the notification and sends it by HTTP POST. Configure the receiving workflow as described in the Teams guide.

Post

Set FORECAST_COLLECTOR_URL to your CloudEvent receiver’s URL:

    triggers=[Trigger.post(os.environ["FORECAST_COLLECTOR_URL"])],

This sends the original server CloudEvent as JSON by HTTP POST. It preserves the envelope fields shown by print(notification), including CloudEvent extensions. Use it when the receiver needs those fields rather than the smaller default webhook body.

Function

Trigger.function(func) calls a Python function of yours with each notification. It is the way to run your own code without writing the loop: run() reads the stream to the end and closes it.

import pyaviso
from pyaviso import Trigger


def save(notification):
    print("save", notification.identifier)


client = pyaviso.AvisoClient()
try:
    client.listen(
        "mars",
        filter={"class": "od"},
        triggers=[Trigger.log("mars.log"), Trigger.function(save)],
    ).run()
except KeyboardInterrupt:
    print("Stopped listening")

When an od notification is published, a line is appended to mars.log and the script prints:

save {'class': 'od', 'step': '12'}

A function trigger differs from the six built-in kinds in where it runs. The built-in kinds run inside the library, before the notification reaches Python. A function runs in the application, in the thread that reads the notification (or on its event loop with AsyncAvisoClient), when the notification reaches it. Consequently:

• The built-in triggers for a notification always run before its functions, regardless of their order in the list.
• Functions run one notification at a time, in arrival order. They need no synchronisation and may call blocking code. A slow function delays the listener; no notification is lost, because the client reads from the server more slowly. On AsyncAvisoClient, a blocking call in a function blocks the event loop, and with it every listener; use async def and awaitable calls there.
• With AsyncAvisoClient, a function may be defined with async def; it is awaited. AvisoClient.listen() rejects such a function with a TypeError when called, because nothing would await it.
• The notification has already been received when a function runs. Unlike a failed built-in trigger, a failed function therefore never holds back the saved position, whether or not the loop continues: the notification may already be recorded as received, and is then not delivered again after a restart. Record completed work separately when every notification must be processed.

The function receives the notification as its only argument. Bind further arguments with functools.partial(save, folder="/data") or a lambda. Several functions run in the order listed.

To use a different function for each of several listeners, see Multiple listeners.

Tunables

By default, every trigger is required and has no retries. If a required action fails, listening stops with pyaviso.TriggerError; that notification does not reach the Python loop. Earlier actions are not undone. Set required=False for an action whose failure should emit a warning and let later actions and the Python loop continue.

For example, replace the trigger list with this optional webhook, allowing two extra attempts and a five-second timeout per request:

    triggers=[
        Trigger.webhook(
            os.environ["FORECAST_WEBHOOK_URL"],
            retries=2,
            required=False,
            timeout=5.0,
        )
    ],

• retries=0 means one attempt. retries=2 allows up to three attempts.
• fail_fast=True is the default for command and HTTP triggers. A non-zero command exit, an HTTP 4xx response, an invalid request or a template error fails immediately, bypassing retries. HTTP 5xx responses, connection errors and timeouts can retry. Set fail_fast=False to retry those immediate failures too, within the configured retry count.
• HTTP triggers (webhook, teams, post) default to a 30-second timeout per request. Commands have no timeout by default; use timeout to set one in seconds. Echo and log do not accept a timeout keyword. Their .timeout() setter is ignored, as is .fail_fast().
• Trigger.function takes retries, required and label. A function that raises counts as a failure: it is called again up to retries times, then a required one raises TriggerError (with trigger_kind == "function" and the original exception as its __cause__) and the functions after it are not called for that notification; an optional one is logged and skipped. timeout and fail_fast do not apply to functions and raise ValueError: Python code cannot be interrupted safely.
• A plain function that returns an awaitable is a programming error, not a failure of one notification: it raises TypeError, whatever required and on_error say.

The builder pattern covers chainable setters and reusing triggers. See error handling for catching client errors.

With AsyncAvisoClient

Pass the same triggers=[...] list to AsyncAvisoClient.listen(). Actions still run before the notification reaches your async for loop, and Trigger.function may be given an async def function, which is awaited. Use await iterator.run() in place of .run(). See Async for a complete listener.

Builder pattern

Start with the keyword arguments on Listening. Use a WatchRequest when you want to name a set of listener settings and reuse it. A builder is simply a series of calls that returns those settings. There is no final .build() call.

These examples use the quickstart’s small mars schema: class is a required filter with choices od and rd; the whole-number step filter is optional. Providers supply both fields when publishing. The payload is optional. Check your server’s schema if it differs.

Build a watch request

This runs without a server. Save it as build_request.py and run python build_request.py:

import pyaviso

request = pyaviso.WatchRequest.watch("mars").with_filter({"class": "od"})
print(request.event_type, request.mode)

Output:

mars watch

The request describes a listener; constructing it does not connect to a server. Pass it to client.listen(request=request), as below.

A complete example

Use the installation and environment setup from the quickstart, including AVISO_BASE_URL and credentials for pyaviso.Env(). For an anonymous server, pass auth=pyaviso.Anonymous() instead. Save this as listen_builder.py and run python listen_builder.py:

import os

import pyaviso

client = pyaviso.AvisoClient(
    base_url=os.environ["AVISO_BASE_URL"], auth=pyaviso.Env()
)
request = pyaviso.WatchRequest.watch("mars").with_filter({"class": "od"})

try:
    with client.listen(request=request) as notifications:
        for notification in notifications:
            print(notification)
except KeyboardInterrupt:
    print("Stopped listening")

It waits for new operational forecasts at any step and prints each original CloudEvent as indented JSON, as shown in Listening. Press Ctrl+C to stop. You do not need publishing permission to listen. For a local trial with provider credentials, run the publish script in another terminal.

request= cannot be combined with event_type, filter, start_from, until, mode or triggers. Put those settings on the request instead.

Replay history and exit

In listen_builder.py, replace the request = ... line with this block. Keep the imports, client initialization and loop:

request = pyaviso.WatchRequest.replay_only("mars", 0).with_filter({"class": "od"})

Run the script again. It reads matching retained history, prints each notification and exits at the server’s replay boundary. Empty history prints nothing. It does not publish anything or wait for new notifications.

An integer start position is exclusive: 0 means everything retained after sequence zero, not every notification ever published. To read after sequence 1024 and then keep listening, use WatchRequest.watch_from("mars", 1024). Both start-position factories also accept a UTC timestamp string such as "2026-06-01T00:00:00Z". replay_only also takes an end point: WatchRequest.replay_only("mars", 0, until=100) ends with sequence 100. See start positions and State and resume.

Build a trigger

You can add triggers to run actions before a notification reaches your loop. Their factories accept keyword arguments. Chainable setters let you adjust an existing trigger. This standalone example needs no server:

import pyaviso

trigger = pyaviso.Trigger.echo().retries(2).required(False)
request = (
    pyaviso.WatchRequest.watch("mars")
    .with_filter({"class": "od"})
    .with_triggers([trigger])
)
print(request.event_type, request.mode)

It prints mars watch. Passing this request to a listener adds an optional echo action with up to two extra attempts. Echo prints a smaller notification view; print(notification) in your loop prints the original CloudEvent.

The setters are .retries(n), .required(on), .timeout(seconds), .fail_fast(on) and .label(name). Timeout and fail-fast settings affect command and HTTP triggers; label affects only echo. See Triggers for failure behavior and the API reference for factory defaults.

Setters return a new value

Keep the result of a setter: it returns a new value and does not change the original. This standalone example builds two independent filters:

import pyaviso

base = pyaviso.WatchRequest.watch("mars")
operational = base.with_filter({"class": "od"})
research = base.with_filter({"class": "rd"})
print(operational.event_type, research.event_type)

It prints mars mars. A call such as base.with_filter({"class": "od"}) whose result you discard leaves base unchanged.

When to use the builder

Use keywords for a single listen call. Use a request for settings you want to reuse or derive from a common base. Trigger and WatchRequest work with both clients; they do not belong to a particular client instance. See Async if your application already uses asyncio.

Authentication

Ask your server operator for its URL and credentials. Users need permission to receive notifications; providers need permission to publish. An auth provider tells the client where to get credentials. It does not grant permissions.

Let the client find your credentials

If you create a client without an auth argument, it looks for a credential in three places and uses the first one it finds:

1. The environment: AVISO_TOKEN, or AVISO_USERNAME with AVISO_PASSWORD.
2. The auth: block of ~/.config/aviso/config.yaml.
3. ~/.config/aviso/credentials.yaml.

import pyaviso

client = pyaviso.AvisoClient()
print(client.schema().event_types)
print(client.config.auth)

The address is found the same way, from AVISO_BASE_URL or the config file; Configuration has the full order and how to see what was chosen. client.config.auth names the credential’s kind and source without its value.

This suits a script or notebook whose credentials were set up beforehand by something else. Nothing in the code names a credential, so the same file runs for a colleague whose token lives somewhere different.

The two file paths can be moved with AVISO_CLIENT_CONFIG_FILE and AVISO_CREDENTIALS_FILE.

Finding nothing leaves the client anonymous. Finding a file that cannot be read raises pyaviso.ConfigError, and a half-set environment (a username with no password) raises pyaviso.AuthError, so a mistake is reported rather than quietly ignored.

A credential found this way is not sent to a plain http:// address unless it is loopback, and the client raises pyaviso.AuthError instead. You did not name the credential in the code, so a mistyped host would otherwise send it in the clear. Naming it yourself lifts the restriction:

client = pyaviso.AvisoClient(
    base_url="http://aviso.internal.example.org",
    auth=pyaviso.Bearer(os.environ["AVISO_TOKEN"]),
)

To send no credential even though one is present on the machine, pass the Anonymous marker:

client = pyaviso.AvisoClient(
    base_url=os.environ["AVISO_BASE_URL"], auth=pyaviso.Anonymous()
)

Read a particular config file

AvisoClient() already reads ~/.config/aviso/config.yaml. To read a different file instead, name it; that path must exist:

client = pyaviso.AvisoClient.from_file("/etc/aviso/production.yaml")

Keyword arguments replace what the file said, and auth=pyaviso.Anonymous() drops a credential the search found. A file that cannot be read, or that has a mistyped key inside a section the client reads, raises pyaviso.ConfigError. Relative paths under tls.ca_bundle are resolved against the file’s own directory, not the working directory.

The plaintext rule above still applies: a credential the file supplied is refused for a plain http:// address that is not loopback, whether that address came from the file or from a base_url argument. Pass auth yourself to lift it.

AsyncAvisoClient.from_file takes the same arguments.

The rest of this page covers naming a source yourself, which is what you want when one script must use particular credentials.

Environment

Start with pyaviso installed and the quickstart environment. Set AVISO_BASE_URL and AVISO_TOKEN, or unset the token and set both AVISO_USERNAME and AVISO_PASSWORD.

Save this as check_auth.py and run python check_auth.py:

import os

import pyaviso

client = pyaviso.AvisoClient(
    base_url=os.environ["AVISO_BASE_URL"], auth=pyaviso.Env()
)
print(client.schema().event_types)

It prints the server’s configured event types, for example ['mars'] for the quickstart schema. Schema discovery does not prove you can listen or publish: those operations have their own permission checks, and discovery may be public.

Env() reads credentials when constructed:

• A non-empty AVISO_TOKEN takes precedence over username and password.
• Otherwise it uses a non-empty AVISO_USERNAME with AVISO_PASSWORD set. The password may be an empty string if your service permits that.
• Without either combination, construction raises pyaviso.AuthError.

Env() has no anonymous fallback of its own. For an anonymous server, pass auth=pyaviso.Anonymous(); omitting auth starts the search described above. Updating environment variables does not change an existing Env provider; create it again or restart the script.

Bearer token

To select a token explicitly, replace the client initialization in check_auth.py with this block. Keep the imports and schema call:

client = pyaviso.AvisoClient(
    base_url=os.environ["AVISO_BASE_URL"],
    auth=pyaviso.Bearer(os.environ["AVISO_TOKEN"]),
)

This sends the token in the HTTP Authorization header. Bearer redacts it in repr(). Keep credentials out of source files and do not print them.

Basic auth

With AVISO_USERNAME and AVISO_PASSWORD set, use this replacement instead:

client = pyaviso.AvisoClient(
    base_url=os.environ["AVISO_BASE_URL"],
    auth=pyaviso.Basic(os.environ["AVISO_USERNAME"], os.environ["AVISO_PASSWORD"]),
)

This explicitly selects username/password authentication even if AVISO_TOKEN is also set. Basic authentication encodes credentials; HTTPS protects them in transit. Basic redacts its password in repr().

Config file

ConfigFile reads an auth-only YAML file, not the CLI’s general configuration file. Create ~/.config/aviso/auth.yaml with exactly one of the following shapes, replacing the example values with your credentials:

bearer:
  token: your-bearer-token

Or, for Basic authentication:

basic:
  username: your-username
  password: your-password

Restrict file access to the account running your script. Keep the URL in the client initialization, not this file. Unknown fields, both sections, neither section, an unreadable file or malformed YAML raise pyaviso.ConfigError at construction.

Use this replacement client initialization in check_auth.py:

client = pyaviso.AvisoClient(
    base_url=os.environ["AVISO_BASE_URL"],
    auth=pyaviso.ConfigFile("~/.config/aviso/auth.yaml"),
)

The path accepts a string or Path; ~ is expanded. The file is read at construction and reread when the client requests a credential refresh after HTTP 401. A file change alone does not immediately replace the cached value.

Refresh on 401

With an auth provider, the client attempts refresh after a 401 and retries the request once if refresh succeeds. A second 401 is still an error: HttpError for a one-shot request, or AuthError when watch authentication remains rejected.

• Bearer, Basic and Env keep their original credentials; refresh does not change them.
• ConfigFile rereads its source file. An invalid replacement file raises AuthError during refresh. A credential found at ~/.config/aviso/credentials.yaml is read this way, so a token rewritten in place is picked up without restarting the script.
• Chain refreshes the first member currently able to produce a header.

For static credentials, fix the source and construct a new provider/client or restart the script. Inspect HTTP errors to distinguish a server rejection from a local credential setup failure.

Chain

This is an advanced option for already-constructed providers. Chain asks each member for an authorization header in order and uses the first successful result. If all fail, it propagates the last provider error. An empty chain raises AuthError when a request needs credentials.

It is not a list of credentials to try against a server. A 401 does not switch to the next member. Env() and ConfigFile(...) are constructed before being passed to Chain; a missing environment or invalid file raises immediately, before the chain can provide fallback. Choose and validate your available credential source during setup rather than relying on a chain to skip those construction errors.

With AsyncAvisoClient

The same providers work with the async client. Credential setup remains synchronous; HTTP methods are awaited. See Async if your application already uses asyncio.

State and resume

A state store saves a cursor, the sequence position used to resume a listener. This helps a restarted script read retained notifications published while it was stopped. It does not record whether your Python analysis finished.

A saved cursor is not an acknowledgement of completed work. The client can save progress while notifications are still waiting in the iterator’s buffer. A crash can therefore leave application work unfinished even for a saved sequence. Make repeated processing safe and track completed work separately when it matters. The cursor alone gives neither lossless processing nor exactly-once execution.

A complete resuming listener

Use the quickstart environment, including AVISO_BASE_URL and credentials for pyaviso.Env(). For an anonymous server, pass auth=pyaviso.Anonymous() instead.

This uses the small mars schema: class is a required choice of od or rd; step is a whole number optional in filters. Omitting it receives all steps. Providers supply both identifiers; the payload is optional. You only need receiving permission for this script.

Save this as listen_saved.py and run python listen_saved.py:

import os
from pathlib import Path

import pyaviso

state_path = Path.home() / ".config" / "aviso" / "state.json"
state_path.parent.mkdir(parents=True, exist_ok=True)
client = pyaviso.AvisoClient(
    base_url=os.environ["AVISO_BASE_URL"],
    auth=pyaviso.Env(),
    state_store=pyaviso.JsonFileStore(state_path),
)

try:
    with client.listen("mars", filter={"class": "od"}) as notifications:
        for notification in notifications:
            print(notification)
except KeyboardInterrupt:
    print("Stopped listening")

It prints each original CloudEvent as indented JSON. Press Ctrl+C to stop. With no saved cursor, the first run waits for new notifications. Later runs with the same settings resume after the saved sequence, if one exists. The last printed notification may be delivered again. If nothing was saved, restarting begins at the live edge, so do not assume a one-notification first run has saved progress.

For a local trial, start this listener, then run the provider publish script in another terminal. Publish several different steps, stop the listener, publish another step, then restart it. What remains available depends on server retention.

Where state lives

• With state_store=None (the default), there is no saved state across runs.
• MemoryStore() holds checkpoints in memory for clients using that store instance. They disappear when the process exits.
• JsonFileStore(path) writes checkpoints to a local JSON file, using an atomic rename and a sidecar lockfile for cooperating writers.

The example creates the parent directory first. Choose a local path your user can write to, including permission to create the lockfile and replace the state file. Relative paths are relative to the working directory. ~ is expanded. Keep the state file if you want to resume; deleting it discards that position.

Local filesystems only

Use local storage rather than NFS or CIFS for JsonFileStore. File locking does not make several listeners a work-sharing queue: they can receive the same notifications. The Python API accepts the two built-in stores, not arbitrary custom Python store objects.

How it works

The Python client derives a resume key from the server URL, event type and filter. Changing one of these can select a different key with no saved cursor. A server schema change alone does not change the key.

For each notification, the background listener:

1. Saves the previous pending sequence, if any.
2. Runs this notification’s triggers.
3. Sends it to the iterator’s buffer.
4. Records its sequence as pending if it advances the current position.

These steps do not wait for your Python loop to finish processing the previous notification. A required trigger failure prevents the failing notification from becoming pending, but the previous position may already have been saved. Checkpoints do not move backwards within a watch session; out-of-order notifications can still reach triggers and your loop.

Redelivery depends on retained history and a usable cursor. A sequence is a resume boundary, not a separate acknowledgement for every event. See Listening for retention and replay limits.

Choose a starting position

An explicit start_from takes precedence over saved state. An integer is exclusive: start_from=1024 reads after sequence 1024; start_from=0 requests all retained history after zero. A UTC timestamp such as start_from="2026-06-01T00:00:00Z" selects publication time, not identifier labels. Subsequent checkpoints use sequences.

Keep sequence numbers unquoted. See Start from a specific position for how Python distinguishes sequence numbers from times.

With start_from=None, a matching saved cursor is used if available; otherwise listening starts live. To deliberately start fresh without affecting existing state, construct a client without that state store. Do not delete your state file just to investigate a problem.

Flush on exit

Keep the default flush_cursor_on_exit=False for a processing script unless you have a reason to advance the final pending position during shutdown. With the default, the last pending sequence is not saved just because the iterator closes. It may be replayed on restart, provided a usable starting position and retained record exist. This does not protect all unfinished buffered work: earlier checkpoints can already be ahead of your processing.

Setting flush_cursor_on_exit=True on the client attempts to save the last pending cursor on shutdown. This can reduce final-notification repeats for a display-only listener. It can also skip unfinished application work on restart, including after your loop raises an exception. A failed storage write can prevent the flush. It is not a successful-work acknowledgement.

The iterator’s with block calls close(), which cancels and waits for the background listener, including any exit-flush attempt. A break alone does not close an iterator you still hold outside a context manager.

With AsyncAvisoClient

Use the same store and constructor options. Wrap the returned iterator in async with; it awaits aclose() on exit. See the complete async listener. The checkpoint and unfinished-work limits above apply equally to async code.

Error handling

Read the exception message first. A missing credential needs a setup change; a rejected filter needs a schema check. Repeating the same request will not necessarily fix either problem.

Client errors inherit from pyaviso.AvisoError. Python input errors can also raise TypeError or ValueError, and a missing environment variable accessed through os.environ[...] raises KeyError. AvisoError does not catch these or errors in your own analysis.

Catching everything

Use the quickstart setup, including AVISO_BASE_URL and credentials for pyaviso.Env(). For an anonymous server, pass auth=pyaviso.Anonymous() instead.

This listener uses the small mars schema. It has a required class choice (od or rd) and optional whole-number step filter. Providers must supply both identifiers; the payload is optional. Listening requires receiving permission, not publishing permission.

Save this as listen_errors.py and run python listen_errors.py:

import os

import pyaviso

try:
    client = pyaviso.AvisoClient(
        base_url=os.environ["AVISO_BASE_URL"], auth=pyaviso.Env()
    )
    with client.listen("mars", filter={"class": "od"}) as notifications:
        for notification in notifications:
            print(notification)
except pyaviso.AvisoError as error:
    print("Listening failed:", error)
    raise
except KeyboardInterrupt:
    print("Stopped listening")

It prints matching notifications as indented CloudEvent JSON until you press Ctrl+C. Setup is inside try because Env() can fail before listening starts. The with block closes the iterator even if your loop raises an exception. The error branch reports the failure and reraises it, so a failed job does not look like a successful run.

HttpError exposes the server’s response

HttpError carries the integer status, string body and optional request_id. Keep the request ID when asking your operator to find the request in server logs. The response body explains what the server rejected.

For providers, here is an intentionally invalid publish. Save it as bad_publish.py and run python bad_publish.py with publishing credentials and the same environment setup:

import json
import os

import pyaviso

client = pyaviso.AvisoClient(
    base_url=os.environ["AVISO_BASE_URL"], auth=pyaviso.Env()
)
try:
    client.notify(event_type="mars", identifier={"class": "od"})
except pyaviso.HttpError as error:
    print("status:", error.status)
    print(json.dumps(json.loads(error.body), indent=2, sort_keys=True))

Captured output with the small mars schema (your request ID will differ):

status: 400
{
  "code": "INVALID_NOTIFICATION_REQUEST",
  "details": "Required field 'step' missing for notify operation",
  "error": "Invalid Notification Request",
  "message": "Required field 'step' missing for notify operation",
  "request_id": "daf5f6d6-6f40-42db-a1e5-8b22df279b07"
}

The server rejects this with HTTP 400 because step is missing. It is optional in listener filters, but required when publishing. This example decodes the Aviso server’s JSON error body; a proxy or another server can return plain text, so general error handlers should not assume every body is JSON.

When errors propagate

• Setup can fail when constructing a provider, client, request or state store.
• HTTP methods such as notify and schema raise when the request fails. notify_many returns per-notification results; inspect every result. Invalid batch input can raise before any request is sent.
• Listening can fail when opening the iterator or during iteration. After a terminal stream error is delivered, subsequent iteration is exhausted.
• A required trigger failure stops the listener before that notification reaches your loop. Earlier trigger effects are not undone.

Connection losses and retryable server responses normally cause listeners to reconnect. One-shot publishes are not automatically retried after transport failure: the server may already have stored the notification. An auth provider is asked to refresh after HTTP 401, followed by one retry if refresh succeeds. If authentication is still rejected while opening a watch, the listener raises AuthError. A one-shot HTTP request instead exposes the final 401 as HttpError. See Authentication.

HistoryGapError carries a reason

A history gap ends the iterator. Inspect error.reason:

Do not treat a failed replay as complete. Check server retention and replay limits with the operator, then choose a starting point appropriate to your work. Starting live skips historical work. Also, start_from=None uses an existing saved cursor when one is configured; it does not override it. See choosing a starting position.

TriggerError carries a kind and a sub-kind

trigger_kind identifies the action: echo, log, command, webhook, teams, post, function or unknown. error_kind describes the failure:

Fields that do not apply are None. Required triggers stop the watch when their retry policy is exhausted or fail-fast applies. Optional triggers warn and let processing continue. Only make an action optional when continuing without it is acceptable. See trigger retry settings.

The failing notification does not advance the pending cursor. An earlier notification may already have been checkpointed. Restarting does not guarantee recovery of unfinished work; see State and resume.

Catching is not the same as recovering

Before retrying a publish, determine whether it may already have succeeded. For a malformed stream event or protocol error, reconnecting to the same input may reproduce the failure. Preserve the error and ask the operator to investigate instead of silently moving past it.

Closing a listener cancels and waits for its background task. It does not certify that your analysis finished. Ctrl+C handling while waiting for input does not set a deadline for interrupting Python work or waiting for cleanup.

Hierarchy

All of these inherit directly from AvisoError:

With AsyncAvisoClient

The same exceptions can arise from an awaited method or async for iteration. Use async with on the iterator to await aclose() on exit. With asyncio.run(), catch KeyboardInterrupt outside the run call, as in the async listener. A TaskGroup can wrap task failures in an exception group.

Async

Use AvisoClient for an ordinary script or notebook. This page is for applications already using asyncio, Python’s way of letting tasks share a thread while they wait for input or network responses.

Use AvisoClient by default

You do not need async to receive notifications. The regular listener is the simplest starting point. Use AsyncAvisoClient when your application already has an event loop, or you need several listeners to wait concurrently in one thread.

A complete async listener

Use the quickstart environment: install pyaviso, set AVISO_BASE_URL and provide credentials for pyaviso.Env(). For an anonymous server, pass auth=pyaviso.Anonymous() instead.

The examples use the small mars schema. class is a required od/rd filter; step is an optional whole-number filter. Providers supply both fields and may omit the payload. You only need receiving permission for the listener.

Save this as listen_async.py and run python listen_async.py:

import asyncio
import os

import pyaviso


async def main() -> None:
    client = pyaviso.AsyncAvisoClient(
        base_url=os.environ["AVISO_BASE_URL"], auth=pyaviso.Env()
    )
    async with client.listen("mars", filter={"class": "od"}) as notifications:
        async for notification in notifications:
            print(notification)


try:
    asyncio.run(main())
except KeyboardInterrupt:
    print("Stopped listening")

It prints each matching new notification as indented CloudEvent JSON. Silence means no matching notification has arrived. For a local trial, leave it running and run the provider script in another terminal. Press Ctrl+C to stop.

listen() returns an async iterator directly; do not await the listen() call. async for waits for each notification. async with awaits the iterator’s aclose() when the block exits, including on an exception or a break.

On Python 3.11 and newer, the default asyncio.run() signal handler makes the first Ctrl+C cancel the main task so its context managers can clean up. On Python 3.10, asyncio.run() cancels remaining tasks during its final cleanup. The script works on both: KeyboardInterrupt is caught outside asyncio.run(). Do not swallow asyncio.CancelledError inside your tasks. Cleanup duration depends on work in progress; it is not a fixed deadline.

In a notebook or framework that already runs an event loop, await main() from that environment instead of nesting asyncio.run().

When async helps

To replay operational and research notifications concurrently, replace main in listen_async.py with this definition. This example uses Python 3.11 or newer for TaskGroup:

async def main() -> None:
    client = pyaviso.AsyncAvisoClient(
        base_url=os.environ["AVISO_BASE_URL"], auth=pyaviso.Env()
    )

    async def replay(data_class: str) -> None:
        async with client.listen(
            "mars",
            filter={"class": data_class},
            start_from=0,
            mode="replay_only",
        ) as notifications:
            async for notification in notifications:
                print(notification)

    async with asyncio.TaskGroup() as tasks:
        tasks.create_task(replay("od"))
        tasks.create_task(replay("rd"))

It prints matching retained notifications and ends after both replays finish. Empty history prints nothing. Output from the two listeners can interleave. The task group waits for its tasks; if one fails, it cancels and waits for the others and raises an exception group. Each listener still closes its iterator. See replay limits.

Concurrent publishing (providers)

Providers with publishing permission can use await client.notify_many(...) for a batch. Save this as publish_async.py and run python publish_async.py with the same environment:

import asyncio
import os

import pyaviso


async def main() -> None:
    client = pyaviso.AsyncAvisoClient(
        base_url=os.environ["AVISO_BASE_URL"], auth=pyaviso.Env()
    )
    notifications = [
        {"event_type": "mars", "identifier": {"class": "od", "step": 24}},
        {"event_type": "mars", "identifier": {"class": "rd", "step": 48}},
    ]
    results = await client.notify_many(notifications, concurrency=2)
    for result in results:
        if result.response is not None:
            print("Notification accepted")
        else:
            print("Notification failed:", result.error)


asyncio.run(main())

For valid input and permitted access, it prints Notification accepted twice. Both identifiers are supplied; this schema’s payload is optional. The batch is not atomic: some requests can succeed while others fail. Results stay in input order. See batch publishing before retrying failures.

Multiple listeners

AsyncAvisoClient.listen_many() delivers the notifications of several listeners through one async for loop; see Multiple listeners.

What stays the same

The clients use the same constructor options, filters, value types and auth providers. State-store behavior and its unfinished-work limits also apply to async listeners.

HTTP and schema methods, including admin methods, return awaitables on the async client. listen() is the exception: it returns the iterator directly. The async client itself is not an async context manager; use async with on its listener. Both clients use the same error types.

Mixing the two is a mistake

Synchronous calls block the thread running your event loop, preventing other tasks from making progress. Use AsyncAvisoClient inside async code. If you must call existing synchronous code, asyncio.to_thread() can move it to a worker thread. Async also does not make CPU-heavy analysis nonblocking: move that work out of the event-loop thread.

API reference

Use the quickstart for your first script. This reference is for looking up signatures and return values. Import the public pyaviso module.

For motivation and when-to-use-this guidance on individual surfaces, see the narrative pages. The async client is documented on the Async page; HTTP methods return awaitables on the async client. listen() returns an async iterator directly, without await.

Clients

class pyaviso.AvisoClient(
    *,
    base_url: str | None = None,
    auth: AuthProvider | Anonymous | None = None,
    timeout: float | None = None,
    user_agent: str | None = None,
    state_store: StateStore | None = None,
    heartbeat_interval: float | None = None,
    danger_accept_invalid_certs: bool | None = None,
    flush_cursor_on_exit: bool | None = None,
)

Every argument is optional. What is not given is taken from the environment, then the aviso config file, then the default; see Configuration for the order.

Discover schemas

• schema() -> SchemaCatalog
• schema_for(event_type) -> SchemaResponse

Receive notifications

• listen(event_type=None, *, filter=None, start_from=None, until=None, mode=None, triggers=None, request=None) -> NotificationIterator | FunctionTriggerIterator (without mode, the listener stays live, unless until is given, which ends it like mode="replay_only"; triggers is a Sequence[Trigger]; the returned iterator is also a context manager via with and supports iterator.close() for explicit teardown)

start_from is int | str | None. Integers are exclusive sequence positions; 0 requests retained history after zero. A UTC string such as "2026-06-01T00:00:00Z" selects publication time. None uses saved state if available, otherwise the live edge. An explicit start overrides saved state. The value’s type selects the meaning, so sequence numbers must be unquoted; see Start from a specific position. Use mode="replay_only" with a start position to end at the replay boundary. See State and resume for checkpoint limits.

until is int | str | None: the end point of a replay. An integer is the last sequence to deliver, inclusive; a UTC string ends with the last notification published at or before that time. until implies mode="replay_only" and needs start_from. See Stop at an end point.

• listen_many(listeners, *, start_from=None, until=None, mode=None, on_error=None) -> MultiNotificationIterator

listeners maps a name to a dict of listen() keywords (event_type, filter, start_from, until, mode, triggers) or to a WatchRequest. The start_from, until and mode given here apply to dict entries that set none. The loop yields (name, notification). on_error is "raise" (or None, the default), "continue" or a function taking (name, error); see Error handling. Arguments are checked before any listener opens, the shared start_from, until and mode included. A mistake in the structure of listeners (not a mapping, an empty or non-string name, an unknown key, a missing event_type) or an invalid on_error raises TypeError or ValueError. An invalid listen() argument inside an entry raises what listen() would. When the mistake belongs to one entry, the message names that listener.

Publish notifications (providers)

• notify(*, event_type, identifier=None, payload=None) -> NotifyResponse
• notify_many(notifications, *, concurrency=0) -> list[NotifyResult]

notify_many takes a sequence of notification dicts and returns results in input order. concurrency=0 limits it to 16 in-flight requests. A batch is not atomic; inspect each result. See Publishing.

identifier is a mapping from strings to JSON-compatible Python values. The same applies to each notification passed to notify_many. Structured values such as point-cloud lists are sent as JSON arrays. Cyclic containers are not valid JSON and raise TypeError. Identifier input deeper than 100 nested containers raises ValueError before conversion.

Supply every identifier field defined by the server when publishing, even fields optional in filters. payload=None omits the payload; the schema decides whether a payload is required.

Admin operations (operators)

• wipe_stream(stream_name) -> None
• wipe_all() -> None
• delete_notification(notification_id) -> None

These remove retained data and require appropriate permission. A publish response’s request ID is not a notification ID.

What the client resolved

• config -> ResolvedConfig: every setting with its value and source, the credential by kind and source only. Safe to log.
• pyaviso.resolve_config(*, base_url=None, auth=None, timeout=None, heartbeat_interval=None, danger_accept_invalid_certs=None) -> ResolvedConfig: the same report for those arguments, without building a client.

ResolvedConfig has base_url (SourcedValue | None), timeout, heartbeat_interval, ca_bundle, danger_accept_invalid_certs (each a SourcedValue with .value and .source), auth (ResolvedAuth | None with .kind, .source and .refused), config_file, credentials_file, and as_dict(). See Configuration.

Constructor options and lifecycle

base_url includes the HTTP or HTTPS scheme; when None it comes from AVISO_BASE_URL or the config file, and ConfigError is raised if neither has one. auth=None searches the environment and the credential files; see Authentication. Pass auth=pyaviso.Anonymous() to send no credentials. state_store=None does not persist checkpoints. flush_cursor_on_exit=False leaves the final pending cursor unflushed; enabling it does not acknowledge completed work. See shutdown behavior.

timeout and heartbeat_interval are seconds. When None, each comes from the config file if it is set there; otherwise timeout imposes no request timeout and heartbeat_interval uses 30 seconds as the expected server heartbeat interval (it does not set the server’s cadence). timeout bounds ordinary requests such as notify and schema; it does not apply to listen, whose stream is meant to stay open. user_agent=None uses aviso/<crate-version>. danger_accept_invalid_certs=None keeps certificate validation enabled unless the config file’s tls: block turns it off.

Use with client.listen(...) to close a synchronous listener. The synchronous client’s own __enter__ / __exit__ do not close its listeners. The async client is not an async context manager; use async with on its iterator.

pyaviso.AsyncAvisoClient is the same shape. notify / schema / notify_many / schema_for / wipe_* / delete_notification return awaitables; listen returns an AsyncNotificationIterator.

Value types

pyaviso.Notification(event_type, sequence, identifier, payload, cloudevent=None)

Properties: event_type, sequence, identifier, payload, cloudevent. Method: as_dict(). Unhashable (the payload may be a dict).

str(notification) formats the original cloudevent as indented JSON. For a manually constructed notification without cloudevent, it formats event_type, sequence, identifier, and payload instead. as_dict() returns the client convenience fields, including cloudevent when present. repr(notification) remains a compact debugging summary. Identifier values retain the JSON shape emitted by the server.

pyaviso.NotifyResponse(status, request_id, processed_at)

Properties: status, request_id, processed_at. Method: as_dict().

pyaviso.NotifyResult (returned by notify_many)

Properties: zero-based index, boolean ok, response (NotifyResponse on success, otherwise None) and error (exception on failure, otherwise None).

pyaviso.SchemaCatalog

Properties: status, event_types, total_schemas, schema. Method: as_dict(). The schema property is a dict keyed by event type, whose values match the per-event-type schema below.

pyaviso.SchemaResponse

Properties: status, event_type, schema. Method: as_dict(). The schema is a dict with two keys: payload (a {"required": bool} shape) and identifier (a dict keyed by identifier field name, each value naming the validator type, the required flag (which gates whether a filter or watch call must include the field, not whether a notify call must), and any type-specific metadata).

Watch shape

pyaviso.WatchRequest

Constructors:

• WatchRequest.watch(event_type)
• WatchRequest.watch_from(event_type, start_from)
• WatchRequest.replay_only(event_type, start_from, *, until=None)

Builders: .with_filter(dict), .with_triggers(list). Properties: event_type, mode.

pyaviso.WatchMode is a str + Enum with members WATCH = "watch" and REPLAY_ONLY = "replay_only".

pyaviso.NotificationIterator and pyaviso.AsyncNotificationIterator: returned by listen. The sync one implements __iter__ / __next__ / run / close; the async one implements __aiter__ / __anext__ / run / aclose. Both are iterator context managers: with closes the sync iterator; async with awaits async closure. A loop break alone does not close an iterator you still hold. run() (awaited on the async one) reads the stream to its end, running its triggers, then closes it. When the triggers include Trigger.function, listen returns a pyaviso.FunctionTriggerIterator (or pyaviso.AsyncFunctionTriggerIterator) with the same methods.

pyaviso.MultiNotificationIterator and pyaviso.AsyncMultiNotificationIterator: returned by listen_many, with the same methods as above, yielding (name, notification), plus errors: a list of pyaviso.ListenFailure, each with listener (the name), kind (a pyaviso.ListenFailureKind, LISTENER or TRIGGER) and error. A listener or function failure raised from the loop carries error.listener. When every listener has failed, the loop raises AvisoError with a failures list. Every AvisoError has both attributes; they are None when not set.

Triggers

pyaviso.Trigger with class-method constructors:

• Trigger.echo(*, retries=0, required=True, label=None)
• Trigger.log(path, *, retries=0, required=True)
• Trigger.command(cmd, *, env=None, working_dir=None, retries=0, required=True, timeout=None, fail_fast=True) (Unix only)
• Trigger.webhook(url, *, method=None, headers=None, body_template=None, retries=0, required=True, timeout=30.0, fail_fast=True)
• Trigger.teams(url, *, retries=0, required=True, timeout=30.0, fail_fast=True)
• Trigger.post(url, *, retries=0, required=True, timeout=30.0, fail_fast=True)
• Trigger.function(func, *, retries=0, required=True, label=None): calls func(notification) in the reading thread or event loop; see Function

Chainable setters: .retries(n), .required(on), .timeout(seconds), .fail_fast(on), .label(name).

Setters return new values. Webhook method=None means POST. Timeout and fail-fast setters affect only command and HTTP triggers, and raise ValueError on a function trigger; label affects echo and names a function trigger in its errors. Echo and log output the smaller notification view, while post forwards the original CloudEvent. See Triggers.

pyaviso.HttpMethod is a str + Enum with members POST, GET, PUT, PATCH, DELETE.

Auth providers

pyaviso.Bearer(token), pyaviso.Basic(username, password=""), pyaviso.Env(), pyaviso.ConfigFile(path), pyaviso.Chain(*providers).

Type alias: pyaviso.AuthProvider = Bearer | Basic | Env | ConfigFile | Chain.

State stores

pyaviso.MemoryStore(), pyaviso.JsonFileStore(path).

Type alias: pyaviso.StateStore = MemoryStore | JsonFileStore.

Exceptions

Base: pyaviso.AvisoError.

Subclasses:

• pyaviso.TransportError
• pyaviso.HttpError (attrs: status, body, request_id)
• pyaviso.AuthError
• pyaviso.DecodeError
• pyaviso.MalformedEventError
• pyaviso.HistoryGapError (attrs: reason, max_allowed, expected, observed)
• pyaviso.StreamProtocolError (attrs: message, request_id)
• pyaviso.ConfigError
• pyaviso.StateStoreError
• pyaviso.TriggerError (attrs: trigger_kind, error_kind, path, exit_code, stderr_tail, status, body_tail, reason, timeout_seconds, context, field, template_kind)

Version

pyaviso.__version__ is the Python distribution version. pyaviso.VERSION is the Rust crate version. They are pinned to the same value via maturin’s dynamic = ["version"].

Troubleshooting

Choose the symptom that matches what you see. Open a panel for checks and links to the relevant guide. Keep the exception message and any request ID when asking your server operator for help; do not include credentials.

C++ binding

aviso ships a C++ binding as a stable C ABI plus a header-only C++ facade over it. The aviso-ffi crate builds a libaviso_ffi library and generates a C header (aviso.h); the hand-written aviso.hpp adds RAII handles, std::string and std::optional ergonomics, and a throwing aviso::Error.

The point of the C ABI is packaging. A C++ application links the prebuilt library and compiles the facade with its own toolchain, so the binding works under C++17 and needs no Rust toolchain in the consumer’s build.

What you can do today

• Build a client from a base URL, with a Bearer token, HTTP Basic credentials, or a credential the client finds for itself.
• Publish notifications with notify; see Publishing.
• Listen to a stream with a callback handler, with filtering and replay; see Listening.
• Listen with several watches through one handler, each with its own filter; see Several watches at once.
• Attach triggers (echo, log, command, webhook, Teams, post) to a listener; see Triggers.
• Read schemas with schema and schema_for, and run the operator-only admin calls wipe_stream, wipe_all, and delete_notification; see Operations.
• Call verbs asynchronously: each except notify_many has a *_async form returning a std::future; see Async.
• Read structured errors: every failure throws an aviso::Error whose what() is a human-readable message and whose error() returns the kind, HTTP status, and request id.

Credentials

When you hold the credential in your code, name it on the builder. bearer_auth sends a token and basic_auth sends a username and password:

aviso::Client client = aviso::ClientBuilder("https://aviso.example.org")
                           .bearer_auth(token)
                           .build();

An empty token throws from build(). A credential named this way is sent to whatever address you gave, plain http:// included; writing it into the call is choosing where it goes.

When the credential is supplied by the environment or by a file instead, call discover_auth and let the client find it:

aviso::Client client = aviso::ClientBuilder("https://aviso.example.org")
                           .discover_auth()
                           .build();

It looks in the environment, then the auth: block of ~/.config/aviso/config.yaml, then ~/.config/aviso/credentials.yaml, and stops at the first one that has a credential. Finding nothing leaves the client anonymous. A source that exists but cannot be read throws from build().

A credential found this way is not sent to a plain http:// address unless it is loopback, and build() throws instead. Nothing in the code named the credential, so a mistyped host would otherwise send it in the clear. Use an https address, or pass the credential yourself with bearer_auth or basic_auth.

Starting from the config file

If the machine already has ~/.config/aviso/config.yaml set up for the aviso command, from_file starts the builder from it: server address, timeouts and TLS settings from the file, plus a credential found the same way discover_auth finds one.

aviso::Client client = aviso::ClientBuilder::from_file().build();

Setters called afterwards replace what the file said, and base_url lets you supply an address the file did not have:

aviso::Client client = aviso::ClientBuilder::from_file()
                           .base_url("https://other.example.org")
                           .bearer_auth(token)
                           .build();

A missing default file sets nothing. from_file(path) reads a specific file, which must exist. Either way, a file that cannot be read throws from build(), and so does a found credential paired with a plain http:// address that is not loopback, whether the address came from the file or from a later base_url call. Naming the credential with bearer_auth or basic_auth lifts that.

Starting from the environment

from_environment behaves like from_file, except that the address may also come from AVISO_BASE_URL, which takes precedence over the file. The aviso command and the Python binding use the same order, so a program built this way needs no arguments on a machine configured for either:

aviso::Client client = aviso::ClientBuilder::from_environment().build();

If neither the environment nor the file provides an address, build() throws a configuration error that names both sources.

Inspecting the resolved configuration

When a connection fails, the first question is which server and which credential the client is using. describe() reports this for any builder, without building a client:

aviso::ClientBuilder builder = aviso::ClientBuilder::from_environment();
std::cout << builder.describe();

base_url                    https://aviso.example.org/              (environment AVISO_BASE_URL)
auth                        bearer                                  (credentials file /home/me/.config/aviso/credentials.yaml)
timeout                     30s                                     (config file /home/me/.config/aviso/config.yaml)
heartbeat_interval          none                                    (default)
ca_bundle                   none                                    (default)
danger_accept_invalid_certs false                                   (default)

Each line shows a setting, its value and, in parentheses, its source. The report contains no secrets: the credential is described by kind and source, never by value, and any user:password@ is removed from the address. It can therefore be included as it is in a log or a support request. A discovered credential that build() would refuse is shown with the reason on its auth line. A builder created with ClientBuilder(url) that has no named credential and has not called discover_auth reports auth as anonymous.

describe() throws aviso::Error for an error the builder already holds, such as a null address, or for a config file that exists but cannot be read.

A first call

#include "aviso.hpp"
#include <iostream>

int main() {
  try {
    aviso::Client client = aviso::ClientBuilder("http://localhost:8000")
                               .basic_auth("user", "pass")
                               .build();
    std::cout << client.schema() << '\n';
  } catch (const aviso::Error& error) {
    std::cerr << "aviso error: " << error.what() << '\n';
    return 1;
  }
}

How calls behave

Every call blocks until the server responds and throws aviso::Error on any failure, so wrap them in try / catch. JSON-shaped data crosses as strings: notify takes its payload as a JSON string and the calls return their responses as JSON strings, which you parse with whatever JSON library your application already uses.

These calls must not run inside a listener or async callback (a runtime thread); doing so throws an aviso::Error with kind AvisoErrorKind_InvalidUsage rather than deadlocking. See Listening for the callback surface.

Some objects are used up by the call that consumes them: a ClientBuilder by build(), a WatchRequest by the watch or WatchSet it is given to, a Trigger by add_trigger, and a WatchSet by watch_many. Moving from a Client, Watch or any of these leaves the source empty as well. Calling a method on a used-up or moved-from object throws an aviso::Error with kind AvisoErrorKind_InvalidUsage, whose message names the object.

Reading an error

error.what() is a message for humans. error.error() is the part to branch on: an ErrorInfo with a kind, the http_status when the server answered, and the server’s request_id to quote when asking for help.

The kind tells you what to do next. AvisoErrorKind_Transport means the server or network was unreachable and a retry may work. AvisoErrorKind_Http means the server answered and said no; look at http_status and the message. A credential the server rejects on a request arrives this way, as a 401 or 403. AvisoErrorKind_Auth covers the other credential problems: none was available, one would have travelled in the clear to a non-loopback http address, or a watch was refused even after refreshing the credential. None of these is worth a retry. AvisoErrorKind_InvalidInput means the calling code passed something the binding could see was wrong before any request went out, such as identifier JSON that is not an object.

} catch (const aviso::Error& error) {
  const aviso::ErrorInfo& info = error.error();
  if (info.kind == AvisoErrorKind_Transport) {
    // retry later
  } else if (info.kind == AvisoErrorKind_Http && info.http_status == 401) {
    // the server rejected the credential; do not retry
  } else if (info.kind == AvisoErrorKind_Http && info.http_status == 404) {
    // the event type is not on this server
  }
}

examples/cpp/resilience/03_error_handling.cpp provokes seven different errors on purpose and shows a branch for each.

Building against the library

Eighteen worked, tested examples live in examples/cpp, grouped by purpose: basics/, resilience/, triggers/ and async/. Each one links the library and compiles the facade through CMake, the way your own program would, and CI runs every one against a real server. For local development, build the library from the workspace first:

cargo build -p aviso-ffi
cmake -S examples/cpp -B build/cpp
cmake --build build/cpp
./build/cpp/01_schema                          # nothing configured: says so, exits 0
AVISO_BASE_URL=http://localhost:8000 ./build/cpp/01_schema

The examples connect through from_environment(), so they need no further setup on a machine where the aviso command is configured; 01_schema prints the resolved configuration before its first request. The two CMake cache variables AVISO_FFI_INCLUDE_DIR and AVISO_FFI_LIB_DIR default to the in-tree locations; point them at a prebuilt drop to build against shipped artifacts with no Rust toolchain. The examples README lists every file with what it shows.

Installing with cargo-c

For a standard system install rather than an in-tree build, cargo-c drops the library, a pkg-config .pc, and the headers in the usual layout:

cargo install cargo-c   # once
cargo cinstall -p aviso-ffi --release --prefix=/usr/local --libdir=/usr/local/lib

A consumer then discovers it through pkg-config, with no in-tree paths and no Rust toolchain:

find_package(PkgConfig REQUIRED)
pkg_check_modules(AVISO_FFI REQUIRED IMPORTED_TARGET aviso_ffi)
target_link_libraries(my_app PRIVATE PkgConfig::AVISO_FFI)

The install places the headers under include/aviso_ffi/, and the .pc puts that directory on the include path, so #include "aviso.hpp" works unchanged.

The C header and the facade

aviso.h is generated from the Rust surface by cbindgen and is the source of truth for the ABI; aviso.hpp is hand-written over it and is the recommended surface for C++ callers. C callers can use aviso.h directly: every fallible call returns an owning AvisoOutcome that you inspect, take a value out of, and free.

Publishing

notify publishes one notification and returns the server’s response as a JSON string. Its map overload is convenient for string-only identifiers. The payload is an optional JSON string. Like every call it throws aviso::Error on failure (see Overview).

std::map<std::string, std::string> identifier = {{"date", "20260101"},
                                                 {"time", "0000"}};
std::string response = client.notify("test_event", identifier);
// With a payload:
std::string with_payload =
    client.notify("test_event", identifier, std::string(R"({"value": 42})"));

Use notify_json when an identifier contains arrays, objects, or other JSON values. Spatial coordinates use latitude first. These spatial examples use the server’s public observations schema, which requires a date, a point cloud, and a payload:

const std::string identifier = R"({
  "date": "20260601",
  "point_cloud": [[46, 8], [47, 9]]
})";
std::string response = client.notify_json(
    "observations", identifier, std::string(R"({"source":"stations"})"));

A polygon has the same [[lat, lon], ...] shape as a point cloud, but needs at least four pairs with the first pair repeated last. Clouds need no closing repeat; duplicate points are valid and their order is preserved. Subscribers filter clouds with polygon, not point_cloud. The built-in point is only a watch/replay filter for polygon streams, not a provider identifier. Do not quote arrays inside the JSON object. The notify_json_async method provides the same path for asynchronous calls.

To see which identifier fields a stream expects, read its schema first with schema_for; see Operations.

Publishing many at once

notify_many sends a whole batch concurrently and returns a JSON array with one entry per input, in order. Over a single HTTP/2 connection a batch that would take many sequential round-trips finishes in roughly one. You pass the batch as a JSON array string of {event_type, identifier?, payload?} objects, built with whatever JSON you like, and an optional max_concurrency (0 selects a default).

const std::string notifications = R"([
  {"event_type": "observations", "identifier": {"date": "20260601", "point_cloud": [[46, 8], [47, 9]]}, "payload": {"source": "stations-a"}},
  {"event_type": "observations", "identifier": {"date": "20260602", "point_cloud": [[48, 10], [49, 11]]}, "payload": {"source": "stations-b"}}
])";
std::string results = client.notify_many(notifications);

The batch is not atomic. A per-item failure comes back as an "error" entry in the array rather than throwing, so one bad notification does not sink the rest; only a malformed array (not valid JSON, or an item missing event_type) throws. Each entry is {"index", "status", "response"} on success or {"index", "status", "error"} on failure, where the error carries kind, http_status, message, and request_id.

A complete example

examples/cpp/basics/02_publish.cpp publishes one notification with a string identifier. examples/cpp/basics/06_publish_polygon.cpp sends a spatial identifier and a required payload with notify_json. examples/cpp/basics/04_publish_many.cpp publishes a batch with notify_many, with one bad item so you can see a per-item failure next to two successes. CI compiles and runs all three on every change, so they never drift from the binding.

Listening

A listener streams notifications to your code as they arrive. In C++ you start one with client.watch, passing a WatchRequest that says what to listen to and a handler that says what to do with each notification. The library calls your handler on a background thread until the listener ends, whether because you stopped it or because it failed.

The handler

Subclass aviso::NotificationHandler and override two methods. on_notification runs once per notification and returns whether to keep going. on_end runs once, after the last notification, and tells you whether the listener stopped because you asked or because it failed.

class Handler : public aviso::NotificationHandler {
 public:
  bool on_notification(const aviso::Notification& n) override {
    std::cout << n.event_type() << " #" << n.sequence() << " "
              << n.identifier_json() << " " << n.payload_json() << '\n';
    return true;  // keep going; return false to stop
  }
  void on_end(const std::optional<aviso::ErrorInfo>& error) override {
    if (error) {
      std::cerr << "watch failed: " << error->message << '\n';
    }
  }
};

Do not leave on_end empty. It is the only place a failed watch is reported. An exception thrown out of on_notification also ends up there: it stops the watch, and on_end receives an AvisoErrorKind_Internal error whose message names the exception. wait() returns normally whether the watch ended because your handler said so or because the connection was refused, so a handler that ignores on_end turns every failure into a quiet exit. The examples keep a small base class in common.hpp that stores the error, and a finish() helper that turns it into the exit code.

The callbacks run on a runtime thread, so the handler must be thread-safe. They must not make blocking aviso calls: a blocking call from inside a callback throws an aviso::Error of kind AvisoErrorKind_InvalidUsage, and the async verbs are the way to make requests from there (see Async). The Notification you receive is a borrowed view, valid only for that call. Its accessors return owned std::strings, so copy out anything you want to keep.

Starting and stopping

Build a WatchRequest, then call client.watch. It returns a Watch whose destructor stops the listener and waits for it, so you cannot leave one running by accident. The handler you pass must outlive the Watch. client.watch consumes the request: calling a setter on it afterwards, or passing it to another watch, throws an aviso::Error of kind AvisoErrorKind_InvalidUsage. Build a new request for each watch.

Handler handler;
aviso::WatchRequest request("test_event");
aviso::Watch watch = client.watch(request, handler);

// Block until listening ends: the handler returned false, the stream ended,
// or it failed. Or just let `watch` go out of scope to stop and wait.
watch.wait();

watch.stop() asks for a graceful stop. It returns at once and is safe from any thread, including from inside the handler. After a stop(), on_end runs with no error, so a stopped watch looks the same as one whose handler returned false. watch.wait() blocks until on_end has returned, so do not call it from inside a callback.

A signal handler may not call stop() itself, since almost nothing is allowed inside one. The pattern that works is to set a flag in the signal handler and have a small thread call stop() when the flag turns.

examples/cpp/basics/03_listen.cpp is this in full: it prints each notification and stops itself after three. examples/cpp/resilience/04_stop_from_outside.cpp runs until Ctrl+C or a timer, and stops the way a real listener would.

Several watches at once

To listen to several things through one handler, give each WatchRequest a name in a WatchSet and call client.watch_many. The handler derives from aviso::MultiNotificationHandler. It works like the single-watch handler, and on_notification also receives the name of the watch:

class Printer : public aviso::MultiNotificationHandler {
 public:
  bool on_notification(const std::string& name,
                       const aviso::Notification& n) override {
    std::cout << name << ": " << n.identifier_json() << '\n';
    return true;
  }
  void on_end(const std::optional<aviso::ErrorInfo>& error) override {
    if (error) {
      std::cerr << "listening failed: " << error->message << '\n';
    }
  }
};

aviso::WatchRequest operational("mars");
operational.filter_json(R"({"class": "od"})");
aviso::WatchRequest research("mars");
research.filter_json(R"({"class": "rd", "step": 0})");

aviso::WatchSet watches;
watches.add("operational", operational).add("research", research);

Printer printer;
aviso::Watch watch = client.watch_many(watches, printer);
watch.wait();

Each line shows which watch delivered the notification:

operational: {"class":"od","step":"6"}
research: {"class":"rd","step":"0"}
operational: {"class":"od","step":"12"}

• Each request keeps its own event type, filter, start position and triggers.
• The watches are read in turn, so a busy watch cannot starve a quiet one.
• The callbacks never run at the same time, so the handler needs no lock for its own state.
• The returned Watch works as for a single watch: stop(), wait() and the destructor act on every watch in the set.
• watch_many consumes the WatchSet, and add consumes each WatchRequest. Using either again throws an aviso::Error of kind AvisoErrorKind_InvalidUsage.

When one watch fails

By default, one failing watch stops them all, and on_end receives its error. The message begins with the name of the watch:

listening failed: watch 'research': http 400: ... Unknown field 'stepp' ...

To drop only the failing watch and keep the others, override on_error, which also receives the name, and return true:

bool on_error(const std::string& name,
              const aviso::ErrorInfo& error) override {
  std::cerr << name << " dropped: " << error.message << '\n';
  return true;
}

on_end still receives an error if every watch fails, so the program cannot end quietly with nothing running. An exception thrown from on_notification or on_error stops every watch, and on_end receives an AvisoErrorKind_Internal error whose message names the exception.

examples/cpp/basics/07_watch_many.cpp is a complete program: it runs two watches and stops once each has delivered three notifications.

Resuming where you left off

Every notification carries a sequence number. If your process stops, the last sequence you handled is all you need to carry on without a gap: ask for everything after it, then stay live. The server replays what you missed first and switches to live delivery on the same connection.

aviso::WatchRequest request("test_event");
request.watch_from_sequence(last_handled);  // replay after this, then live

Where you keep last_handled is up to you. A file is enough for a single process; record it in on_notification after handling, not before, so a crash mid-handler replays that notification rather than skipping it. That gives you at-least-once delivery, which is what you want for anything that matters.

watch_from_date does the same with a timestamp instead of a sequence.

examples/cpp/resilience/01_resume_from_sequence.cpp keeps the position in a file. Run it, stop it, publish a few notifications, run it again: the missed ones arrive first.

Reading history only

Sometimes you want a batch, not a feed. replay_from_sequence and replay_from_date deliver what the server has kept and then end the watch by themselves, without waiting for anything new. The handler can return true throughout; wait() still returns when history runs out.

aviso::WatchRequest request("test_event");
request.replay_from_date("2026-01-01T00:00:00Z");  // history, then end

A server caps how much one replay may return. When you hit the cap the watch ends with an error of kind AvisoErrorKind_HistoryGap whose message names the limit, and the notifications you did get are complete and in order up to the last one. Ask again with replay_from_sequence from that last sequence to get the rest, and repeat until the watch ends without an error.

examples/cpp/resilience/02_replay_only.cpp does exactly that: it reads everything since a date in as many batches as the cap requires, then exits with a count.

Stopping at an end point

replay_until_sequence and replay_until_date end the replay at an end point instead of at the last stored notification. A sequence is the last one delivered, inclusive; a date ends with the last notification published at or before that time. Combine either with a replay_from_* setter, in any order:

aviso::WatchRequest request("test_event");
request.replay_from_date("2026-01-01T00:00:00Z")
    .replay_until_date("2026-01-02T00:00:00Z");  // one day, then end

The start is exclusive and the end inclusive for sequences: replay_from_sequence(10) with replay_until_sequence(20) delivers the matching notifications with sequences 11 to 20. An end point in the future ends at the last stored notification. If the connection drops, the watch resumes up to the same end point.

An end point without a replay_from_* setter makes on_end report AvisoErrorKind_InvalidInput when the watch starts, since a live watch has no end. A sequence end that is not after a sequence start is reported as AvisoErrorKind_Config. An end point needs aviso-server 0.13.0 or later; an older server rejects the request with an AvisoErrorKind_Http error, status 400.

Filtering

filter_json narrows the stream to notifications whose identifier matches a JSON object: an exact value per key, or a server-defined rule object.

aviso::WatchRequest("test_event").filter_json(R"({"date":"20260101"})");

Fields you leave out match anything. The filter is applied by the server, so notifications that do not match never reach your process. examples/cpp/basics/05_filter.cpp listens for one date and lets everything else go past.

Numeric and enum constraints

With the schema and seeds from the weather tutorial, use this request with the Handler above and a client built as in A first call, using your test server’s address and credentials. Replay delivers B and C, then ends; inspect their labels in n.payload_json().

aviso::WatchRequest request("weather");
request.replay_from_sequence(0).filter_json(R"({
  "date": "20260913",
  "severity": {"gte": 5},
  "anomaly": {"between": [40, 50]},
  "region": {"in": ["north", "south"]}
})");
Handler handler;
auto watch = client.watch(request, handler);
watch.wait();

For live delivery, omit replay_from_sequence(0) and start before publishing. The raw string contains JSON objects with numeric operands, not quoted JSON objects. See Filters for supported operators and schema requirements.

Triggers

A trigger is a per-notification side effect attached to a listener. When it processes a notification, its triggers fire before the notification reaches your handler. Build a trigger with a factory, tune it with the chainable setters, and attach it to a WatchRequest with add_trigger.

Kinds

• Trigger::echo() writes each notification as one line of JSON to standard output. The one to try first, because it shows you exactly what every other trigger receives.
• Trigger::log(path) appends each notification as JSON to a file, across runs. A durable record with no file handling of your own.
• Trigger::command(cmd) runs /bin/sh -c <cmd> per notification (Unix only). The notification arrives as environment variables: AVISO_EVENT_TYPE, AVISO_SEQUENCE, one AVISO_IDENTIFIER_<FIELD> per identifier field, and AVISO_NOTIFICATION_JSON for the whole thing. The command’s own stdout is captured and dropped, so write to a file if you want to see output.
• Trigger::webhook(url) sends an HTTP request per notification, with a settable method, headers, and a body template that can name notification fields, such as {{ notification.identifier.date }}.
• Trigger::teams(url) posts an Adaptive Card to a Teams Workflows webhook.
• Trigger::post(url) HTTP POSTs the raw CloudEvent envelope.

Triggers fire whether or not your handler does anything with the notification. A handler that only counts, paired with a trigger that does the real work, is a perfectly good listener.

Attaching

add_trigger consumes the trigger. A factory result attaches directly:

aviso::WatchRequest request("test_event");
request.add_trigger(aviso::Trigger::log("/var/log/aviso/notifications.log"));
aviso::Watch watch = client.watch(request, handler);

A trigger is move-only, so to tune one with the setters, build it as a named value and move it in:

aviso::Trigger hook = aviso::Trigger::webhook("https://example.com/hook");
hook.method(aviso::HttpMethod::Post)
    .header("Authorization", "Bearer " + token)
    .retries(3)
    .timeout_secs(10);
request.add_trigger(std::move(hook));

After add_trigger, hook is used up. Calling a setter on it, or attaching it again, throws an aviso::Error of kind AvisoErrorKind_InvalidUsage.

Reliability

Every trigger has retries (default 0), required (default true), a timeout_secs, and fail_fast (default true). Set label to name the trigger in error messages when you attach more than one.

required is the setting that decides what a failure means. A required trigger that still fails after its retries ends the listener: on_end receives an aviso::ErrorInfo of kind AvisoErrorKind_Trigger, with trigger_kind naming the trigger and error_kind naming the failure. An optional trigger (required(false)) that fails is skipped and the listener carries on. Nothing tells your code about it: there is no callback and no log you can read from C++, and the notification reaches your handler as if the trigger had worked. If you need to know when a trigger fails, make it required, or have the trigger leave its own trace. Use required for the side effect the listener exists to perform, and optional for the ones that are nice to have.

Triggers run in the order you added them, for every notification, before your handler sees it.

Complete examples

Each file in triggers/ covers one kind, and the last one is a composition:

• 01_echo.cpp and 02_log.cpp are the two simplest, with a handler that only counts.
• 03_command.cpp runs a shell command that appends the AVISO_* variables to a file, then prints the file.
• 04_webhook.cpp POSTs a templated body to a URL. It opens a tiny receiver on a loopback port so it runs without one, and prints what arrived.
• 05_multiple.cpp attaches a required log, an optional echo, and an optional command that always fails, so you can see the failure leave the listener running. Change it to required(true) and the listener ends on the first notification instead.

Every one stops itself after three notifications; publish from another terminal to drive them.

Operations

The schema lookups and the admin calls. Each one either succeeds or throws aviso::Error (see Overview).

Schemas

schema returns the full catalogue (GET /api/v1/schema); schema_for returns one stream’s schema (GET /api/v1/schema/{event_type}). Both return JSON strings.

std::string catalogue = client.schema();
std::string one = client.schema_for("test_event");

Admin

The admin calls are operator-only and return nothing on success. wipe_stream removes every notification for one stream, wipe_all removes them for every stream, and delete_notification removes a single notification by its <event_type>@<sequence> id.

client.wipe_stream("test_event");
client.delete_notification("test_event@42");
client.wipe_all();

Async

Every blocking verb except notify_many has an async form that returns a std::future and runs on a background thread, so several calls can be in flight at once. The async forms are also safe to call from inside a listener or async callback, where a blocking verb would throw AvisoErrorKind_InvalidUsage.

The future holds the same value the blocking verb returns: a JSON string for notify_async, schema_async, and schema_for_async, and nothing (std::future<void>) for wipe_stream_async, wipe_all_async, and delete_notification_async. Calling .get() blocks for the result and rethrows any aviso::Error.

std::future<std::string> published =
    client.notify_async("test_event", identifier);
std::future<std::string> catalogue = client.schema_async();

std::cout << published.get() << '\n';  // rethrows aviso::Error on failure
std::cout << catalogue.get() << '\n';

When to reach for them

For publishing a batch, notify_many already sends concurrently and reports per-item failures without throwing; see Publishing. It has no async form because it does not need one. The async verbs earn their keep when the requests are not all publishes, or when you have work to do between starting them and collecting. Inside a callback they are the only option, since a blocking verb throws there.

The pattern for many requests is: start them all, keep the futures, then get() each one. A failed request throws from its own get() and the others are unaffected, so wrap each get() in a try if one failure should not stop you collecting the rest.

Complete examples

examples/cpp/async/01_basic.cpp puts two requests in flight at once and times them. examples/cpp/async/02_fan_out.cpp starts ten publishes and a schema lookup, then collects them all in about one round trip.

Triggers

listeners:
  - name: my-listener
    event: mars
    identifiers:
      class: od
    triggers:
      - type: echo
      - type: webhook
        url: "https://hooks.example.com/notify"
        headers:
          Authorization: "Bearer {{ env.HOOK_TOKEN }}"

Echo trigger

aviso listen --event mars --identifiers '{"class":"od"}'
aviso listen --event mars --identifiers '{"class":"od"}' | jq -r '.payload'

triggers:
  - type: echo
    retries: 0          # optional, default 0
    required: true      # optional, default true

new notification (listener: my-listener, trigger: echo):
{
  "event_type": "mars",
  "sequence": 42,
  "identifier": {
    "class": "od",
    "date": "20260601",
    ...
  },
  "payload": { ... }
}

{"event_type":"mars","sequence":42,"identifier":{"class":"od",...},"payload":{...}}

Log trigger

triggers:
  - type: log
    path: /var/log/aviso/mars.log    # required
    retries: 0                       # optional, default 0
    required: true                   # optional, default true

Error in listener my-listener: trigger log(/var/log/aviso/mars.log) failed: io: No such file or directory (os error 2)
  Hint: log trigger could not open `/var/log/aviso/mars.log`: No such file or directory (os error 2). Common causes: the parent directory does not exist (the log trigger does NOT create directories), or the path is not writable by the aviso user. Verify the parent exists and the user can write to it: `ls -ld $(dirname '/var/log/aviso/mars.log')`
  Other listeners continue.

Command trigger

triggers:
  - type: command
    command: "echo {{ notification.event_type }}@{{ notification.sequence }} >> /tmp/seen.log"
    env:                                         # optional; values are literal (NOT templated)
      DATA_DIR: /var/lib/aviso/data
      MODE: production
    working_dir: /var/lib/aviso                  # optional
    timeout: 30s                                 # optional
    retries: 2                                   # optional, default 0
    required: true                               # optional, default true
    fail_fast: true                              # optional, default true

command: "curl -X POST https://api.example/notify -d '{{ notification.payload }}' -H 'Authorization: Bearer {{ env.API_TOKEN }}'"

# Style A: template engine
command: "ingest {{ notification.event_type }} {{ notification.sequence }}"

# Style B: env vars (often shorter and easier to escape)
command: "ingest \"$AVISO_EVENT_TYPE\" \"$AVISO_SEQUENCE\""

Hint: command trigger exited non-zero. Common causes: the rendered command is malformed (check `{{ notification.* }}` substitutions; the rendered command appears in DEBUG-level tracing only), the command is missing or not on PATH (check the shell's behaviour with `/bin/sh -c '<your command>'`), or the command genuinely failed (check the stderr tail above).

Webhook trigger

triggers:
  - type: webhook
    # Required, template-rendered.
    url: "https://hooks.example.com/notify"
    # Optional; POST is the default.
    method: POST
    # Optional headers and body.
    headers:
      Authorization: "Bearer {{ env.WEBHOOK_TOKEN }}"
      X-Source: "aviso-listener"
    body_template: |
      {
        "seq": {{ notification.sequence }},
        "payload": {{ notification.payload }}
      }
    # Optional; defaults to 30s.
    timeout: 30s
    # Optional; defaults to 0.
    retries: 2
    # Optional; both default to true.
    required: true
    fail_fast: true

{
  "event_type": "mars",
  "sequence": 42,
  "identifier": {...},
  "payload": {...}
}

body_template: |
  {
    "who": "{{ notification.identifier.class }}",
    "what": "{{ notification.event_type }}",
    "when": "{{ notification.identifier.date }}"
  }

body_template: |
  {
    "alert": {
      "title": "aviso {{ notification.event_type }} #{{ notification.sequence }}",
      "details": {{ notification.payload }},
      "source": "aviso-listener"
    }
  }

Error in listener my-listener: trigger webhook failed: webhook:
status=400 body_tail={"error":"missing_required_field","field":"alert.title"}
  Hint: webhook returned 4xx (400 Bad Request) which is TERMINAL
  (no retries) per the dispatcher contract: 4xx means the receiver
  rejected the request, retrying with the same notification will
  fail identically. Check the webhook URL, headers, and body_template;
  the receiver's response body is included above and may name the
  specific field that failed validation.
  Other listeners continue.

WebhookConfig {
  url_template: <compiled-url-template-redacted>,
  method: Post,
  header_count: 2,
  body_template: <compiled-body-template-redacted>
}

triggers:
  - type: webhook
    url: "{{ env.SLACK_WEBHOOK_URL }}"
    body_template: >-
      {"text": "aviso {{ notification.event_type }}
      sequence {{ notification.sequence }}"}

triggers:
  - type: webhook
    url: "{{ env.DISCORD_WEBHOOK_URL }}"
    body_template: >-
      {"content": "aviso {{ notification.event_type }}
      sequence {{ notification.sequence }}"}

triggers:
  - type: webhook
    url: "https://alerts.example.org/api/v1/incidents"
    method: POST
    headers:
      Authorization: "Bearer {{ env.ALERT_TOKEN }}"
      X-Source: "aviso-mars"
    body_template: |
      {
        "title": "Mars notification #{{ notification.sequence }}",
        "severity": "info",
        "tags": ["aviso", "mars", "{{ notification.identifier.class }}"]
      }
    retries: 3
    timeout: 10s

triggers:
  - type: webhook
    url: "https://api.github.com/repos/example/repo/dispatches"
    method: POST
    headers:
      Authorization: "Bearer {{ env.GITHUB_TOKEN }}"
      Accept: "application/vnd.github+json"
    body_template: |
      {
        "event_type": "aviso",
        "client_payload": {
          "sequence": {{ notification.sequence }},
          "event": "{{ notification.event_type }}"
        }
      }

Teams trigger

triggers:
  - type: teams
    url: "{{ env.TEAMS_WEBHOOK_URL }}"               # required
    title_template: "Custom title {{ notification.event_type }}"  # optional
    retries: 2                                        # optional, default 0
    required: true                                    # optional, default true
    timeout: 30s                                      # optional, default 30s
    fail_fast: true                                   # optional, default true

https://prod-XX.YYY.logic.azure.com:443/workflows/.../triggers/manual/paths/invoke?api-version=1&sp=...&sv=1.0&sig=...

aviso mars #42

Event:    mars
Sequence: 42
class:    od
date:     20260601
domain:   g
...

Payload
seed:  x
count: 5

# Default
title_template: "aviso {{ notification.event_type }} #{{ notification.sequence }}"

# Custom with identifier fields
title_template: "ECMWF {{ notification.event_type }} step={{ notification.identifier.step }}"

# With env-var prefix for environment tagging
title_template: "[{{ env.DEPLOYMENT_TIER }}] aviso {{ notification.event_type }}"

triggers:
  - type: teams
    url: "{{ env.TEAMS_WEBHOOK_URL }}"

export TEAMS_WEBHOOK_URL='https://prod-XX.../workflow'
aviso listen my-listeners.yaml

Post trigger

triggers:
  - type: post
    url: "https://receiver.example/aviso"            # required
    headers:                                          # optional
      Authorization: "Bearer {{ env.RECEIVER_TOKEN }}"
      X-Source: "aviso-listener"
    retries: 2                                        # optional, default 0
    required: true                                    # optional, default true
    timeout: 30s                                      # optional, default 30s
    fail_fast: true                                   # optional, default true

{
  "specversion": "1.0",
  "type": "int.ecmwf.aviso.mars",
  "source": "https://aviso.example.org",
  "id": "mars@42",
  "time": "2026-05-23T22:28:52.384985528Z",
  "datacontenttype": "application/json",
  "dataschema": "https://aviso.example.org/schema/mars",
  "data": {
    "identifier": {
      "class": "od",
      "date": "20260601",
      ...
    },
    "payload": { ... }
  }
}

triggers:
  - type: post
    url: "https://receiver.example/aviso"
    headers:
      Content-Type: "application/json"        # explicit, overrides the default

triggers:
  - type: post
    url: "https://events.example.com/ingest"
    headers:
      X-Service-Auth: "{{ env.INGEST_SERVICE_TOKEN }}"

triggers:
  - type: post
    url: "http://broker-ingress.knative-eventing.svc.cluster.local/default/aviso"
    # Content-Type defaults to application/cloudevents+json which Knative consumes natively

triggers:
  - type: post
    url: "https://events.example.org/queue/aviso"
    headers:
      Authorization: "Bearer {{ env.QUEUE_TOKEN }}"
      X-Routing-Key: "aviso.{{ notification.event_type }}"   # custom routing on the receiver side
    retries: 5
    timeout: 10s

Template engine

{{ notification.<dotted.path> }}    -- substitutes a notification field
{{ env.<NAME> }}                    -- substitutes a process environment variable

url: "{{ env.WEBHOOK_URL }}"
body_template: '{"token": "{{ env.SECRET }}"}'

"value": "{{ notification.identifier.class }}"
                ↓ renders ↓
"value": "od"                              ← valid JSON; the surrounding quotes ARE the JSON string delimiters

"value": "{{ notification.identifier }}"
                ↓ renders ↓
"value": "{"class":"od","date":"20260601"}"   ← INVALID JSON; inner quotes break the string

"identifier": {{ notification.identifier }}
                ↓ renders ↓
"identifier": {"class":"od","date":"20260601"}   ← valid JSON; object is a JSON value, not a string

body_template: '{"who": "{{ notification.identifier.class }}", "what": "{{ notification.event_type }}"}'

body_template: '{"id": {{ notification.identifier }}, "seq": {{ notification.sequence }}}'

body_template: '{{ notification }}'

url: "{{ env.WEBHOOK_URL }}"

export WEBHOOK_URL='https://hooks.example.com/notify?token=xxx'

title_template: "[{{ env.DEPLOYMENT_TIER }}] aviso {{ notification.event_type }}"

Trigger examples

Sending email

listeners:
  - name: ops-email
    event: mars
    triggers:
      - type: command
        command: >
          printf 'From: %s\nTo: %s\nSubject: aviso %s #%s\n\n%s\n'
          "$MAIL_FROM" "$MAIL_TO" "$AVISO_EVENT_TYPE" "$AVISO_SEQUENCE" "$AVISO_NOTIFICATION_JSON"
          | msmtp --from="$MAIL_FROM" "$MAIL_TO"
        env:
          MAIL_FROM: aviso@example.com
          MAIL_TO: ops@example.com
        required: false        # email is non-idempotent; do not force redelivery
        timeout: 30s
        retries: 2             # transient SMTP failures are retried

triggers:
  - type: webhook
    url: "https://mail-gateway.example.org/send"
    headers:
      Authorization: "Bearer {{ env.MAIL_TOKEN }}"
      Content-Type: "application/json"
    body_template: >
      {"to": "ops@example.com",
       "subject": "aviso {{ notification.event_type }} #{{ notification.sequence }}",
       "text": "aviso {{ notification.event_type }} #{{ notification.sequence }} fired"}
    required: false

Notifications

{
  "data": {
    "identifier": {
      "class": "od",
      "step": "12"
    },
    "payload": {
      "location": "file:///data/forecast.grib"
    }
  },
  "datacontenttype": "application/json",
  "dataschema": "https://aviso.example/schema/mars",
  "id": "mars@1",
  "source": "https://aviso.example",
  "specversion": "1.0",
  "time": "2026-09-15T15:15:15.799578652Z",
  "type": "int.ecmwf.aviso.mars"
}

aviso schema get mars

aviso listen --event mars --identifiers '{"class":"od","step":12}'

triggers:
  - type: webhook
    url: "https://hooks.example/notify"
    body_template: '{"event": "{{ notification.event_type }}", "payload": {{ notification.payload }}}'

Filters

listeners:
  - name: mars-od
    event: mars
    identifiers:
      class: od
      step: 12
    triggers:
      - type: echo

aviso listen --event mars --identifiers '{"class":"od","step":12}'

aviso schema get mars

{
  "date": "20260913",
  "severity": {"gte": 5},
  "anomaly": {"between": [40, 50]},
  "region": {"in": ["north", "south"]}
}

aviso listen --event mars --identifiers '{}'

identifiers:
  polygon:
    - [46, 8]
    - [46, 9]
    - [47, 9]
    - [47, 8]
    - [46, 8]

aviso listen --event test_polygon \
  --identifiers '{"polygon":[[46,8],[46,9],[47,9],[47,8],[46,8]]}'

{"point_cloud":[[46,8],[47,9],[46.5,8.5]]}

Streams and reconnects

Resume and state

~/.config/aviso/state.json
~/.config/aviso/state.json.lock

# ~/.config/aviso/config.yaml
state_file: "/var/lib/aviso/state.json"

aviso listen --no-state-store --event mars --identifiers '{"class":"od"}'

{
  "version": 1,
  "key_format_version": 1,
  "checkpoints": {
    "46fe3e30...": {
      "last_committed_sequence": 72,
      "last_event_id": "mars@72"
    }
  }
}

Authentication providers

bearer:
  token: "opaque-or-jwt-token"

basic:
  username: "alice"
  password: "wonderland"

Glossary

CLI flags reference

Every flag for every subcommand. This is the long-form reference; for narrative usage, start at CLI overview. Refresh this page whenever the Clap command surface changes.

To see the same information from the binary itself:

aviso --help
aviso <SUBCOMMAND> --help

Global flags

Available on every subcommand.

aviso notify <PARAMETERS>

Publish one notification to /api/v1/notification.

See repeated identifiers for scripts for shell quoting, key trimming, and typed values.

Returns exit code 0 on success, 1 on a server error or network failure, 2 on missing parameters.

aviso listen [LISTENER_FILES]...

Run one or more listeners against /api/v1/watch.

Returns 0 on a clean Ctrl+C, 1 if any listener task errored, 2 on no listeners resolved.

aviso replay --from <VALUE> [--until <VALUE>] [LISTENER_FILES]...

Replay historical notifications from a cursor.

Replay never touches the state file. Returns 0 on completion, 1 on error.

aviso schema list

List event types the server knows about.

No subcommand-specific flags. On a TTY the output is a header line and a bullet list of event types; piped or with --json, the output is NDJSON (one JSON object per line).

aviso schema get <EVENT_TYPE>

Fetch one schema as pretty JSON.

aviso admin wipe-stream <EVENT_TYPE> --yes

Delete every notification of one event type.

aviso admin wipe-all --yes

Delete every notification across every stream.

aviso admin delete <NOTIFICATION_ID> --yes

Delete one notification.

aviso config dump

Print the resolved configuration to stdout.

aviso completions <SHELL>

Print a shell completion script to stdout.

Environment variables

Exit codes

Signal handling

The first Ctrl+C triggers a graceful drain: aviso closes the watch connection, flushes in-flight commits, then exits 0 (or 1 if a listener errored earlier). A second Ctrl+C within five seconds calls the OS exit directly with code 130, bypassing the drain.

Listener YAML reference

The file format aviso listen (and aviso replay with positional files) reads.

A listener file has one top-level key, listeners:, with a list of listener definitions. The same shape is accepted inside the main config file (~/.config/aviso/config.yaml).

Minimal example

listeners:
  - name: mars-od
    event: mars
    identifiers:
      class: od
    triggers:
      - type: echo

All fields

Identifier values may have any JSON-compatible YAML shape. Spatial values use latitude first. This listener filters point-cloud notifications with a polygon:

listeners:
  - name: alpine-observations
    event: observations
    identifiers:
      date: "20260601"
      polygon:
        - [46, 8]
        - [46, 9]
        - [47, 9]
        - [47, 8]
        - [46, 8]
    triggers:
      - type: echo

A point is [latitude, longitude]. Polygons need at least four pairs, with the first pair repeated last. Providers send point_cloud; subscribers send polygon. This uses the observations schema from Publish and listen.

Constraint mappings

Use YAML mappings for constraints, not strings containing JSON. With the schema and seed records from the weather tutorial, put this in weather-listeners.yaml:

listeners:
  - name: selected-weather
    event: weather
    identifiers:
      date: "20260913"
      severity:
        gte: 5
      anomaly:
        between: [40, 50]
      region:
        in: [north, south]
    triggers:
      - type: echo

Quote the date so it stays a string. Leave numeric operands unquoted. This selects B and C; the central operator reference explains the allowed mappings.

Run the file directly, replaying the retained seeds before listening live:

aviso listen weather-listeners.yaml --from 0 --no-state-store
aviso replay weather-listeners.yaml --from 0

The listen command runs until Ctrl+C; run replay separately. Alternatively, place the same listeners: block in your client config, weather-config.yaml, alongside your connection settings. Select its listener by name for replay:

aviso --config weather-config.yaml listen --from 0 --no-state-store
aviso --config weather-config.yaml replay --listener selected-weather --from 0

Both config commands use the same mapping; they do not read the positional listener file. AVISO_BASE_URL can supply the test server address for either form.

Trigger fields

Every trigger entry has a type: field plus per-kind fields. Shared options:

echo

- type: echo

No required fields. Writes the notification to stdout (pretty JSON on a TTY, NDJSON otherwise).

log

- type: log
  path: /var/log/aviso/mars.log

Appends one line of compact JSON per notification.

command

- type: command
  command: "./on-event.sh {{ notification.event_type }} {{ notification.sequence }}"
  env:
    DATA_DIR: /var/lib/aviso/data
  working_dir: /var/lib/aviso
  timeout: 30s

Unix only.

webhook

- type: webhook
  url: "https://hooks.example/notify"
  method: POST
  headers:
    Authorization: "Bearer {{ env.WEBHOOK_TOKEN }}"
  body_template: '{"event": "{{ notification.event_type }}", "seq": {{ notification.sequence }}}'

teams

- type: teams
  url: "{{ env.TEAMS_WEBHOOK_URL }}"
  title_template: "Custom {{ notification.event_type }}"

Builds the Adaptive Card body automatically from the notification.

post

- type: post
  url: "https://receiver.example/aviso"
  headers:
    Authorization: "Bearer {{ env.RECEIVER_TOKEN }}"

Body is always the server’s original CloudEvent envelope. No body_template, no method (always POST).

Templates

The template engine for trigger fields is documented at Triggers: template engine. Two namespaces inside {{ ... }}:

• {{ notification.<dotted.path> }}: a field of the notification.
• {{ env.<NAME> }}: a process environment variable.

Resolution and precedence

When you run aviso listen:

1. Positional YAML files replace the global config’s listeners: for this invocation. They do not merge with it.
2. With multiple positional files, the listener lists are concatenated in argv order.
3. With no positional files, the global config’s listeners: block is used.
4. With no listeners anywhere, aviso listen exits with code 2.

--event with either --identifiers or repeated --identifier (inline mode) takes precedence over positional YAML files when both are present.

What next

• Trigger overview: pick the right trigger.
• CLI publish and listen: running listeners.

State file reference

The on-disk record of where each listener left off. By default at ~/.config/aviso/state.json. A sibling lockfile lives next to it at ~/.config/aviso/state.json.lock.

If you have never run aviso listen, neither file exists yet. Both are created lazily on the first successful checkpoint commit. aviso replay does not touch either file.

For the conceptual model, read Resume and state first.

A worked example

After listening for mars events with class=od and processing one notification, the file looks like:

{
  "version": 1,
  "key_format_version": 1,
  "checkpoints": {
    "46fe3e30937478ae30527c74cb2f03a5e5419228a11051cdaccefe7d044b21c3": {
      "last_committed_sequence": 72,
      "last_event_id": "mars@72"
    }
  }
}

The next time aviso runs against the same server, event type, and filter, it reads this checkpoint and asks the server for sequence 73 onwards.

What each field is for

version

The format version of the JSON document itself (which top-level fields exist, what types they hold).

The check is exact match. A file with version: 2 is rejected by a client that knows only version: 1. If you upgrade aviso and the version bumps, the old file becomes unreadable until you either install a matching aviso, or delete the file and accept that the next run starts from “now”.

key_format_version

The version of the recipe used to derive the hex keys in checkpoints. Also exact match. A mismatch means the keys on disk were hashed differently and cannot be matched to anything the live client computes.

checkpoints

A map keyed by 64-character hex resume keys. Each value is one checkpoint object.

What “committed” actually means

last_committed_sequence advances only after every required trigger for the notification succeeded and aviso wrote the new value to disk. If anything in that chain fails, the cursor does not advance, and the notification will be redelivered on the next run.

So when you see last_committed_sequence: 72, that means mars@72 was fully processed end-to-end. The cursor is a high-water mark of completed work, not a “received” counter.

Can I edit or delete this file?

Delete the whole file: safe, with consequences

rm ~/.config/aviso/state.json ~/.config/aviso/state.json.lock

Do this only when no aviso listen is running. The next run starts with no cursor:

• If your YAML or command-line sets --from, the run resumes from there.
• Otherwise the run starts from “now” (the server’s current tip).

You will miss the notifications between the deleted cursor and “now” unless you explicitly replay them.

Delete just the lockfile: unsafe while a client is running

rm ~/.config/aviso/state.json.lock

The cross-process lock is attached to the lockfile’s inode. Deleting the lockfile while a client holds the lock lets a sibling process acquire “the” lock on a fresh inode, which breaks mutual exclusion. Only delete it when no aviso process is using the file.

Hand-edit the file: mostly read-only by design

The store guards last_committed_sequence against going backwards. Two consequences:

• Lowering a sequence is silently ignored. If you edit 72 down to 42 and start aviso, the next checkpoint write compares the on-disk value against the in-memory candidate and keeps the higher. Your edit is overwritten on the next commit.
• Raising a sequence skips notifications. If you edit 72 up to 100, the next reconnect asks the server for sequence 101 onwards, and notifications 73 through 100 are never delivered to this listener. aviso has no way to tell whether that was intentional, so it trusts you.

To genuinely reset a cursor, delete the file (with aviso stopped) and start with --from:

rm ~/.config/aviso/state.json
aviso listen my-listeners.yaml --from 2026-05-23T00:00:00Z

cat while aviso is running: safe

Reading the file from outside aviso is harmless. The atomic-write protocol guarantees you see either the previous complete file or the new complete file, never a half-written tear.

How --from interacts with the state file

When you pass --from <VALUE> and a cursor already exists in the file: