Mining/docs/user-guide/cli.md

CLI User Guide

The miner-ctrl command-line interface provides complete control over Mining Platform from your terminal.

Installation

See the Installation Guide for installation instructions.

Global Flags

These flags work with any command:

• --config string: Config file path (default: $HOME/.mining.yaml)
• --help: Show help for the command

Commands

serve

Start the mining service and interactive shell.

Usage:

miner-ctrl serve [flags]

Flags:

• --host string: Host to listen on (default: 0.0.0.0)
• -p, --port int: Port to listen on (default: 8080)
• -n, --namespace string: API namespace (default: /api/v1/mining)

Examples:

# Start on localhost:9090
miner-ctrl serve --host localhost --port 9090

# Start with custom namespace
miner-ctrl serve --namespace /mining/v2

# Start with interactive shell
miner-ctrl serve

When the server is running, you can access:

• REST API: http://localhost:8080/api/v1/mining/
• Swagger UI: http://localhost:8080/api/v1/mining/swagger/index.html

start

Start a new miner instance.

Usage:

miner-ctrl start [miner-type] [flags]

Arguments:

• miner-type: Type of miner to start (e.g., xmrig)

Flags:

• --config string: Path to configuration file
• --pool string: Mining pool URL
• --wallet string: Wallet address
• --algo string: Mining algorithm
• --threads int: Number of threads to use

Examples:

# Start with config file
miner-ctrl start xmrig --config xmr-config.json

# Start with inline parameters
miner-ctrl start xmrig \
  --pool stratum+tcp://pool.supportxmr.com:3333 \
  --wallet YOUR_WALLET_ADDRESS \
  --algo rx/0 \
  --threads 4

# Start GPU mining
miner-ctrl start xmrig \
  --pool stratum+tcp://etc.woolypooly.com:3333 \
  --wallet YOUR_ETC_WALLET \
  --algo etchash \
  --cuda

stop

Stop a running miner instance.

Usage:

miner-ctrl stop [miner-name]

Examples:

# Stop a miner by name
miner-ctrl stop xmrig

# Stop all miners
miner-ctrl stop --all

status

Get the status and statistics of a running miner.

Usage:

miner-ctrl status [miner-name]

Output includes:

• Hashrate (current and average)
• Accepted/rejected shares
• Uptime
• Temperature (if supported)
• Power usage (if supported)

Examples:

# Get status of specific miner
miner-ctrl status xmrig

# Get JSON output for scripting
miner-ctrl status xmrig --json

list

List running miners and available miner types.

Usage:

miner-ctrl list [flags]

Flags:

• --running: Show only running miners
• --available: Show only available miner types

Examples:

# List all running miners
miner-ctrl list

# Show available miner types
miner-ctrl list --available

# Detailed output
miner-ctrl list --verbose

install

Install or update a miner binary.

Usage:

miner-ctrl install [miner-type] [flags]

Flags:

• --force: Force reinstall even if already installed
• --version string: Install specific version

Examples:

# Install XMRig
miner-ctrl install xmrig

# Install specific version
miner-ctrl install xmrig --version 6.21.0

# Force reinstall
miner-ctrl install xmrig --force

Miners are installed to ~/.local/share/lethean-desktop/miners/[miner-type]/.

uninstall

Uninstall a miner and remove its files.

Usage:

miner-ctrl uninstall [miner-type]

Examples:

# Uninstall XMRig
miner-ctrl uninstall xmrig

# Uninstall with confirmation
miner-ctrl uninstall xmrig --confirm

update

Check for updates to installed miners.

Usage:

miner-ctrl update [flags]

Flags:

• --check-only: Only check for updates, don't install
• --all: Update all miners with available updates

Examples:

# Check for updates
miner-ctrl update --check-only

# Update all miners
miner-ctrl update --all

# Update specific miner
miner-ctrl update xmrig

doctor

Check the status of all installed miners and system configuration.

Usage:

miner-ctrl doctor

Output includes:

• Installed miners and versions
• GPU detection (OpenCL/CUDA)
• System resources
• Configuration file locations
• Potential issues and recommendations

Examples:

# Run full diagnostic
miner-ctrl doctor

# Output to file for troubleshooting
miner-ctrl doctor > system-info.txt

completion

Generate shell completion scripts.

Usage:

miner-ctrl completion [shell]

Supported shells:

• bash
• zsh
• fish
• powershell

Examples:

# Bash completion
miner-ctrl completion bash > /etc/bash_completion.d/miner-ctrl

# Zsh completion
miner-ctrl completion zsh > "${fpath[1]}/_miner-ctrl"

# Fish completion
miner-ctrl completion fish > ~/.config/fish/completions/miner-ctrl.fish

Configuration File

Create a config file at ~/.mining.yaml:

server:
  host: localhost
  port: 9090
  namespace: /api/v1/mining

defaults:
  miner: xmrig
  threads: 4
  cpuPriority: 3

profiles:
  - name: XMR
    pool: stratum+tcp://pool.supportxmr.com:3333
    wallet: YOUR_XMR_WALLET
    algo: rx/0

  - name: ETC
    pool: stratum+tcp://etc.woolypooly.com:3333
    wallet: YOUR_ETC_WALLET
    algo: etchash

Load a profile:

miner-ctrl start --profile XMR

Interactive Shell

When you run miner-ctrl serve without backgrounding it, you get an interactive shell:

Mining Platform v1.0.0
API Server running on http://localhost:9090
Type 'help' for available commands

mining> help
Available commands:
  list      - List running miners
  start     - Start a miner
  stop      - Stop a miner
  status    - Get miner status
  profiles  - Manage profiles
  exit      - Exit shell

mining> list
Running miners:
  xmrig - Hashrate: 4520 H/s, Shares: 42/0

mining> status xmrig
Miner: xmrig
Status: Running
Hashrate: 4520 H/s
Accepted Shares: 42
Rejected Shares: 0
Uptime: 2h 15m

Output Formats

Most commands support multiple output formats:

# Human-readable (default)
miner-ctrl list

# JSON for scripting
miner-ctrl list --output json

# YAML
miner-ctrl status xmrig --output yaml

# Table format
miner-ctrl list --output table

Environment Variables

Configure behavior with environment variables:

# Set config file location
export MINING_CONFIG=~/.config/mining.yaml

# Set data directory
export MINING_DATA_DIR=~/.local/share/mining

# Set log level
export MINING_LOG_LEVEL=debug

# Start server
miner-ctrl serve

Examples

Basic Mining Workflow

# 1. Install miner
miner-ctrl install xmrig

# 2. Verify installation
miner-ctrl doctor

# 3. Start mining
miner-ctrl start xmrig \
  --pool stratum+tcp://pool.supportxmr.com:3333 \
  --wallet YOUR_WALLET \
  --algo rx/0

# 4. Monitor
miner-ctrl status xmrig

# 5. Stop when done
miner-ctrl stop xmrig

Dual Mining (CPU + GPU)

# Start CPU mining for Monero
miner-ctrl start xmrig-cpu \
  --pool stratum+tcp://pool.supportxmr.com:3333 \
  --wallet YOUR_XMR_WALLET \
  --algo rx/0 \
  --threads 4

# Start GPU mining for Ethereum Classic
miner-ctrl start xmrig-gpu \
  --pool stratum+tcp://etc.woolypooly.com:3333 \
  --wallet YOUR_ETC_WALLET \
  --algo etchash \
  --cuda

# Monitor both
miner-ctrl list

Automated Monitoring

# Create a monitoring script
cat > monitor.sh << 'EOF'
#!/bin/bash
while true; do
  clear
  echo "=== Mining Status ==="
  miner-ctrl status xmrig --output json | jq '.hashrate, .shares'
  sleep 10
done
EOF

chmod +x monitor.sh
./monitor.sh

Troubleshooting

Command Not Found

Ensure miner-ctrl is in your PATH:

which miner-ctrl
# If not found, add to PATH or use full path

Permission Denied

On Linux, you may need to run with appropriate permissions:

# Grant execute permission
chmod +x miner-ctrl

# Or run with sudo if needed (not recommended)
sudo miner-ctrl doctor

Miner Won't Start

Check logs for errors:

# Enable debug logging
miner-ctrl --log-level debug start xmrig ...

# Check system journal (Linux)
journalctl -u mining-service

Port Already in Use

If port 8080 is already in use:

# Use a different port
miner-ctrl serve --port 9090

Next Steps

• Explore the Web Dashboard for visual management
• Try the Desktop Application for a native experience
• Read the API Documentation for integration
• See Pool Integration Guide for pool recommendations