Skip to content

Shell Completions for nw

This directory contains dynamic shell completions for the nw (Networka) command. Supported shells:

  • Bash (Linux/macOS)
  • Zsh (Linux/macOS)

Features

The completions provide intelligent suggestions powered by the CLI itself:

  • Commands: All nw subcommands (info, run, list-*, etc.)
  • Device names: Read from your active configuration
  • Device groups: From the device_groups section
  • Command sequences: Global, vendor, and device-specific sequences
  • Sequence groups: Predefined groups of command sequences
  • Tags: Available tags for tag-based operations
  • File paths: Context-aware file completion for config files, firmware, etc.
  • Options: All command-line options and flags

Installation

Use the provided installation script (supports bash/zsh):

# Install system-wide (requires sudo)
./install_completion.sh --system

# Install for current user only
./install_completion.sh --user

# Show manual installation instructions
./install_completion.sh --manual

# Show help
./install_completion.sh --help

Manual Installation (per shell)

Option 1: Source in your shell profile

Add this line to your ~/.bashrc, ~/.bash_profile, or ~/.profile:

source "/path/to/bash_completion_nw.sh"

For zsh, copy zsh_completion_nw.zsh to one of your $fpath directories as _nw, e.g.:

mkdir -p ~/.zsh/completions
cp zsh_completion_nw.zsh ~/.zsh/completions/_nw
echo 'fpath+=$HOME/.zsh/completions' >> ~/.zshrc
echo 'autoload -Uz compinit && compinit' >> ~/.zshrc

Option 2: System-wide installation (bash)

Copy the completion file to the bash completion directory:

# Most Linux distributions
sudo cp bash_completion_nw.sh /etc/bash_completion.d/nw

# Some distributions use this path
sudo cp bash_completion_nw.sh /usr/share/bash-completion/completions/nw

Option 3: User-specific bash-completion

If you use bash-completion locally:

mkdir -p ~/.local/share/bash-completion/completions
cp bash_completion_nw.sh ~/.local/share/bash-completion/completions/nw

Usage Examples

Once installed, you can use TAB completion with the nw command:

Basic Command Completion

nw <TAB><TAB>
# Shows: info run list ...

nw list <TAB><TAB>
# Shows: devices sequences groups supported-types ...

Device, Group, and Sequence Name Completion

nw info <TAB><TAB>
# Shows: core1br core2br vpn1br sw-acc1 sw-dist1 ... (devices)
#        access_switches core_devices dmz_devices ... (groups)
#        system_info backup_config health_check ... (sequences)

nw run sw-<TAB><TAB>
# Shows: sw-acc1 sw-acc2 sw-dist1

Group Name Completion (as run target)

nw run <TAB><TAB>
# Shows device and group names

Sequence Completion (via run)

nw run sw-acc1 <TAB><TAB>
# Shows: health_check system_info interface_monitoring security_audit ...
# Plus device-specific sequences: interface_status

# Or use run with sequences (device or group)
nw run sw-acc1 <TAB><TAB>
# Shows: commands or known sequences

nw run core <TAB><TAB>
# Shows global sequences for groups

Vendor/user-defined sequence completion

nw run sw-acc1 <TAB><TAB>
# Includes vendor/user sequences resolved via device type

File and Option Completion

nw upload sw-acc1 <TAB>
# Shows file completion for local files

nw info --<TAB><TAB>
# Shows: --config --verbose --help

nw run --config <TAB><TAB>
# Shows *.yml and *.yaml files

Configuration File Detection

The completion scripts automatically detect your configuration file:

  1. Looks for --config or -c options in the current command
  2. Uses the modular config directory (no single-file fallback)
  3. Asks the CLI for suggestions via a hidden __complete command

Advanced Features

Multi-level Completion

The completion is context-aware and provides different suggestions based on:

  • The current command being typed
  • The position of the cursor
  • Previously typed arguments
  • The configuration file contents

Dynamic Engine

Completions are generated by the CLI on-the-fly, so:

  • New devices/groups/sequences are available immediately
  • Vendor and user-defined sequences are included when relevant
  • No parsing logic duplicated in shell scripts

Error Handling

The completion gracefully handles:

  • Missing configuration files
  • Malformed YAML (falls back to no completion)
  • Permission issues
  • Non-existent directories

Troubleshooting

Completion Not Working

  1. Check if completion is loaded:
complete -p nw
# Should show: complete -F _nw nw
  1. Manually load completion:
source /path/to/bash_completion_nw.sh
  1. Check bash-completion is installed:
# Ubuntu/Debian
sudo apt install bash-completion

# RHEL/CentOS/Fedora
sudo yum install bash-completion
# or
sudo dnf install bash-completion

Configuration File Issues

  1. Verify YAML syntax:
nw config validate
  1. Check file permissions:
ls -la config/
  1. Test with explicit config: 
    nw --config /path/to/config info <TAB>

Performance Issues

If completion is slow with large configuration files:

  1. Optimize YAML parsing by simplifying the awk scripts
  2. Cache results (future enhancement)
  3. Use a smaller configuration file for testing

Files

  • bash_completion_nw.sh - Main completion script
  • install_completion.sh - Automated installation script
  • README.md - This documentation

Contributing

To improve the completion:

  1. Test with various YAML configurations
  2. Add support for new nw commands
  3. Improve performance for large config files
  4. Add support for additional file types
  5. Enhance error handling

The completion also works with these command variations:

  • networka (alternative name)
  • network-toolkit (legacy name)

Note: This completion requires bash 4.0+ and is tested on Linux and macOS with bash-completion 2.0+.