This guide provides a terminal-focused reference for the maintenance and diagnostic utilities available in the scripts/ directory.

File: update.ts (shim: update.js) Purpose: Perform a safe, production-ready update.

# Pull latest code, install deps, and restart PM2
dexbot update

Note: Protects your profiles/ directory during the update process.

All clear/reset scripts resolve their directories via scripts/lib/dexbot-paths.sh, which mirrors modules/paths.ts. Defaults depend on the install type:

Env overrides: DEXBOT_PROFILE_ROOT, DEXBOT_MARKET_ADAPTER_DATA_DIR, DEXBOT_MARKET_ADAPTER_STATE_DIR, DEXBOT_CLAW_DATA_DIR. When run through the dexbot CLI, the resolved runtime dirs are passed automatically, so the CLI always clears the same dirs the runtime uses.

File: clear-logs.sh Purpose: Delete all bot .log and .jsonl files, including profiles/logs/market_adapter.log.

# IRREVERSIBLE: Deletes all files in profiles/logs/*.log and *.jsonl, including market_adapter.log
# Prompts for confirmation before deleting.
bash scripts/clear-logs.sh

File: clear-orders.sh Purpose: Delete all persistent order state files.

# IRREVERSIBLE: Deletes all files in profiles/orders/*
# Prompts for confirmation before deleting.
bash scripts/clear-orders.sh

File: clear-market-adapter.sh Purpose: Delete all market adapter candle data, state files, and runtime logs.

# IRREVERSIBLE: Removes market_adapter/{data,state}/ and profiles/logs/{market_adapter,dexbot-adapter,dexbot-adapter-error}.log
# (paths relocate under the profiles dir for global npm installs)
# Prompts for confirmation before deleting.
bash scripts/clear-market-adapter.sh

File: clear-all.sh Purpose: Delete order state files, log files, market adapter data/state, and claw data in one confirmed operation.

# IRREVERSIBLE: Deletes profiles/orders/*, profiles/logs/*.{log,jsonl},
# market_adapter/{data,state}/*, and claw data (positions.json, watcher-health.json, memu/) under
# <profiles>/claw/data (or <repo>/claw/data for source checkouts).
# Prompts for confirmation before deleting.
bash scripts/clear-all.sh

File: reset-settings.sh Purpose: Delete the three settings files and restore built-in defaults on next run.

# IRREVERSIBLE: Deletes profiles/general.settings.json, profiles/market_profiles.json,
# and profiles/market_adapter_settings.json
# Prompts for confirmation before deleting.
bash scripts/reset-settings.sh

File: validate_bots.ts Purpose: Check bots.json for schema errors or missing required fields.

# Validate the live bot configuration
node dist/scripts/validate_bots.js

File: generate_market_adapter_whitelist.ts Purpose: Generate profiles/market_adapter_whitelist.json from bots whose gridPrice uses AMA mode.

# Add missing AMA bots from profiles/bots.json to profiles/market_adapter_whitelist.json.
# Existing entries are preserved; new entries enable AMA/range scaling and leave dynamicWeight disabled.
dexbot white

# Add missing AMA bots with dynamicWeight enabled for newly generated entries
dexbot white --dynamic-weight

# Add missing AMA bots with asymmetricBounds disabled for newly generated entries
dexbot white --no-asymmetric-bounds

# Remove whitelist entries for bots no longer in profiles/bots.json
dexbot white --prune

File: divergence-calc.ts Purpose: Measure the "drift" between in-memory grid and disk state using RMS divergence metric.

# Calculates RMS Error (hardcoded threshold: 1 promille ≈ 3.2% avg error)
# RMS quadratically penalizes large errors - see docs/GRID_RECALCULATION.md
node dist/scripts/divergence-calc.js

Reference: RMS threshold interpretation in Grid Recalculation docs

File: analyze-orders.ts Purpose: Analyze grid trading metrics and order distribution patterns.

# Analyzes spread accuracy, geometric consistency, and fund distribution
node dist/scripts/analyze-orders.js

For AMA bots (gridPrice: ama) the analyzer reads <botKey>.dynamicgrid.json and, when fresh (2 × MARKET_ADAPTER.RUNTIME_DEFAULTS.pollSeconds, default 2h), shows live weights with color: higher = red (losing), lower = green (winning), static = grey. Stale snapshot appends a red (adapter offline) alert to the static weights.

File: diagnose-kibana-candles.ts Purpose: Fetch raw Kibana LP candles for a specific pool to verify trading activity.

node dist/scripts/diagnose-kibana-candles.js

File: diagnose-pool-history.ts Purpose: Inspect raw BitShares pool history API responses.

# Inspect pool history (default pool 1.19.133)
node dist/scripts/diagnose-pool-history.js

# Custom pool, limit, and time range
node dist/scripts/diagnose-pool-history.js --pool 1.19.x --limit 100 --hours 48 --maxPages 5

File: print_grid.ts Purpose: Demonstrate the grid structure — shows consecutive price levels with percentage differences between adjacent slots.

node dist/scripts/print_grid.js

File: runner.ts Purpose: Standalone order grid calculation debugger — loads a bot config, initializes the grid, and simulates sync cycles.

# Default (first bot, 3 cycles)
node dist/scripts/runner.js

# Specific bot, 10 cycles with 1s delay
LIVE_BOT_NAME=my-bot CALC_CYCLES=10 CALC_DELAY_MS=1000 node dist/scripts/runner.js

Useful for verifying config produces the expected grid, testing price derivation, and debugging fund allocation. Requires a live BitShares connection (asset metadata lookups and price derivation are on-chain).

File: native_release_gates.ts (+ generate_mainnet_corpus_report.ts) Purpose: Prove the native serialization layer matches the chain byte-for-byte before release.

# Generate the mainnet corpus report (needs a live node + 50+ blocks)
npm run native:corpus

# Run serializer snapshots + ECC invariants and assert the corpus report
npm run native:release-gates

The corpus report lands in <profiles>/native_validation/mainnet_corpus_report.json. The gates fail unless the report has passed=true and transactionCount>=50.

File: git-viewer.sh Purpose: Interactive monitor for uncommitted, committed, and pushed changes.

# Launch interactive git changes viewer with fzf search
bash scripts/git-viewer.sh

Features:

• View uncommitted (working tree) changes
• View committed (staged) changes
• View pushed vs. remote-tracking changes
• Smart auto-refresh (1s for local, 15s for remote)
• Fuzzy search with fzf for finding files
• Toggle between full file view and diff-only view

Usage:

# Press '1' to view all changes
# Press '2' to search uncommitted files (with fzf)
# Press '3' to search unpushed commits (with fzf)
# Press '4' to search pushed commits (with fzf)
# Press 'q' to quit

Inside file viewer: f full file, d diff view, q back to search, b main menu.

Tests use native Node assert — no test framework needed. Sources compile to dist/tests/ via npm run build:tests, and npm test runs them sequentially through dist/scripts/run-tests.js (with a per-test watchdog and diagnostics summary). See tests/README.md for details.

File: analyze-git.ts Purpose: Analyze git history and generate a chart of lines added vs deleted by file.

node dist/scripts/analyze-git.js

File: test-credit-renewal.ts Purpose: Test credit offer renewal for a specific bot against the live chain.

npm run test:credit-renewal

File: verify-browser-bundle.ts Purpose: Verify that the browser-safe surface actually bundles for the web (source-level and dist-level checks).

npm run verify:browser-bundle

File: create-bot-symlinks.sh Purpose: Create profiles/<bot-name>.config.cjs symlinks pointing to profiles/ecosystem.config.cjs so you can run pm2 start <bot-name> directly.

bash scripts/create-bot-symlinks.sh

File: sync-version.ts Purpose: Keep DEXBot2-owned package and plugin manifests aligned to the root package.json version.

# Check that package-lock.json and Claw manifests match root package.json
npm run version:check

# Rewrite aligned manifests from root package.json
npm run version:sync

Git-only: These scripts require a .git directory and will not work with global npm package installs (npm install -g dexbot). They are intended for source checkout workflows only.

File: pmain.sh (also: npm run pmain) Purpose: Sync local test branch through dev to main remote.

# Push test → dev → main
bash scripts/pmain.sh
# OR
npm run pmain

File: pdev.sh (also: npm run pdev) Purpose: Sync local test branch to dev remote.

# Push test → dev
bash scripts/pdev.sh
# OR
npm run pdev

File: ptest.sh (also: npm run ptest) Purpose: Push local test branch to remote.

# Push test to origin/test
bash scripts/ptest.sh
# OR
npm run ptest

The following scripts allow you to call dexbot commands directly from the scripts/ directory:

File: generate_lp_chart.ts Purpose: Generate the standard uPlot LP chart output.

# Generate the default LP chart flow
npm run lp:chart -- --data <lp-export.json>
# --file is an alias for --data

File: analysis/ama_fitting/generate_unified_comparison_chart.ts Purpose: Generate the local LP comparison chart from an LP candle export. Output: analysis/charts/lp_chart_<interval>_UNIFIED_COMPARISON.html

# Generate the local LP comparison chart
npm run ama:chart:lp-local -- --data <lp-export.json>

File: analysis/analyze_derivatives.ts Purpose: Generate the derivative analysis report.

# Generate the derivative analysis report
npm run analysis:derivatives -- --source json --file <file.json>

For understanding the systems these scripts interact with:

• Module Architecture: See modules/README.md
• Copy-on-Write Pattern: See docs/COPY_ON_WRITE_MASTER_PLAN.md for rebalancing architecture
• Fund Accounting: See docs/FUND_MOVEMENT_AND_ACCOUNTING.md
• Grid Divergence: See docs for RMS threshold explanations
• Logging System: See docs/LOGGING.md for log configuration and levels

Boost your workflow by adding these aliases to your ~/.bashrc or ~/.zshrc:

# DEXBot2 Shortcuts
alias dbu='dexbot update'
alias dbc='bash scripts/clear-logs.sh'
alias dbr='bash scripts/clear-orders.sh'
alias dba='bash scripts/clear-all.sh'
alias dbv='node dist/scripts/validate_bots.js'
alias dbd='node dist/scripts/divergence-calc.js'

Monitor live updates while running a script:

# Tail the update log in a separate pane
tail -f <profiles>/logs/dexbot-update.log

Run a specific bot dry-run from the CLI:

# Force a clean start for 'my-bot'
bash scripts/clear-orders.sh && BOT_NAME=my-bot dexbot test