feat: add cli for axon set and reset #726

Mobile-Crest · 2025-12-03T08:54:14Z

Add CLI commands for axon management

Closes #225

Summary

This PR adds two new CLI commands to manage axon serving information for neurons on the Bittensor network:

btcli axon reset - Resets axon to stop serving (sets IP to 0.0.0.0 and port to 1 as chain doesn't accept 0 as invalid port)
btcli axon set - Sets axon serving endpoint with specified IP and port

Motivation

Miners and validators need a convenient way to manage their axon serving endpoints directly from the CLI without writing custom scripts. This is particularly useful for:

Temporarily stopping a neuron from serving
Updating serving endpoints when changing infrastructure
Managing multiple neurons across different subnets

Changes

New Files

bittensor_cli/src/bittensor/extrinsics/serving.py
- reset_axon_extrinsic() - Handles axon reset logic
- set_axon_extrinsic() - Handles axon set logic
- ip_to_int() - Utility for IP address conversion
- Includes validation, error handling, and user prompts
tests/unit_tests/test_axon_commands.py
- 16 comprehensive unit tests
- Tests for IP conversion, extrinsic functions, and CLI handlers
- 100% test coverage for new functionality
tests/e2e_tests/test_axon.py
- 3 end-to-end tests against local blockchain
- Tests full workflow, IPv6 support, and error handling

Modified Files

bittensor_cli/cli.py
- Added import for serving extrinsics module
- Created axon_app Typer application
- Registered axon app with main CLI
- Added axon_reset() command handler
- Added axon_set() command handler
- Registered commands with the axon app

Usage

Reset Axon

Stop a neuron from serving by resetting its axon information:

btcli axon reset --netuid 1 --wallet-name my_wallet --wallet-hotkey my_hotkey

Set Axon

Configure a neuron's serving endpoint:

# IPv4
btcli axon set --netuid 1 --ip 192.168.1.100 --port 8091 \
  --wallet-name my_wallet --wallet-hotkey my_hotkey

# IPv6
btcli axon set --netuid 1 --ip 2001:db8::1 --port 8091 --ip-type 6 \
  --wallet-name my_wallet --wallet-hotkey my_hotkey

Available Options

Both commands support:

--netuid - Subnet ID (required)
--wallet-name - Wallet name
--wallet-hotkey - Hotkey name
--wallet-path - Custom wallet path
--network - Network to connect to (default: finney)
--prompt / --no-prompt - Interactive confirmation
--wait-for-inclusion - Wait for block inclusion
--wait-for-finalization - Wait for finalization
--quiet - Minimal output
--verbose - Detailed output

Additional for set:

--ip - IP address (required)
--port - Port number 0-65535 (required)
--ip-type - 4 for IPv4, 6 for IPv6 (default: 4)
--protocol - Protocol version (default: 4)

Examples

Example 1: Reset axon for maintenance

btcli axon reset --netuid 1 --wallet-name validator --wallet-hotkey default

Example 2: Set axon with public IP

btcli axon set --netuid 1 --ip 203.0.113.42 --port 8091 \
  --wallet-name miner --wallet-hotkey default

Example 3: Set axon without prompts (automation)

btcli axon set --netuid 1 --ip 192.168.1.100 --port 8091 \
  --wallet-name miner --wallet-hotkey default --no-prompt

Testing

Unit Tests

# Run all unit tests
python -m pytest tests/unit_tests/test_axon_commands.py -v

Test Coverage:

✅ IP address conversion (IPv4, IPv6, validation)
✅ Reset axon extrinsic (success, failures, cancellation)
✅ Set axon extrinsic (success, validation, IPv6, errors)
✅ CLI command handlers

E2E Tests

# Run e2e tests (requires Docker)
python -m pytest tests/e2e_tests/test_axon.py -v

Test Coverage:

✅ Full workflow (create subnet, register, set, verify, reset)
✅ IPv6 address support
✅ Invalid input handling

Implementation Details

Technical Approach

Extrinsic Composition
- Uses SubtensorModule::serve_axon call
- Parameters: netuid, version, ip, port, ip_type, protocol, placeholders
- Signed with hotkey (not coldkey)
IP Address Handling
- Converts IP strings to integers using netaddr library
- Supports both IPv4 and IPv6
- Validates format before submission
Error Handling
- Input validation (IP format, port range)
- Hotkey unlock verification
- Blockchain submission errors
- User-friendly error messages
User Experience
- Optional confirmation prompts
- Rich console output with colors and icons
- Progress indicators during submission
- Clear success/failure messages

Security Considerations

Hotkey must be unlocked to sign extrinsic
Extrinsic signed with hotkey (not coldkey)
IP and port are publicly visible on blockchain
No sensitive information logged

Contribution by Gittensor, learn more at https://gittensor.io/

thewhaleking

This one is at least better than #725, but still has a lot going on that should have been verified before submitting.

bittensor_cli/src/bittensor/extrinsics/serving.py

bittensor_cli/cli.py

Mobile-Crest · 2025-12-03T19:43:47Z

@thewhaleking
can you please review this pr again?

thewhaleking

Looks better. Will do a full review tomorrow.

thewhaleking · 2025-12-03T20:03:00Z

tests/unit_tests/test_axon_commands.py

+        # is_success is a property that returns a coroutine
+        async def mock_is_success():
+            return True
+        mock_response.is_success = mock_is_success()


Be careful with this. It's fine here, but be careful in future situations as this will assign the coroutine object as is_success rather than the coroutine function property as it is usually used.

Typically you can do

await response.is_success await response.is_success await response.is_success ...

because it's a property, but by assigning the result of a coroutine function to it, you can only do it once, and then you'll raise exceptions if you try to await it again. It can be a pain to debug.

thewhaleking

lgtm

Mobile-Crest · 2025-12-04T20:27:44Z

@thewhaleking
can you merge this pr if all looks good?

thewhaleking · 2025-12-05T08:42:05Z

@thewhaleking can you merge this pr if all looks good?

Think we're not going to include this in 9.16, as it's already quite filled up. Should merge to staging after release of 9.16 (either today or Monday, coinciding with the release of mainnet)

feat: add cli for axon set and reset - Closes opentensor#225

e819fb3

thewhaleking requested a review from a team December 3, 2025 12:27

thewhaleking requested changes Dec 3, 2025

View reviewed changes

Mobile-Crest marked this pull request as draft December 3, 2025 13:50

refactoring and bug fix

763ee28

Mobile-Crest marked this pull request as ready for review December 3, 2025 19:20

Mobile-Crest requested a review from thewhaleking December 3, 2025 19:21

Mobile-Crest marked this pull request as draft December 3, 2025 19:23

fix unit and e2e tests

8e50f2b

Mobile-Crest marked this pull request as ready for review December 3, 2025 19:43

thewhaleking reviewed Dec 3, 2025

View reviewed changes

thewhaleking previously approved these changes Dec 4, 2025

View reviewed changes

Mobile-Crest added 2 commits December 5, 2025 03:49

run ruff format

b34eb12

fix e2e test

00d0d50

Mobile-Crest dismissed thewhaleking’s stale review via 00d0d50 December 5, 2025 02:56

Mobile-Crest requested a review from thewhaleking December 5, 2025 02:56

fix e2e test error

e4b3d32

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add cli for axon set and reset #726

feat: add cli for axon set and reset #726

Mobile-Crest commented Dec 3, 2025 •

edited

Loading

Uh oh!

thewhaleking left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Mobile-Crest commented Dec 3, 2025

Uh oh!

thewhaleking left a comment

Uh oh!

thewhaleking Dec 3, 2025

Uh oh!

thewhaleking left a comment

Uh oh!

Mobile-Crest commented Dec 4, 2025

Uh oh!

thewhaleking commented Dec 5, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat: add cli for axon set and reset #726

Are you sure you want to change the base?

feat: add cli for axon set and reset #726

Conversation

Mobile-Crest commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Add CLI commands for axon management

Summary

Motivation

Changes

New Files

Modified Files

Usage

Reset Axon

Set Axon

Available Options

Examples

Example 1: Reset axon for maintenance

Example 2: Set axon with public IP

Example 3: Set axon without prompts (automation)

Testing

Unit Tests

E2E Tests

Implementation Details

Technical Approach

Security Considerations

Uh oh!

thewhaleking left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Mobile-Crest commented Dec 3, 2025

Uh oh!

thewhaleking left a comment

Choose a reason for hiding this comment

Uh oh!

thewhaleking Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

thewhaleking left a comment

Choose a reason for hiding this comment

Uh oh!

Mobile-Crest commented Dec 4, 2025

Uh oh!

thewhaleking commented Dec 5, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Mobile-Crest commented Dec 3, 2025 •

edited

Loading