Tacit Lab
a61c329496
- Split 900-line precheck_core.py into 9 focused modules: precheck_constants, time_utils, data_utils, state_manager, market_data, candidate_scoring, snapshot_builder, adaptive_profile, trigger_analyzer - Remove dead auto_trader command and module - Migrate 7 root-level command modules into commands/: check_api, doctor, external_gate, init_user_state, market_probe, paths, rotate_external_gate_log - Keep thin backward-compatible facades in root package - Update cli.py MODULE_MAP to route through commands/ - Verified compileall and smoke tests for all key commands
277 lines
6.9 KiB
Markdown
277 lines
6.9 KiB
Markdown
# coinhunter-cli
|
|
|
|
<p align="center">
|
|
<strong>The executable CLI layer for CoinHunter.</strong><br/>
|
|
Runtime-safe trading operations, precheck orchestration, review tooling, and market probes.
|
|
</p>
|
|
|
|
<p align="center">
|
|
<img alt="Python" src="https://img.shields.io/badge/python-3.10%2B-blue" />
|
|
<img alt="Status" src="https://img.shields.io/badge/status-active%20development-orange" />
|
|
<img alt="Architecture" src="https://img.shields.io/badge/architecture-runtime%20%2B%20commands%20%2B%20services-6f42c1" />
|
|
</p>
|
|
|
|
## Why this repo exists
|
|
|
|
CoinHunter is evolving from a loose bundle of automation scripts into a proper installable command-line tool.
|
|
|
|
This repository is the tooling layer:
|
|
|
|
- Code and executable behavior live here.
|
|
- User runtime state lives in `~/.coinhunter/` by default.
|
|
- Hermes skills can call this CLI instead of embedding large script collections.
|
|
- Runtime paths can be overridden with `COINHUNTER_HOME`, `HERMES_HOME`, `COINHUNTER_ENV_FILE`, and `HERMES_BIN`.
|
|
|
|
In short:
|
|
|
|
- `coinhunter-cli` = tool
|
|
- CoinHunter skill = strategy / workflow / prompting layer
|
|
- `~/.coinhunter` = user data, logs, state, reviews
|
|
|
|
## Current architecture
|
|
|
|
```text
|
|
coinhunter-cli/
|
|
├── src/coinhunter/
|
|
│ ├── cli.py # top-level command router
|
|
│ ├── runtime.py # runtime paths + env loading
|
|
│ ├── doctor.py # diagnostics
|
|
│ ├── paths.py # runtime path inspection
|
|
│ ├── commands/ # thin CLI adapters
|
|
│ ├── services/ # orchestration / application services
|
|
│ └── *.py # compatibility modules + legacy logic under extraction
|
|
└── README.md
|
|
```
|
|
|
|
The repo is actively being refactored toward a cleaner split:
|
|
|
|
- `commands/` → argument / CLI adapters
|
|
- `services/` → orchestration and application workflows
|
|
- `runtime/` → paths, env, files, locks, config
|
|
- future `domain/` → trading and precheck core logic
|
|
|
|
## Implemented command/service splits
|
|
|
|
The first extraction pass is already live:
|
|
|
|
- `smart-executor` → `commands.smart_executor` + `services.smart_executor_service`
|
|
- `precheck` → `commands.precheck` + `services.precheck_service`
|
|
- root modules are compatibility facades only:
|
|
- `src/coinhunter/precheck.py`
|
|
- `src/coinhunter/smart_executor.py`
|
|
- `precheck` internals now live in dedicated service modules:
|
|
- `services.precheck_core`
|
|
- `services.precheck_state`
|
|
- `services.precheck_snapshot`
|
|
- `services.precheck_analysis`
|
|
|
|
This keeps behavior stable while giving the codebase a cleaner landing zone for deeper refactors.
|
|
|
|
## Installation
|
|
|
|
Dedicated user-local install:
|
|
|
|
```bash
|
|
./scripts/install_local.sh
|
|
```
|
|
|
|
This creates:
|
|
|
|
- app environment: `~/.local/share/coinhunter-cli/venv`
|
|
- launcher: `~/.local/bin/coinhunter`
|
|
|
|
The launcher behaves like a normal installed CLI and simply forwards into the dedicated virtualenv.
|
|
|
|
Editable install for development:
|
|
|
|
```bash
|
|
pip install -e .
|
|
```
|
|
|
|
Run directly after install:
|
|
|
|
```bash
|
|
coinhunter --help
|
|
coinhunter --version
|
|
```
|
|
|
|
Short aliases are available for the most common commands. The original long-form command names remain supported for backward compatibility.
|
|
|
|
## Quickstart
|
|
|
|
Initialize user state:
|
|
|
|
```bash
|
|
coinhunter init
|
|
```
|
|
|
|
Inspect runtime wiring:
|
|
|
|
```bash
|
|
coinhunter paths
|
|
coinhunter diag
|
|
```
|
|
|
|
Validate exchange credentials:
|
|
|
|
```bash
|
|
coinhunter api-check
|
|
```
|
|
|
|
Run precheck / gate plumbing:
|
|
|
|
```bash
|
|
coinhunter precheck
|
|
coinhunter precheck --mark-run-requested "external-gate queued cron run"
|
|
coinhunter precheck --ack "analysis finished"
|
|
coinhunter gate
|
|
```
|
|
|
|
Inspect balances or execute trading actions:
|
|
|
|
```bash
|
|
coinhunter exec bal
|
|
coinhunter exec overview
|
|
coinhunter exec hold
|
|
coinhunter exec buy ENJUSDT 50
|
|
coinhunter exec flat ENJUSDT
|
|
coinhunter exec rotate PEPEUSDT ETHUSDT
|
|
```
|
|
|
|
Preferred `exec` verbs are `bal`, `overview`, `hold`, `buy`, `flat`, and `rotate`.
|
|
Legacy forms remain supported for backward compatibility: `balances`, `balance`, `acct`, `status`, `sell-all`, `sell_all`, and `rebalance`.
|
|
|
|
Generate review data:
|
|
|
|
```bash
|
|
coinhunter review 12
|
|
coinhunter recap 12
|
|
```
|
|
|
|
Probe external market data:
|
|
|
|
```bash
|
|
coinhunter probe bybit-ticker BTCUSDT
|
|
coinhunter probe bybit-klines BTCUSDT 60 20
|
|
```
|
|
|
|
Long-form equivalents still work:
|
|
|
|
```bash
|
|
coinhunter doctor
|
|
coinhunter check-api
|
|
coinhunter smart-executor bal
|
|
coinhunter review-context 12
|
|
coinhunter review-engine 12
|
|
coinhunter market-probe bybit-ticker BTCUSDT
|
|
coinhunter external-gate
|
|
coinhunter rotate-external-gate-log
|
|
```
|
|
|
|
Supported top-level commands and aliases remain:
|
|
|
|
- `check-api` / `api-check`
|
|
- `doctor` / `diag`
|
|
- `external-gate` / `gate`
|
|
- `init`
|
|
- `market-probe` / `probe`
|
|
- `paths`
|
|
- `precheck`
|
|
- `review-context` / `review`
|
|
- `review-engine` / `recap`
|
|
- `rotate-external-gate-log` / `rotate-gate-log` / `rotate-log`
|
|
- `smart-executor` / `exec`
|
|
|
|
## Runtime model
|
|
|
|
Default layout:
|
|
|
|
```text
|
|
~/.coinhunter/
|
|
├── accounts.json
|
|
├── config.json
|
|
├── executions.json
|
|
├── notes.json
|
|
├── positions.json
|
|
├── watchlist.json
|
|
├── logs/
|
|
├── reviews/
|
|
└── state/
|
|
```
|
|
|
|
Credential loading:
|
|
|
|
- Binance credentials are read from `~/.hermes/.env` by default.
|
|
- `COINHUNTER_ENV_FILE` can point to a different env file.
|
|
- `hermes` is resolved from `PATH` first, then `~/.local/bin/hermes`, unless `HERMES_BIN` overrides it.
|
|
|
|
## Useful commands
|
|
|
|
### Diagnostics
|
|
|
|
```bash
|
|
coinhunter diag
|
|
coinhunter paths
|
|
coinhunter api-check
|
|
```
|
|
|
|
### Trading and execution
|
|
|
|
```bash
|
|
coinhunter exec bal
|
|
coinhunter exec overview
|
|
coinhunter exec hold
|
|
coinhunter exec buy ENJUSDT 50
|
|
coinhunter exec flat ENJUSDT
|
|
coinhunter exec rotate FROMUSDT TOUSDT
|
|
```
|
|
|
|
### Precheck and orchestration
|
|
|
|
```bash
|
|
coinhunter precheck
|
|
coinhunter gate
|
|
coinhunter rotate-gate-log
|
|
coinhunter rotate-log
|
|
```
|
|
|
|
### Review and market research
|
|
|
|
```bash
|
|
coinhunter review 12
|
|
coinhunter recap 12
|
|
coinhunter probe bybit-ticker BTCUSDT
|
|
```
|
|
|
|
## Development notes
|
|
|
|
This project is intentionally moving in small, safe refactor steps:
|
|
|
|
1. Separate runtime concerns from hardcoded paths.
|
|
2. Move command dispatch into thin adapters.
|
|
3. Introduce orchestration services.
|
|
4. Extract reusable domain logic from large compatibility modules.
|
|
5. Keep cron / Hermes integration stable during migration.
|
|
|
|
That means some compatibility modules still exist, but the direction is deliberate.
|
|
|
|
## Near-term roadmap
|
|
|
|
- Extract more logic from `smart_executor.py` into dedicated execution / portfolio services.
|
|
- Continue shrinking `precheck.py` by moving snapshot and analysis internals into reusable modules.
|
|
- Add `domain/` models for positions, signals, and trigger analysis.
|
|
- Add tests for runtime paths, precheck service behavior, and CLI stability.
|
|
- Evolve toward a more polished installable CLI workflow.
|
|
|
|
## Philosophy
|
|
|
|
CoinHunter should become:
|
|
|
|
- more professional
|
|
- more maintainable
|
|
- safer to operate
|
|
- easier for humans and agents to call
|
|
- less dependent on prompt-only correctness
|
|
|
|
This repo is where that evolution happens.
|