Skip to content

About

Command-line tool to monitor on-chain activity on Ethereum and EVM chains; Write SQL queries and deploy real-time blockchain alerts with Dedaub.

Topics

Resources

Stars

4 stars

Watchers

1 watching

Forks

Repository files navigation

dedaub-monitoring

Agent skill on skills.sh Claude Code plugin License: MIT

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.

Installation

Pick the path that matches what you already have — all three end with the same installed dedaub-monitoring command.

From scratch — one command (recommended)

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 | sh

Windows (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.

Already have uv — one line

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 login

Contributors — from a clone

If 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 branch

To 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.

Authentication

dedaub-monitoring login    # or: make login

This 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.

Headless (CI, containers, remote agents)

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 file

When 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.

Usage

Browse your queries

dedaub-monitoring tree

Create a query

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

Write 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 {{ethereum.outer_transaction()}} t
WHERE t.callvalue > 100 * 1e18
  AND t.status = true
SQL

Enable alerts

dedaub-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.

Check execution logs

dedaub-monitoring get-logs --id 1234

See fired alerts

dedaub-monitoring get-alerts --id 1234

Test a query

dedaub-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.

Explore the schema

dedaub-monitoring get-schema --network ethereum
dedaub-monitoring get-schema --network ethereum --macros

DedaubQL

Queries 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 t

Key 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

Claude Code skill

If you use Claude Code, install the /dedaub-monitoring skill to get an AI-guided alert builder:

dedaub-monitoring install-skill

The 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, .agents

Install the skill on its own

The 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-cli

As 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.

Commands

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.

Account & session

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

Operations

Folders

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

Queries — create, edit & organize

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)

Queries — inspect & validate (no execution)

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

Running queries

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

Materialization & alerts

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)

Notifications & sharing

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)

Widgets & dashboards

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 78

render-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.

FAQ

What is dedaub-monitoring?

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.

How do I monitor on-chain activity from the command line?

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.

How do I set up real-time alerts for large token or ETH transfers?

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.

Which blockchains and networks are supported?

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()}}).

How do I monitor a smart contract or DeFi protocol for drains, liquidations, or admin actions?

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.

Do I write raw SQL or a special dialect?

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.

Is there an AI-assisted way to build alerts?

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.

License

MIT

About

Command-line tool to monitor on-chain activity on Ethereum and EVM chains; Write SQL queries and deploy real-time blockchain alerts with Dedaub.

Topics

Resources

Stars

4 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages