nssh

nssh is an SSH wrapper for operators who manage many hosts. It keeps host inventory, auth policy, routing, and SSH options in nssh YAML config, resolves credentials from external password managers, injects passwords through OpenSSH prompts, and can record sessions.

Demo

Features

• Smart connect: nssh HOST, nssh user@HOST, and nssh --select route through nssh inventory lookup, partial host matching, and optional fzf selection. Use nssh --target HOST for literal destinations that collide with nssh command names.
• SSH command line: root invocations keep SSH-style option and command boundaries. In 0.3, recognized SSH options can appear before or after the destination until the remote command starts. Use -- when a remote command begins with -; nssh -- HOST -p 2222 and nssh HOST -- -p 2222 both run -p 2222 on HOST rather than treating it as an SSH port option.
• Inventory: nssh inv manages local hosts and external providers; current providers are NetBox and containerlab.
• Credentials: SOPS+age, 1Password, and Bitwarden providers are selected by inventory host or group auth mappings. nssh has no local password vault.
• Agent runtime: nssh agent brokers provider-session requests and runs retained provider access only when configured.
• Connection behavior: OpenSSH still owns transport; nssh wraps it with a PTY connector for prompt detection, password injection, host-key handling, timing, and typed SSH option rendering.
• Recordings: optional asciinema session capture is managed with nssh log.
• SCP: nssh cp uses the same host and credential resolution path as connect.
• Multi-host commands: nssh repl provides an interactive terminal prompt or plain piped input. A root command may also target a bare comma list such as nssh 'edge1, edge2' 'show version'; it runs one command per host with four workers by default. Lists require a remote command and keep its argv unchanged.

Run nssh --help or read the generated help snapshots under docs/examples/help. The first-run config template is internal/config/example_config.yaml.

Multi-host commands

Start nssh repl, then submit targets and commands:

[ 'irn-border-sw(1,2)', 'irn-agg-sw(1,2)' ] ( 'show env power' )

Or pipe a submission from fish:

printf '%s\n' "[ 'irn-border-sw(1,2)', 'irn-agg-sw(1,2)' ] ( 'show env power' )" | nssh repl

REPL is a normal command in the 0.3 development series. A literal host named repl uses nssh --target repl. Authenticate credential providers before entering the REPL. Output appears when each command finishes; commands cannot read interactive input. See the REPL guide for grammar, keys, limits, and errors.

Installation

curl -fsSL https://raw.githubusercontent.com/ntwrknrd/nssh/main/scripts/install.sh | sh

nssh self init
nssh self status

To update, run nssh self reinstall; it installs the latest GitHub release.

On first run, nssh self init creates the commented root config template and offers credential and inventory provider setup. If config.yaml already exists, bare init skips without changing it; use nssh self reset to start fresh. Add providers later with nssh self init --cred <provider> or nssh self init --inv <provider>. Inventory auth mappings are added later with nssh inv set. To remove local nssh state:

nssh self uninstall

Use --dry-run, --keep-config, or --keep-recordings when needed. External password-manager records are not removed.

Documentation

• 0.2 to 0.3 RC migration guide - standalone beta-tester guide with backup, conversion, verification, and rollback steps.
• CONTRIBUTING.md - development workflow, tests, releases, and doc rules.
• skills/nssh/SKILL.md - portable nssh skill entrypoint for usage, configuration, inventory, credentials, operations, troubleshooting, and architecture references.

Dependencies

nssh builds around OpenSSH, Cobra, Charm terminal UI packages, creack/pty, optional fzf, optional asciinema, and external credential CLIs such as sops, op, and bw. See LICENSE.