Skip to content

Latest commit

 

History

History
225 lines (170 loc) · 7.59 KB

06-tensorium-cli-tool.md

File metadata and controls

225 lines (170 loc) · 7.59 KB

Tutorial 06 — Mastering the Tensorium CLI Tool

The Tensorium CLI (tools/tensorium_cli.py) is your command center for installers, miners, and health checks. In this final tutorial we’ll keep things approachable—plenty of friendly tips, caution blocks, verification commands, and even a few image placeholders so teammates ramp up fast.

tensorium cli overview placeholder

Table of Contents

🎯 Learning goals

  • Install and expose the CLI globally (/usr/local/bin/tensorium).
  • Configure environment variables so every command knows which wallets/hotkeys to use.
  • Extend the CLI with new subcommands safely (logging + error handling).
  • Automate common operations (health checks, install pipelines, log collection).

🧠 Prerequisites

  • Tutorials 01–05 completed (env, wallets, miners).
  • Python basics (argparse, subprocess, logging).
  • Familiarity with /opt/tensorium layout.

💡 Tip: Keep docs/cli-cookbook.md updated with your favorite tensorium one-liners so the whole team benefits.

1. Install the CLI (friendly flow)

cd /opt/tensorium/bittensor
source .venv/bin/activate
pip install -r tools/requirements.txt   # optional extras for CLI extensions

chmod +x tools/tensorium_cli.py
sudo ln -sf /opt/tensorium/bittensor/tools/tensorium_cli.py /usr/local/bin/tensorium

⚠️ Warning: Make sure .venv/ exists and btcli works before symlinking. Otherwise global commands will fail due to missing dependencies.

Now tensorium --help is available from any shell (assuming /usr/local/bin is on PATH).

2. Command overview

tensorium list-subnets       # btcli subnet list wrapper
tensorium wallet             # wallet balance summary
tensorium start-miner        # wrap scripts/run_miner_simple.sh
tensorium install            # run scripts/install_bittensor.sh (sudo)
tensorium health             # GPU, venv, port checks
tensorium logs               # tail miner logs

Each subcommand emits structured JSON logs. Use --json when you want machine-friendly output.

cli subcommands placeholder

3. Configure environment variables

Create /opt/tensorium/cli.env:

TENSORIUM_PROJECT_DIR=/opt/tensorium/bittensor
TENSORIUM_DEFAULT_NETUID=1
BT_WALLET_NAME=tensorium
BT_WALLET_HOTKEY=miner-main
BT_HOTKEY_PASSWORD=change_me
LOG_DIR=/opt/tensorium/logs

Load it:

set -a
source /opt/tensorium/cli.env
set +a

Now commands shrink to: tensorium start-miner --netuid 1 --config configs/miner.yaml.

💬 Friendly reminder: Keep env files out of git (.gitignore) and lock down permissions (chmod 600 /opt/tensorium/cli.env).

4. Extend the CLI

Steps:

  1. Open tools/tensorium_cli.py.
  2. Create a handler function.
  3. Register it with sub.add_parser.
  4. Add helpful logging + exit codes.

Example:

def health(args):
    issues = []
    if shutil.which("nvidia-smi") is None:
        issues.append("No NVIDIA driver detected.")
    if not (PROJECT_DIR / ".venv").exists():
        issues.append("Virtual environment missing.")
    # Add more validators here (ports, env files, logs)
    if issues:
        for item in issues:
            logging.error(item)
        return 1
    logging.info("All health checks passed.")
    return 0

⚠️ Warning: Always wrap subprocess calls with try/except or check=False so the CLI returns clean errors instead of stack traces.

5. Automation use cases

  • Installer pipelines: tensorium install --target-dir /opt/tensorium.
  • Hourly health checks: 
    0 * * * * tensorium health >> /opt/tensorium/logs/health.log
  • CI verification: Run tensorium list-subnets --json inside GitHub Actions to confirm upstream compatibility.
  • Incident response: tensorium logs --netuid 1 --lines 100 for quick triage.

Because tensorium ultimately wraps btcli, ensure BT_HOTKEY_PASSWORD or keyring integration is available on any host running these commands.

6. Logging best practices

  • Default log file: /opt/tensorium/logs/tensorium-cli.log.
  • JSON lines example: 
    {"timestamp":"2025-11-17T10:05:12Z","level":"info","event":"start-miner","netuid":1}
  • Rotate with logrotate: 
    /opt/tensorium/logs/tensorium-cli.log {
    weekly
    rotate 4
    compress
    missingok
    create 640 ubuntu ubuntu
}

Verification commands:

tensorium --help | head -n 5
tensorium health
tail -n 20 /opt/tensorium/logs/tensorium-cli.log

cli logging placeholder

📘 Example Output

$ tensorium list-subnets --max-rows 3
[2025-11-17 10:02:11][INFO] Fetching subnet data via btcli ...
NETUID  NAME        TEMPO  INCENTIVE  DIVIDENDS
1       nakamoto    12     18.4%      11.0%
3       vision      12     21.1%      10.4%
7       language    18     17.6%      12.3%

$ tensorium health
[2025-11-17 10:04:55][INFO] Checking GPU availability ...
[2025-11-17 10:04:55][INFO] GPU: NVIDIA RTX 4090 • Driver 550.54 • CUDA 12.3
[2025-11-17 10:04:55][INFO] Verifying virtual environment ...
[2025-11-17 10:04:56][INFO] Axon ports 8091/8092 are free.
[2025-11-17 10:04:56][SUCCESS] All health checks passed.

$ tensorium start-miner --netuid 1 --config configs/miner-netuid-1.yaml
[2025-11-17 10:06:10][INFO] Launching miner profile netuid-1
[2025-11-17 10:06:10][INFO] Writing logs to /opt/tensorium/logs/miner-netuid-1.log
[2025-11-17 10:06:12][SUCCESS] Miner started (PID 3421). Use `tensorium logs --netuid 1` to tail output.

✅ Summary

  • Install the CLI inside the project venv, then symlink to /usr/local/bin/tensorium for convenience.
  • Source /opt/tensorium/cli.env (or use workflow env vars) so every subcommand knows which wallet/hotkey to operate on.
  • Extend the CLI with argparse subcommands + logging to provide guardrails for teammates.
  • Capture logs via /opt/tensorium/logs/tensorium-cli.log and rotate them regularly to prevent disk bloat.

📝 Review questions

  1. Why does Tensorium symlink the CLI into /usr/local/bin, and what prerequisite must be met first?
  2. How can environment variables reduce the number of command-line flags you need to pass to the CLI?
  3. Outline the steps required to add a new health subcommand.
  4. What are typical automation scenarios for the CLI, and how do they improve reliability?
  5. Where do CLI logs live, and how can you prevent them from consuming unlimited disk space?

Answers

  1. Symlinking makes tensorium available from any directory; ensure the virtual environment and file permissions are set before linking.
  2. Variables like BT_WALLET_NAME or TENSORIUM_DEFAULT_NETUID can be sourced from an env file so commands inherit defaults.
  3. Write a handler function, add it to the argparse subparsers, implement health logic, and register in the main dispatch.
  4. Installer scripts, hourly health checks, CI verifications, and log retrieval; automation standardizes operations and catches issues early.
  5. /opt/tensorium/logs/tensorium-cli.log; manage it with logrotate or another log rotation tool to rotate/compress files regularly.