← Home / CLI Reference

CSDS CLI Reference

Terminal-first interface to the Crypto Scam Detection System, built for humans and AI agents.

Get started in seconds

pip install csds-cli

⚠

Beta Release

Core commands (check, batch, tokens, stats, config) are fully implemented. x402 wallet payments and the live dashboard are stubs — see Not Yet Implemented below.

Command Surface

csds check     <address> [options]       # Analyze a single address
csds batch     <file>    [options]       # Analyze addresses from a file
csds tokens              [options]       # Browse the token database
csds stats               [options]       # Platform statistics
csds dashboard                          # ⚠ Not yet implemented
csds auth      setup|status|fund|export # ⚠ Not yet implemented
csds config    set|get                  # Read/write config

Exit Codes

Exit codes let scripts and agents branch on risk level without parsing output.

0

Low/moderate risk — score < 50

1

High risk — score 50–75

2

Critical risk — score > 75

3

Error — network, quota, invalid address

csds check

Analyze a single token or contract address for scam risk.

csds check <address> [--chain] [--full] [--deep] [--format] [--no-color]

Options

Flag	Default	Description
`--chain`	auto-detect	ethereum \| bsc \| solana
`--full`	off	Standard report (deeper analysis)
`--deep`	off	Deep dive with forensic analysis
`--format`	table	table \| json \| csv \| md
`--no-color`	off	Strip ANSI codes (use for piping)

Examples

# Quick check (free tier — 3 lifetime lookups)
csds check 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb --chain ethereum

# JSON output for scripting
csds check 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb --format json --no-color

# Solana token
csds check EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v --chain solana

# CI/CD gate
SCORE=$(csds check $TOKEN --format json --no-color | jq '.risk_score')
[ "$SCORE" -gt 60 ] && { echo "Token failed screening"; exit 1; }

csds batch

Analyze multiple addresses from a file. Results stream as NDJSON by default.

csds batch <file> [--chain] [--format] [--concurrency]

File Format

# One address per line. Chain is optional (auto-detected if omitted).
0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb  ethereum
EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v  solana
0xe9e7CEA3DedcA5984780Bafc599bD69ADd087D56
# blank lines and # comments are skipped

Examples

# Stream NDJSON and filter critical results
csds batch portfolio.txt | jq 'select(.risk_score > 75)'

# Save CSV report
csds batch portfolio.txt --format csv > report.csv

csds tokens

Browse 47,000+ analyzed tokens without making a paid analysis call.

csds tokens [--search] [--chain] [--risk-min] [--risk-max] [--limit] [--format]

# High-risk Ethereum tokens
csds tokens --chain ethereum --risk-min 80 --limit 20

# Search and export CSV
csds tokens --search "pepe" --format csv

csds stats

Show platform-wide statistics.

csds stats
csds stats --format json | jq '.summary.tokens_analyzed'

csds config

Read and write persistent configuration at ~/.config/csds/config.toml.

csds config set <key> <value>
csds config get [key]

Valid Keys

Key	Valid Values	Description
`default-chain`	ethereum, bsc, solana	Default blockchain
`default-format`	table, json, csv, md	Default output format
`api-url`	https:// URL	Override API endpoint
`api-key`	Your API key	Paid tier auth (bypasses quota)
`wallet-key`	Private key	x402 wallet ⚠ not yet implemented

Environment Variables

All config values can be overridden via environment variables. Useful for CI/CD.

Variable	Description
`CSDS_API_URL`	Override API endpoint
`CSDS_API_KEY`	API key auth
`CSDS_WALLET_KEY`	x402 wallet key ⚠ not yet implemented
`CSDS_DEFAULT_CHAIN`	Default blockchain
`CSDS_FORMAT`	Default output format

CSDS_API_KEY=csds_abc123 csds check $TOKEN --format json --no-color

⚠ Not Yet Implemented

Feature	Command	Status
x402 wallet payments	`CSDS_WALLET_KEY`	Stub
Wallet setup	`csds auth setup`	Stub
Wallet balance	`csds auth status`	Stub
Wallet funding QR	`csds auth fund`	Stub
Private key export	`csds auth export`	Stub
Live dashboard TUI	`csds dashboard`	Stub

API key auth and free-tier quota tracking are fully implemented.

Agent Usage

For AI agents and scripts, always use --format json --no-color for machine-readable output.

# Shell script branching on exit code
csds check $TOKEN --format json --no-color
case $? in
  0) echo "Safe to proceed" ;;
  1) echo "High risk — review before trading" ;;
  2) echo "ABORT: critical risk token" && exit 1 ;;
  3) echo "Error — check network or quota" && exit 1 ;;
esac

# Portfolio scan — filter critical tokens
csds batch wallet_tokens.txt --format json \
  | jq '[.[] | select(.risk_score > 50)] | sort_by(.risk_score) | reverse'

Installation Guide API Reference Quick Start