dedaub-monitoring is a command-line interface (CLI) for the Dedaub monitoring platform. It lets you write SQL queries against on-chain data on Ethereum and EVM-compatible chains, test them, and deploy real-time blockchain alerts — all from your terminal.
Use it to monitor on-chain activity and get notified about large transfers, fund drains, liquidations, oracle price deviations, privileged admin/owner actions, and any other event you can express in SQL. The package name is monitoring-cli and the installed command is dedaub-monitoring.
Use cases: smart-contract monitoring, DeFi protocol monitoring, security monitoring, on-chain alerting, and blockchain data analysis across Ethereum, Arbitrum, Base, and other EVM chains.
Pick the path that matches what you already have — all three end with the same installed dedaub-monitoring command.
The bootstrap installer does the whole setup: it installs uv if it's missing (uv also provides the right Python, so you don't install Python yourself), installs the CLI, installs the agent skill, and starts login. Works on macOS, Linux, and Windows. It assumes git is already present (uv uses it to fetch the package) and will tell you if it isn't; everything else it handles.
macOS / Linux:
curl -LsSf https://raw.githubusercontent.com/Dedaub/monitoring-cli/main/install.sh | shWindows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/Dedaub/monitoring-cli/main/install.ps1 | iex"Re-run any time to upgrade. The only step that isn't automated is the browser login, which prints a URL for you to open.
uv installs the CLI straight from the public repo over HTTPS — no clone, no SSH keys, and uv fetches the pinned Python for you:
uv tool install git+https://github.com/Dedaub/monitoring-cli
dedaub-monitoring install-skill
dedaub-monitoring loginIf you're hacking on the CLI, work from a checkout. From a clone, make setup runs the whole onboarding. It always installs the latest main from GitHub, also when your clone is behind or on another branch:
git clone https://github.com/Dedaub/monitoring-cli.git
cd monitoring-cli
make setup # latest main (uv tool install --force --reinstall git+…) + install-skill + login
make setup-local # the same with your working tree, to test a branchTo update the CLI only, run make install (latest main) or make install-local (your working tree). Both print the installed version.
The skill picker and the login browser flow are interactive, so you stay in control of those two steps. Re-authenticate any time with make login.
dedaub-monitoring login # or: make loginThis opens a browser-based OAuth2 device flow. Your credentials are stored locally and reused across sessions; run logout to clear them. logout also revokes the token on the server, which ends that login for every copy of the token. logout --local removes only the local copy and keeps exported tokens valid. Every command accepts --profile/-p to keep separate credential sets (e.g. work vs personal).
Login asks for an offline token, and every command stores the refreshed token it gets back, so a CLI (or an agent driving it) that runs regularly stays logged in without another browser round-trip. You only log in again after the token sits unused past the server's idle limit, or after logout.
Credentials live in ~/.config/dedaub/monitoring.json (mode 0600); set DEDAUB_CONFIG to use another file. Other Dedaub CLIs read the same file, so one login serves them all; they share the login code through the dedaub-auth package in this repository.
Log in once on a machine with a browser, then hand the token to the headless environment:
dedaub-monitoring token # or: make token — prints the stored refresh token
export DEDAUB_MONITORING_REFRESH_TOKEN="<that token>" # on the headless side
dedaub-monitoring entities # works with no config fileWhen DEDAUB_MONITORING_REFRESH_TOKEN is set it replaces the stored token. Endpoints come from the selected profile if a config file exists, otherwise from the production defaults. Nothing is written to disk in this mode, so the token is not rotated: it expires at its own expiry time and you export a fresh one then. Treat the value like a password. Running logout on the machine that exported the token also stops the exported token, unless you use --local.
dedaub-monitoring treededaub-monitoring create-folder "/My Alerts"
dedaub-monitoring create-query "/My Alerts/large-eth-transfer"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 {{ethereum.outer_transaction()}} t
WHERE t.callvalue > 100 * 1e18
AND t.status = true
SQLdedaub-monitoring enable-alerts \
--id 1234 \
--frequency 300 \
--network ethereum \
--alert-template "{{sender}} sent {{eth_amount}} ETH (tx: {{tx_hash}})" \
--unique-key "tx_hash" \
--email--network (default ethereum) selects the chain the alert's run config and notifications
apply to — set it to match the network used in your query's macros (e.g. arbitrum, base).
The same --network option is available on set-config, get-config, disable-alerts, and
list-alerts.
dedaub-monitoring get-logs --id 1234dedaub-monitoring get-alerts --id 1234dedaub-monitoring run-query --id 1234 --duration 1h --limit 20
dedaub-monitoring run-query --id 1234 --format tsv <<'SQL' # run SQL from stdin without storing it
SELECT selector('transfer(address,uint256)') AS sel -- the CLI replaces the call with the hash
SQL--format tsv (or json, one object per line) prints the rows exact and uncut; the default table is
for a person and cuts cells to the terminal width. Notes and the row count go to stderr.
The account runs 3 queries at a time. run-query waits for a free slot (--wait, default 300 s) and
exits 4 when none frees in time. On an empty result it counts the logs of each logs(...) signature's
topic0 and says whether the indexed flags, the address or the window is the cause.
dedaub-monitoring status checks the login (exit 3 when not logged in) and shows the query slots in use.
dedaub-monitoring get-schema --network ethereum
dedaub-monitoring get-schema --network ethereum --macrosQueries use DedaubQL, a dialect of SQL with macros that handle time-bounded incremental execution. Always use macros instead of raw table names:
-- Use this
FROM {{ethereum.outer_transaction()}} t
-- Not this (causes full table scans and timeouts)
FROM ethereum.outer_transaction tKey macros: {{ethereum.outer_transaction()}}, {{etheruem.logs()}}, {{ethereum.contracts()}}.
All address and hash columns are bytea. Use \x-prefixed literals in WHERE clauses and encode(col, 'hex') in SELECT for readable output:
WHERE t.to_a = '\x7a250d5630b4cf539739df2c5dacb4c659f2488d'Full reference: DedaubQL API Reference
If you use Claude Code, install the /dedaub-monitoring skill to get an AI-guided alert builder:
dedaub-monitoring install-skillThe skill ships in the shared "Agent Skills" format, so it can install to more than just Claude. With no flags, in a terminal you get a checkbox picker; otherwise it installs to Claude plus any other supported agent already present on the machine. Choose targets explicitly with --agent, or install everywhere with --all:
dedaub-monitoring install-skill --agent claude --agent codex # specific agents
dedaub-monitoring install-skill --all # claude, codex, cursor, .agentsThe skill is published straight from this repository, so an agent can pull it without the Python CLI. Both routes below read .claude-plugin/, where marketplace.json and plugin.json point at the packaged skill in packages/dedaub-skills/.
With npx skills, which supports Claude Code, Codex, Cursor, Copilot, and 70+ other agents:
npx skills add Dedaub/monitoring-cliAs a Claude Code plugin, which keeps it current with /plugin marketplace update:
/plugin marketplace add Dedaub/monitoring-cli
/plugin install dedaub-monitoring@dedaub
Installed as a plugin, the skill is namespaced: run /dedaub-monitoring:dedaub-monitoring. The skill drives the dedaub-monitoring command, so keep the CLI on your PATH — see Installation.
Then type /dedaub-monitoring in Claude Code (or your agent) to start a session. The skill guides you through researching a protocol, writing alert queries, reviewing them, and deploying them.
The Usage walkthrough above covers the common path — log in, create a query, write SQL, enable alerts. This is the full reference, grouped by what you're doing: the Account & session commands get you set up, and the Operations sub-sections cover everything you do to existing queries afterwards.
Commands that act on a query or folder take it either by --id <id> or by --path /Folder/Name (add --entity-id to reach another entity's tree), so once you know what you want you can edit it directly without browsing first. Every command also accepts --profile/-p.
| Command | Description |
|---|---|
login |
Authenticate via browser (OAuth2 device flow) |
logout |
Remove stored credentials and revoke them on the server (--local keeps the server session) |
token |
Print the stored refresh token, for DEDAUB_MONITORING_REFRESH_TOKEN in headless setups |
entities |
List entities (your user + orgs) available to you |
entity |
Look up an entity by username |
tree |
Show the query file tree for an entity |
install-skill |
Install the agent skill to one or more agents (--agent, --all) — see above |
| Command | Description |
|---|---|
create-folder |
Create a folder (intermediate folders are created automatically) |
rename-folder |
Rename a folder (--new-path) |
delete-folder |
Delete a folder |
move-folder |
Move a folder under another parent (--to-folder-id) |
subfolders |
List a folder's immediate subfolders |
| Command | Description |
|---|---|
create-query |
Create a new empty query |
write-query |
Update a query's SQL (pass as an argument or pipe via stdin) |
read-query |
Print a query's SQL |
query-metadata |
Print full query metadata as JSON |
move-query |
Move a query to another folder (--to-folder-id) |
star-query / unstar-query |
Star or unstar (favourite) a query |
query-by-key |
Fetch a query's metadata by its share key (--key) |
generate-query |
Generate DedaubQL from natural language via the platform generator (for direct/programmatic use) |
| Command | Description |
|---|---|
get-schema |
Show available tables and columns — or macros with --macros; filter with --network/--table |
preprocess-query |
Render DedaubQL macros and print the resulting SQL |
explain-query |
Print the query's PostgreSQL EXPLAIN plan (it plans but does not execute, so it's free) |
validate-query |
Fast compile check — exits 0 if the SQL is valid, else prints the PG error and exits 1 |
query-columns |
Print the output columns (name + type) without running the query |
format-query |
Pretty-print SQL (argument or stdin) |
query-status |
Show materialization/backfill status as JSON |
query-history |
List a query's saved version history |
| Command | Description |
|---|---|
run-query |
Execute a query and print results (async; Ctrl-C or --timeout revokes the server-side task; --format table|tsv|json; waits up to --wait for a query slot, exit 4 after) |
status |
Check the login (exit 3 when not logged in) and show the query slots in use |
cancel-query |
Revoke a running async query task by id (--task-id; idempotent) |
active-queries |
List the task ids of currently-running async queries |
download-results |
Download a completed async query's results as CSV (--task-id) |
materialize |
Trigger a materialization run for a query |
reset-materialization |
Reset the materialized table, forcing a full recompute on the next run |
| Command | Description |
|---|---|
get-config |
Show a query's materialization/scheduling config |
set-config |
Set materialization/scheduling (--materialize TABLE/VIEW/INCREMENTAL, --frequency, --incrementalization, --backfill, --immediate) |
enable-alerts |
Enable incremental alerts and notifications (--email and/or --webhook-id, --alert-template, --unique-key, --frequency) |
disable-alerts |
Disable notifications (materialization is left unchanged) |
list-alerts |
List all queries with alerts enabled |
get-logs |
List execution logs (filter --status/--since, paginate with --before) |
get-alerts |
List fired alert events (filter --since/--before, paginate with --after-id) |
| Command | Description |
|---|---|
webhook |
Manage notification webhooks: create, test, list, get, update, delete (--secret for signing) |
alert-filter |
Manage saved alert filters: create, list, get, update, delete (group queries/chains, --colour) |
telegram-code |
Get the Telegram bot linking code for a query's notifications |
share-query / unshare-query |
Share or unshare a query with a team (--team-id, --perm READ/WRITE) |
A widget is a saved chart, table or single value of one query; a dashboard is a grid of widgets. A widget can be on no dashboard or on many. The checks and the SQL are the same as in the web app's Visualize tab. Each write prints the https://app.dedaub.com/widget/<id> or /dashboard/<id> link (the host follows your profile's API URL).
| Command | Description |
|---|---|
check-widget |
Check a widget like the Visualize tab: config keys and values, the options of the type, the axes the type needs, the query's columns and their types. Exits 1 with one line per problem |
preview-widget |
Read the rows the dashboard reads for the widget, print sample rows and a summary of what the chart draws, with the web chart's notes (--sql prints the SQL only) |
render-widget |
Draw the widget with the web app's own chart code in a headless browser and save a PNG (needs the render extra: Playwright). --upload stores the card picture of a saved widget |
create-widget |
Save a widget of a query (--query-id, --type, --x/--y/--y1, --series-by, --x-label/--y-label, --timeframe, --percent, --horizontal, --prefix/--suffix, --line-style (also stacked), --config FILE|-, --dashboard-id); runs the checks first |
update-widget |
Change a widget on every dashboard that has it; the flags merge into the saved config, --clear KEY removes a key |
get-widget / list-widgets |
Show a widget (JSON), or list your widgets (--query-id, --dashboard-id) |
delete-widget |
Delete a widget (it leaves every dashboard) |
add-widget / remove-widget |
Put a widget on dashboards (--dashboard-id, repeatable), or take it off one |
list-dashboards / get-dashboard |
List your dashboards (the default is marked), or show one with its widgets (JSON) |
create-dashboard / update-dashboard |
Create a dashboard (--public, --unlisted, --description), or change its name, description or visibility |
delete-dashboard |
Delete a dashboard; its widgets stay saved unless --delete-widgets |
set-layout |
Set the place and size of widgets on the 12-column grid (--layout FILE|-, a JSON list of {widget_id, x, y, width, height}) |
set-default-dashboard |
Set the dashboard that /dashboard opens (--id), or --clear it |
share-widget / widget-private-queries |
Share a widget with everyone (--public, it makes its private queries public too) or --private; list those queries first (--dry-run lists them and changes nothing) |
publish-dashboard |
Make a dashboard and its private queries public in one step (--dry-run lists them) |
widget-picture / dashboard-picture |
Download the stored picture (--theme dark|light) and say whether it is stale |
dedaub-monitoring check-widget --query-id 123 --type line --x day --y volume_usd --y-label 'Volume (\$)'
dedaub-monitoring preview-widget --query-id 123 --type line --x day --y volume_usd --timeframe 7d
dedaub-monitoring render-widget --query-id 123 --type line --x day --y volume_usd # widget-draft-dark.png
dedaub-monitoring create-widget --query-id 123 --type line --x day --y volume_usd --label '**Daily volume**'
dedaub-monitoring add-widget --id 456 --dashboard-id 78render-widget needs Playwright and a browser:
uv tool install --force --with-executables-from playwright 'monitoring-cli[render] @ git+https://github.com/Dedaub/monitoring-cli'
playwright install chromium # or use an installed Chrome: --browser-channel chrome--with-executables-from playwright puts the playwright command on your PATH: uv tool install links only the executables of the main package. make install and make setup install without the render extra: use the line above, or make install-render, when you need render-widget.
The widget types and every config key are in the skill's references/widgets.md.
dedaub-monitoring is a command-line tool for the Dedaub monitoring platform. You write SQL (DedaubQL) queries against on-chain Ethereum and EVM data, test them, and deploy real-time alerts that notify you by email when matching activity occurs.
Install the CLI (uv tool install .), authenticate with dedaub-monitoring login, create a query with create-query, write your SQL with write-query, and enable notifications with enable-alerts. The query runs incrementally on a schedule and fires alerts when rows match.
Write a query that selects transfers above a threshold (see the large ETH transfer example above), then run enable-alerts with an --alert-template and --unique-key so each transfer is reported once. Set --frequency to control how often the query runs.
Any chain supported by the Dedaub monitoring platform, including Ethereum, Arbitrum, and Base. Select the chain with the --network option (default ethereum) and the matching network argument inside your DedaubQL macros (e.g. {{ethereum.outer_transaction()}}).
Query the protocol's logs and calls with the {{<c>.logs(...)}} and {{<c>.outer_transaction(...)}} macros (<c> is the chain slug), filter for the events you care about (large withdrawals, liquidation calls, owner/admin function selectors, oracle updates), and enable alerts on the query. The Claude Code skill (dedaub-monitoring install-skill) can build these queries for you from a plain-language description.
You write DedaubQL, a dialect of SQL with macros for time-bounded incremental execution. Always use macros (e.g. {{ethereum.outer_transaction()}}) instead of raw table names to avoid full table scans. See DedaubQL above.
Yes. If you use Claude Code, run dedaub-monitoring install-skill and type /dedaub-monitoring to get an AI-guided alert builder that researches a protocol, writes the query, and deploys the alert.
MIT