feat:add filter/sort/limit to | shell completion | download

[michaelj094]

feat: Add filter and output to subnets & metagraph,shell completion

Summary

This PR adds advanced filtering, sorting, column-selection, limiting, and structured output options to the subnets list command and extends the same usability flags to the subnets metagraph command. It also introduces a top-level btcli completion command for easy shell completion installation and a set of improvements to output handling and documentation.

Description of Changes

• New btcli completion command to generate and optionally install shell completion scripts for Bash, Zsh, Fish, and PowerShell. README updated with instructions.
• Enhanced subnets list command with many usability flags (filter, sort, limit, columns, output format, pager, header control, wide mode).
• Added the same set of flags and behavior to the subnets metagraph command so users can filter/sort/limit neurons, select columns, and export JSON/YAML.
• Refactored list-like logic into pure helper functions to decouple CLI parsing from business logic and make testing easier.
• Added unit tests for the new filter/sort/limit helpers used by subnets list and subnets metagraph.
• Added support for BTCLI_PAGER environment variable to page large table outputs.

Motivation and Context

Working with large subnet lists or full metagraphs can be cumbersome. These changes give users granular control over list-like outputs (filtering, sorting, limiting, and column selection), allow structured export (JSON/YAML), and improve developer experience via modular helpers and tests. Shell completion increases productivity for interactive use.

Files Changed (high level)

• README.md — shell completion docs and output tips
• bittensor_cli/cli.py — added flags and validation, completion command, pass-through of new options
• bittensor_cli/src/commands/subnets/subnets.py —
  • Added filter_sort_limit_subnets (existing commit) and filter_sort_limit_metagraph_rows helpers
  • Extended subnets_list and metagraph_cmd to accept and honor new options (output, columns, no-header, wide, uids/hotkey-contains, sort-by, sort-order, limit)
  • Added JSON/YAML output mode for metagraph
  • Pager support for table output when BTCLI_PAGER is set
• tests/unit_tests/test_subnets_list_sort_filter.py — unit tests for subnets list helper
• tests/unit_tests/test_metagraph_list_sort_filter.py — unit tests for metagraph helper (new)

(See commit for exact diffs and line-level changes.)

New CLI Flags (examples)

Flag(s)	Description
--netuids / -n	(subnets list) Show only selected netuids (comma-separated).
--uids / -u	(metagraph) Show only selected neuron UIDs (comma-separated).
--name-contains / --name	Filter subnets by name substring (case-insensitive).
--hotkey-contains / --hotkey	Filter metagraph rows whose hotkey contains this substring (case-insensitive).
--sort-by	Sort by supported columns (see README / help for allowed values).
--sort-order	Ascending (asc) or descending (desc).
--limit / --top	Limit results to the first N rows (applies after filtering+sorting).
--output / -o	Output format: table, json, yaml. Overrides legacy --json-output.
--columns	Comma-separated column ids to display (table & structured output).
--no-header	Hide table header/title/footers (table output only).
--wide / -w	Wider table (less truncation).

Usage Examples

Filter + sort + limit (subnets):

btcli subnets list \
  --netuids 0,2 \
  --name-contains "AI" \
  --sort-by market_cap \
  --sort-order desc \
  --limit 5 \
  --output json \
  --columns netuid,name,market_cap \
  --no-header \
  --wide

Metagraph: list top 10 neurons by global stake for a subnet, output as YAML:

btcli subnets metagraph --netuid 1 \
  --sort-by global_stake --sort-order desc --limit 10 \
  --output yaml --columns uid,hotkey,global_stake,rank

Metagraph: filter by hotkey substring and show columns in a wide table:

btcli subnets metagraph --netuid 1 --hotkey-contains alice --columns uid,hotkey,local_stake,trust --wide

Shell completion installation (examples):

btcli completion bash --install
btcli completion zsh --install
btcli completion fish --install
btcli completion powershell --install

Testing Performed

• Manual testing of btcli completion for supported shells (script output and --install).
• Manual testing of subnets list and subnets metagraph with combinations of filters, --columns, --output, --limit, and --wide.
• Unit tests added for the pure helpers used by both commands:
  • tests/unit_tests/test_subnets_list_sort_filter.py (existing)
  • tests/unit_tests/test_metagraph_list_sort_filter.py (new)

To run the new tests locally:

pytest -q tests/unit_tests/test_subnets_list_sort_filter.py tests/unit_tests/test_metagraph_list_sort_filter.py

Backwards compatibility & notes

• The new --output flag supersedes --json-output when provided; legacy --json-output behavior is preserved unless overridden by --output.
• --html (metagraph) is mutually exclusive with structured json/yaml outputs.
• Column selection via --columns overrides the per-user config metagraph_cols for that invocation only.
• Helpers are intentionally pure to make them reusable for other list-like commands (wallets, stake lists, proxies) in the future.

Contribution by Gittensor, see my contribution statistics at https://gittensor.io/miners/details?githubId=191372963

[michaelj094]

Hi @ibraheem-abe,

I hope you’re doing well! I’ve submitted a PR for adding filter and output to subnets & metagraph and shell completion: #793

When you have a chance, I’d really appreciate your review and any feedback.

Thank you so much!

Best regards,

Michael

[thewhaleking]

What's the benefit of this over the currently existing btcli --install-completion?

[thewhaleking]

I think this is a neat and novel approach. Two things I will recommend, however:

1. Remove the install completion stuff. The standard btcli --install-completion works great, and doesn't require maintenance on our part.
2. Your new reused options should live in the Options class.