Monitoring CLI

dedaub-monitoring is a command-line interface for the Dedaub monitoring platform — a terminal-driven alternative to the web app. Use it to author and manage on-chain alert queries from your editor, your shell, or any CI pipeline that needs to keep monitoring queries in version control.

The CLI lives in its own repository: github.com/Dedaub/monitoring-cli. This page covers the essentials; the repo's README and dedaub-monitoring --help are the canonical reference for individual command flags.

Installation

Requires Python 3.13. Install from source — uv is recommended:

git clone https://github.com/Dedaub/monitoring-cli.git
cd monitoring-cli
uv tool install . # or: pipx install .

After install, dedaub-monitoring is on your PATH.

Authentication

dedaub-monitoring login

This opens a browser-based OAuth2 device flow. Credentials are stored locally (with chmod 600) and reused across sessions, so you log in once per machine.

Claude Code skill

The CLI ships with a Claude Code skill that turns alert creation into an AI-guided conversation. Instead of writing DedaubQL by hand, you describe the alert you want and the skill takes you through researching the protocol, drafting the query, reviewing it, and deploying it — all from the same Claude Code session.

Install the skill:

dedaub-monitoring install-skill

This writes the skill into your Claude Code configuration. From any Claude Code session you can then run:

/dedaub-monitoring

and describe what you want to monitor in natural language — e.g. "alert me whenever someone borrows more than 1M USDC from Aave on Ethereum." The skill walks the model through:

1. Research — locate the relevant contracts, events, and tables.
2. Write — generate a DedaubQL query using the appropriate macros.
3. Review — show the query, explain it, run it against recent data.
4. Deploy — create the query, enable alerts, set up notifications.

If you're using Claude Code, this is by far the fastest path. The rest of this page documents the underlying CLI commands the skill drives, which are also useful on their own.

Core workflow

The full lifecycle of an alert in five commands.

Browse what you have

dedaub-monitoring tree

Shows your folder tree and existing queries, so you can see where to put a new alert.

Create a folder and a query

dedaub-monitoring create-folder "/My Alerts"
dedaub-monitoring create-query "/My Alerts/large-eth-transfer"

create-query prints the query's numeric id, which you'll use in subsequent commands.

Write the SQL

dedaub-monitoring write-query --id 1234 <<'SQL'
SELECT
    encode(t.tx_hash, 'hex') AS tx_hash,
    encode(t.from_a, 'hex')  AS sender,
    t.callvalue / 1e18       AS eth_amount,
    t.block_number
FROM {{outer_transaction(network='ethereum')}} t
WHERE t.callvalue > 100 * 1e18
  AND t.status = true
SQL

You can test the query at any point with run-query --id 1234 --duration 1h --limit 20 before turning it into a deployed alert.

Enable alerts

dedaub-monitoring enable-alerts \
  --id 1234 \
  --frequency 300 \
  --alert-template "{{sender}} sent {{eth_amount}} ETH (tx: {{tx_hash}})" \
  --unique-key "tx_hash" \
  --email

The query now runs on the chosen frequency, with each new row producing one alert via the chosen notification channels.

Inspect what's happening

dedaub-monitoring get-logs   --id 1234   # execution history
dedaub-monitoring get-alerts --id 1234   # fired alerts

DedaubQL essentials

Queries use DedaubQL — a SQL dialect with macros that handle time-bounded incremental execution. Two rules cover most of what you need to know to be productive from the CLI:

• Use macros instead of raw table names. FROM {{outer_transaction(network='ethereum')}} is incremental and bounded; FROM ethereum.outer_transaction causes full-table scans and times out.

• Address and hash columns are bytea. Use \x-prefixed literals in WHERE clauses and encode(col, 'hex') when projecting them out:

  WHERE t.to_a = '\x7a250d5630b4cf539739df2c5dacb4c659f2488d'

The full macro and column reference lives in the DedaubQL API Reference. The Quickstart walks through writing a non-trivial query end-to-end and is worth reading once even if you're using the CLI.

Command reference

Command	Description
login	Authenticate via browser
entities	List your user and org accounts
tree	Show your query file tree
create-folder	Create a folder
create-query	Create an empty query
write-query	Update a query's SQL
read-query	Print a query's SQL
query-metadata	Print full query metadata as JSON
get-schema	Show available tables and columns
run-query	Execute a query and print results
get-config	Show materialization config
set-config	Set materialization config
enable-alerts	Enable incremental alerts for a query
disable-alerts	Disable alert notifications
list-alerts	List all queries with alerts enabled
get-logs	Show execution logs
get-alerts	Show fired alert events
preprocess-query	Expand DedaubQL macros and print the result
explain-query	Print query dependency analysis
install-skill	Install the Claude Code skill

Run dedaub-monitoring <command> --help for the flags of any individual command.

Learn more

• Repository: github.com/Dedaub/monitoring-cli — source, README, issues.
• DedaubQL Reference: DedaubQL API Reference for the full list of tables, macros, and functions available to queries.
• Tutorial: Quickstart for a worked example of an end-to-end monitoring agent.

The CLI's --help output and the repo README are the source of truth for command flags as they evolve. If something in this page disagrees with the repo, the repo wins.