Crate ssh_cli 

ssh-cli

Full-stack Rust CLI that gives an LLM (Claude Code, Cursor, Windsurf) the ability to operate remote servers over SSH in a subprocess flow via stdin/stdout.

Modules

Module	Responsibility
cli	Clap derive argument definitions (contract)
commands	Subcommand dispatch layer (CAMADA 2)
concurrency	Bounded multi-host / tunnel fan-out (Semaphore + JoinSet)
constants	Named domain constants (XDG names, env keys, network/timing)
net	Async DNS + Happy Eyeballs TCP dial for SSH connect
error/errors	Structured error types via thiserror + retry classification
retry	Named RetryConfig + full-jitter backoff (agent contract)
vps	CRUD and persistence of VPS records (XDG + TOML + 0o600)
secrets	Primary key and default at-rest encryption (ChaCha20-Poly1305)
ssh	Real one-shot SSH client via russh (password/key, TOFU)
tls	rustls (aws_lc_rs): SSH-over-TLS, mTLS, ACME (feature tls)
i18n	Bilingual UI (Message enum + exhaustive EN/pt-BR match)
json_wire	Typed agent JSON DTOs + compact emit (RFC 8259, not NDJSON)
locale	BCP47 detect/negotiate (sys-locale + unic-langid + langneg)
platform	Windows UTF-8/VT, runtime env (WSL/container/CI), TTY
masking	Unicode-safe masking of sensitive values
output	Sole module authorized for stdout/stderr data emission
paths	Path validation and normalization (anti-traversal, NFC)
signals	One-shot SIGINT/SIGTERM flags + cooperative should_stop
telemetry	Process-local tracing install (stderr; no OTEL / no files)
validation	Parse→serde→validator pipeline for config/import (no OTEL)
domain	Newtypes: VpsName, Rfc3339Utc, BatchRunId, HttpsUrl, Money…
terminal	TTY detection and color choice via termcolor

Features

Feature	Default	Effect
ssh-real	yes	Real SSH via russh + aws-lc-rs (compression none only; G-TLS)
tls	yes	rustls ≥0.23.18 + aws_lc_rs: SSH-over-TLS, mTLS, ACME
musl-allocator	no	Uses mimalloc as #[global_allocator] (binary only; musl/Alpine)
i18n-full	no	Reserved: top-20 economic locales (no extra strings yet)
i18n-cjk	no	Reserved: zh-Hans / zh-Hant / ja / ko
i18n-rtl	no	Reserved: ar / he (RTL isolation)
i18n-europe	no	Reserved: additional European locales

Disable real SSH only for dependency diagnosis: --no-default-features. Documented feature gates use #[doc(cfg(...))] under the docsrs cfg. Default binary always embeds en + pt-BR only (Rules: no full top-20).

Entry point

The public run function is the entry point called by main.rs.

Safety

• docs.rs / rustdoc: when built with --cfg docsrs, this crate enables #![feature(doc_cfg)] so #[doc(cfg(...))] labels render on feature-gated items (migration doc_auto_cfg → doc_cfg). Consumers of this crate do not need nightly; only the docs.rs build uses the feature gate.
• unsafe: product code avoids unsafe on the happy path; remaining blocks (platform console / Unix permissions) are documented at the call site.

Modules

cli

CLI argument definitions via clap derive and dispatcher.

commands

Per-subcommand command layer (rules clap CAMADA 2).

concurrency

Bounded multi-host / tunnel fan-out (Semaphore + JoinSet). Bounded concurrency for multi-host SSH fan-out (Rules Rust — paralelismo).

constants

Named domain constants (XDG file names, env keys, network/timing defaults). Named domain constants (Rules Rust — proibição de hardcode).

domain

Domain newtypes (parse, don’t validate — G-TYPE / G-DOM 4-crates). Domain newtypes — parse, don’t validate (G-TYPE / G-DOM).

error

Canonical error module name per clap layout rules (error.rs). Canonical error module path (error.rs) required by clap project layout rules.

errors

Structured error types (thiserror) and sysexits-style exit codes. Structured error types for ssh-cli.

fs_perm

Unix secret file/dir permission helpers (G-AUD-24). Unix secret file/dir modes — single source (G-AUD-24 / no hardcode drift).

i18n

ssh-cli internationalization system (Rules Rust multi-idioma).

json_wire

Typed JSON wire DTOs for agent-facing stdout/stderr contracts.

locale

Cross-platform language detection and resolution (Rules Rust i18n).

masking

Masking of sensitive values (passwords, tokens) — agent-safe.

net

TCP dial (async DNS + Happy Eyeballs multi-address connect). TCP dial helpers (Rules Rust — rede).

output

Only module allowed to emit stdout for VPS CRUD.

paths

File path validation and normalization.

platform

Operating-system conditional abstractions.

retry

Explicit retry policy + full-jitter backoff (agent re-invoke; opt-in in-process). Explicit retry policy for ssh-cli (Rules Rust — retry / backoff).

scp

File transfer via SCP over SSH (one-shot).

secrets

At-rest encryption of secrets in config.toml (GAP-009 / R-SECRETS-DEFAULT).

sftp

SFTP subsystem operations over SSH (upload/download/ls/mkdir/rm/stat/rename).

signals

Operating system signal handling for one-shot graceful shutdown.

ssh

SSH engine via russh 0.62.x.

telemetry

Process-local tracing subscriber (binary path only; libraries only emit). Process-local tracing setup for the ssh-cli binary path.

terminal

Colored output configuration and interactive terminal detection.

tls

rustls TLS stack (SSH-over-TLS, mTLS, ACME) — feature tls (default). Product TLS via rustls (aws_lc_rs only): SSH-over-TLS, mTLS, ACME.

tunnel

SSH tunnel (local port-forward) with mandatory deadline (bounded one-shot).

validation

Shared parse→validate pipeline for external config/import (G-SERDE-07). Shared validation pipeline for external input (G-SERDE-07).

vps

VPS record CRUD and persistence (XDG + atomic TOML + flock).

Functions

resolve_exit_code

Maps a run / run_with_args result to a sysexits-aligned exit code.

run

Runs ssh-cli from the command-line arguments.

run_with_args

Executes phases 4–5 with pre-parsed arguments (G-IO-11 library entry).