coinhunter-cli/README.md

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

```bash
pip install -e .
```

Run directly after install:

```bash
coinhunter --help
coinhunter --version
```

## Quickstart

Initialize user state:

```bash
coinhunter init
```

Inspect runtime wiring:

```bash
coinhunter paths
coinhunter doctor
```

Validate exchange credentials:

```bash
coinhunter check-api
```

Run precheck / gate plumbing:

```bash
coinhunter precheck
coinhunter precheck --mark-run-requested "external-gate queued cron run"
coinhunter precheck --ack "analysis finished"
```

Inspect balances or execute trading actions:

```bash
coinhunter smart-executor balances
coinhunter smart-executor status
coinhunter smart-executor hold
coinhunter smart-executor buy ENJUSDT 50
coinhunter smart-executor sell-all ENJUSDT
```

Generate review data:

```bash
coinhunter review-context 12
coinhunter review-engine 12
```

Probe external market data:

```bash
coinhunter market-probe bybit-ticker BTCUSDT
coinhunter market-probe bybit-klines BTCUSDT 60 20
```

## 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 doctor
coinhunter paths
coinhunter check-api
```

### Trading and execution

```bash
coinhunter smart-executor balances
coinhunter smart-executor status
coinhunter smart-executor hold
coinhunter smart-executor rebalance FROMUSDT TOUSDT
```

### Precheck and orchestration

```bash
coinhunter precheck
coinhunter external-gate
coinhunter rotate-external-gate-log
```

### Review and market research

```bash
coinhunter review-context 12
coinhunter review-engine 12
coinhunter market-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.