coinhunter-cli

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

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

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
• precheck internals now also have dedicated service modules for:
  • 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

Editable install:

pip install -e .

Run directly after install:

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:

coinhunter init

Inspect runtime wiring:

coinhunter paths
coinhunter diag

Validate exchange credentials:

coinhunter api-check

Run precheck / gate plumbing:

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:

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:

coinhunter review 12
coinhunter recap 12

Probe external market data:

coinhunter probe bybit-ticker BTCUSDT
coinhunter probe bybit-klines BTCUSDT 60 20

Long-form equivalents still work:

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:

~/.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

coinhunter diag
coinhunter paths
coinhunter api-check

Trading and execution

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

coinhunter precheck
coinhunter gate
coinhunter rotate-gate-log
coinhunter rotate-log

Review and market research

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.