# coinhunter-cli

The executable CLI layer for CoinHunter.
Runtime-safe trading operations, precheck orchestration, review tooling, and market probes.

Python Status Architecture

## 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 ``` ## 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.