Commands

Blnk Watch exposes a small set of CLI commands for running the service and syncing transactions from Blnk Core.

The make targets run the default command shape only.If you need to change flags such as -port, -sync-interval, or -batch-size, use the blnk-watch binary directly.

start

Use start to run Watch in continuous mode. It starts the Watch HTTP service and, when DB_URL is set, starts the watermark syncer in the same process. This is the simplest way to run Watch against Blnk Core in one process. New transactions are continuously pulled from Blnk Core on a schedule, written into Watch, and evaluated against your active rules as they flow in. Use start when you want the API and automatic Core ingestion together. If you only need the API (e.g. you send transactions via the inject API), use watch. If you only need to sync from Core without the API, use sync or sync-once.

Direct download
Using make
Using Go binary

When blnk-watch is on your PATH (for example after direct download or make install):

# Default: API on 8081, sync every 10s, batch size 1000
blnk-watch start

Flag	Description	Default
`-port`	Port used by the Watch HTTP service	`8081`
`-sync-interval`	How often Watch pulls new transactions from Core	`10s`
`-batch-size`	Number of transactions to process per sync batch	`1000`

Runs the default command only.

make start

Use the binary from the project directory with custom flags (port, sync interval, batch size).

# Default: API on 8081, sync every 10s, batch size 1000
./blnk-watch start

# Custom port, sync interval, and batch size
./blnk-watch -command=start -port=9090 -sync-interval=5s -batch-size=500

Flag	Description	Default
`-port`	Port used by the Watch HTTP service	`8081`
`-sync-interval`	How often Watch pulls new transactions from Core	`10s`
`-batch-size`	Number of transactions to process per sync batch	`1000`

install

Use install to build and install the blnk-watch binary in your system. This is useful when you want to run blnk-watch directly from your shell instead of invoking it from the project directory.

Using make
Using Go binary

Builds the binary and installs it into $(go env GOPATH)/bin.

make install

From the blnk-watch project root, build and install the binary into your Go path:

go install ./cmd/blnk-watch

To make sure you can run blnk-watch, add the Go bin directory to your PATH. Follow the steps below for your OS:

Add Go bin to PATH

macOS / Linux
Windows

Add to PATH for the current session:

export PATH="$(go env GOPATH)/bin:$PATH"

# Make it permanent and reload the shell (e.g. `~/.zshrc` or `~/.bashrc`)
source ~/.zshrc

Confirm the binary is available:

blnk-watch -command=start

Add to PATH for the current session (PowerShell):

$env:Path += ";$(go env GOPATH)\bin"

To make it permanent:

Press Win + R, type sysdm.cpl, press Enter to open System Properties.
Open the Advanced tab → Environment Variables.
Under User variables, select Path → Edit.
Click New, then add %USERPROFILE%\go\bin
Click OK on each dialog to save.
Close and reopen your terminal so the updated PATH is loaded.

Confirm the binary is available:

blnk-watch -command=start

watch

Use watch to run only the Watch service. This starts the HTTP API used to inject transactions, retrieve evaluation results, and serve the endpoints used during transaction evaluation. Use watch when you only need the HTTP API (e.g. you inject transactions) and do not need to pull from Blnk Core. To run both the API and Core ingestion, use start instead.

Direct download
Using make
Using Go binary

When blnk-watch is on your PATH:

# Default: API on port 8081
blnk-watch -command=watch

# Custom port
blnk-watch -command=watch -port=9090

Flag	Description	Default
`-port`	Port used by the Watch HTTP service	`8081`

Starts the default service command only. Use the binary if you need custom flags.

make watch

Use the binary from the project directory with a custom port or other flags.

# Default: API on port 8081
./blnk-watch -command=watch

# Custom port
./blnk-watch -command=watch -port=9090

Flag	Description	Default
`-port`	Port used by the Watch HTTP service	`8081`

sync

sync requires DB_URL so Watch can connect to the Blnk Core database.

Use sync to run the watermark sync service continuously. This command reads transactions from Blnk Core in batches, stores them in Watch, and keeps moving forward from the current watermark. In practice, sync is useful for backfills, historical evaluation, or when you only need to pull transactions from Core (no HTTP API). On a fresh setup, it can process older transactions from the configured sync start point. After that, it continues syncing new transactions as they appear. sync does not start the Watch HTTP server. To run both the API and sync from Core, use start instead.

Direct download
Using make
Using Go binary

When blnk-watch is on your PATH:

# Default: sync every 10s, batch size 1000
blnk-watch -command=sync

# Custom sync interval and batch size
blnk-watch -command=sync -sync-interval=5s -batch-size=500

Flag	Description	Default
`-sync-interval`	How often Watch runs the next watermark sync cycle	`10s`
`-batch-size`	Number of transactions to process per sync batch	`1000`

Runs the default continuous sync command only. Use the binary to change sync settings.

make sync

Use the binary from the project directory with a custom sync interval or batch size.

# Default: sync every 10s, batch size 1000
./blnk-watch -command=sync

# Custom sync interval and batch size
./blnk-watch -command=sync -sync-interval=5s -batch-size=500

Flag	Description	Default
`-sync-interval`	How often Watch runs the next watermark sync cycle	`10s`
`-batch-size`	Number of transactions to process per sync batch	`1000`

sync-once

sync-once requires DB_URL so Watch can connect to the Blnk Core database.

Use sync-once to run a single watermark synchronization pass and then exit. It processes available historical transactions from Blnk Core up to the current watermark and stops when that run completes. This is useful for backfills, one-off reprocessing, CI or maintenance jobs, and scheduled tasks such as cron jobs where you do not want a long-running process. Unlike sync, this command does not keep polling for new transactions.

Direct download
Using make
Using Go binary

When blnk-watch is on your PATH:

# Default: batch size 1000
blnk-watch -command=sync-once

# Custom batch size
blnk-watch -command=sync-once -batch-size=2000

Flag	Description	Default
`-batch-size`	Number of transactions to process in the one-time sync batch loop	`1000`

Runs the default one-time sync only. Use the binary if you need to change the batch size.

make sync-once

Use the binary from the project directory with a custom batch size.

# Default: batch size 1000
./blnk-watch -command=sync-once

# Custom batch size
./blnk-watch -command=sync-once -batch-size=2000

Flag	Description	Default
`-batch-size`	Number of transactions to process in the one-time sync batch loop	`1000`

Guides

Rules language

Watch API

start

install

watch

sync

sync-once

Guides

Rules language

Watch API

Documentation Index

​start

​install

​watch

​sync

​sync-once

start

install

watch

sync

sync-once