{"id":7045,"library":"bittensor-cli","title":"Bittensor CLI","description":"bittensor-cli is the official command-line interface for interacting with the Bittensor network. It allows users to manage wallets, stake TAO, register hotkeys, manage subnets, and perform other on-chain operations. As of version 9.20.1, it provides robust tools for participants in the decentralized AI network, with frequent updates addressing bug fixes and new features.","status":"active","version":"9.20.1","language":"en","source_language":"en","source_url":"https://github.com/opentensor/btcli","tags":["cli","blockchain","decentralized AI","cryptocurrency","bittensor"],"install":[{"cmd":"pip install bittensor-cli","lang":"bash","label":"Install Bittensor CLI"}],"dependencies":[{"reason":"Runtime environment","package":"python","version":">=3.10","optional":false}],"imports":[],"quickstart":{"code":"import subprocess\nimport json\nimport sys\n\n# Note: bittensor-cli is primarily a command-line tool.\n# This quickstart demonstrates how to run a command programmatically.\n\ntry:\n    # Get the installed btcli version\n    version_process = subprocess.run(\n        [sys.executable, '-m', 'btcli', 'version'],\n        capture_output=True, text=True, check=True\n    )\n    print(f\"Bittensor CLI Version:\\n{version_process.stdout}\")\n\n    # List available subnets in JSON format\n    # This command requires a connection to the Bittensor network.\n    # Replace 'finney' with your preferred network, e.g., 'local' for a local setup.\n    print(\"\\nListing subnets on 'finney' network...\")\n    subnets_process = subprocess.run(\n        [sys.executable, '-m', 'btcli', 'subnets', 'list', '--netuid', '0', '--json-out', '--no-prompt', '--subtensor.chain_endpoint', 'ws://127.0.0.1:9944'], # Example using local, replace as needed\n        capture_output=True, text=True, check=False # check=False to catch potential errors gracefully\n    )\n\n    if subnets_process.returncode == 0:\n        try:\n            subnets_data = json.loads(subnets_process.stdout)\n            print(\"Successfully retrieved subnet information:\")\n            print(json.dumps(subnets_data, indent=2))\n        except json.JSONDecodeError:\n            print(\"Error: Could not decode JSON output.\")\n            print(f\"Raw output:\\n{subnets_process.stdout}\")\n    else:\n        print(f\"Error running btcli subnets list:\\n{subnets_process.stderr}\")\n\nexcept FileNotFoundError:\n    print(\"Error: 'btcli' command not found. Ensure bittensor-cli is installed and in your PATH.\")\nexcept subprocess.CalledProcessError as e:\n    print(f\"An unexpected error occurred: {e}\")\n    print(f\"Stdout: {e.stdout}\")\n    print(f\"Stderr: {e.stderr}\")\n","lang":"python","description":"This quickstart demonstrates how to programmatically execute `btcli` commands using Python's `subprocess` module, as bittensor-cli is primarily a command-line interface. It checks the CLI version and attempts to list subnets. Note that for actual network operations, a running subtensor node or a public endpoint is required."},"warnings":[{"fix":"Upgrade to `bittensor-cli>=9.20.1` and verify your coldkey/hotkey identities using `btcli wallet list` to confirm they are up-to-date. If issues arise, consider re-generating or migrating identities as per official documentation.","message":"Old identities were deprecated in `v9.20.1`. Users should ensure they are using the latest identity management practices.","severity":"deprecated","affected_versions":"<9.20.1"},{"fix":"There is no direct CLI replacement. Users needing wallet transaction history may need to consult blockchain explorers or alternative tools.","message":"The `wallet history` command has been disabled due to the deprecation of its external API dependency. This functionality is no longer available via the CLI.","severity":"breaking","affected_versions":">=9.19.0"},{"fix":"Instead of `--coldkey-ss58 <address>`, interact with coldkeys using their registered names, for example, `btcli wallet --wallet.name <coldkey_name>`. Refer to `btcli --help` for the current argument structure.","message":"The `--coldkey-ss58` parameter was consolidated into a predefined option in `v9.17.0`, leading to 'unknown argument' errors if using the old explicit SS58 address parameter.","severity":"gotcha","affected_versions":"<9.17.0"},{"fix":"Upgrade to `bittensor-cli>=9.20.2rc1` (or the latest stable version) to ensure correct handling of stake additions in complex wallet configurations.","message":"`stake add` operations for multi-hotkey and multi-netuid scenarios had mapping issues.","severity":"gotcha","affected_versions":"<9.20.2rc1"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"The command is permanently disabled. There is no CLI replacement; consult blockchain explorers for transaction history.","cause":"The `wallet history` command was disabled in version 9.19.0 due to the deprecation of an external API it relied upon.","error":"Command 'wallet history' is not available"},{"fix":"Upgrade your `bittensor-cli` to version `9.19.0` or newer: `pip install --upgrade bittensor-cli`.","cause":"A bug in earlier versions caused the `--json-out` flag to return empty output for certain commands, including `subnets list`.","error":"JSON output is empty for `btcli subnets list --json-out`"},{"fix":"Remove the `--coldkey-ss58` argument and instead use `btcli wallet --wallet.name <coldkey_name>` or ensure your command structure aligns with the post-v9.17.0 documentation for wallet interactions.","cause":"In `v9.17.0`, the `--coldkey-ss58` argument was deprecated in favor of interacting with coldkeys by their name or through integrated wallet commands.","error":"Error: unrecognized arguments: --coldkey-ss58"},{"fix":"Upgrade to `bittensor-cli>=9.20.2rc1` (or the latest stable release after it) to resolve stake mapping issues: `pip install --upgrade bittensor-cli`.","cause":"Versions prior to `9.20.2rc1` contained a bug where `stake add` operations could fail or incorrectly map when dealing with multiple hotkeys or netuids.","error":"Failed to add stake: Operation mapping error for multi-hotkey/netuid."}]}