Command Line Interface (CLI) - Terminal User Interface (TUI)

What

The SadServers cli/tui is a program that facilitates running SadServers scenarios directly from the command line.

Note : currently only Pro+ users will be able to run scenarios from the cli/tui client.

Note : this tool is in beta at the moment (offered as-is, not supported).

Installation

Download the binary for your architecture, make it executable and then rename it for convenience, e.g:

• (Linux) mv sads_v0.1.0_linux_amd64 sads; chmod +x sads
• (Mac) mv sads_v0.1.0_darwin_arm64 sads; chmod +x sads
• (Windows) ren sads_v0.1.0_windows_amd64.exe sads.exe

Check with sads -h or sads -v that the binary works.

Mac users

When trying to run the executable you’ll get a message like "sads_v0.1.0_darwin_arm64" can’t be opened because Apple cannot check it for malicious software."

Go to System Settings -> Privacy & Security, scroll down to the Security section and find the text:

"sads_v0.1.0_darwin_arm64" was blocked from use because it is not from an identified developer , then click on the “Allow Anyway” button underneath it if you trust us. The first run after this a window will ask to confirm as well.

Usage

Running sads with no arguments launches the interactive TUI. All functionality is also available as direct subcommands.

sads [command]

Commands

Flags

• sads -h or sads --help: lists available commands and flags
• sads -v or sads --version: prints current version

Workflow

# 1. Authenticate
sads auth

# 2. Browse scenarios and spin one up
sads scenarios
sads up 5

# 3. Connect once the VM is ready
# (requires a public key uploaded in the dashboard and "sads config" to indicate the private one)
sads ssh

# 4. Verify your solution
sads check

# 5. Tear down the VM when done
sads down

Authentication

sads auth
# Opens a verification URL — complete login in your browser,
# then press Enter in the terminal.

Credentials are stored at:

• macOS: ~/Library/Application Support/sadservers/config.json
• Linux: ~/.config/sadservers/config.json

The SSH private key path is stored in the same file and survives logout.

Environment Variables

TUI

The TUI is split into two panes. The left Problem pane shows scenario details, API responses, and status messages. The right SSH pane is a virtual terminal connected to the active PTY process.

The bottom input bar changes prompt based on the current mode:

| Prompt | Mode | Available input | | auth> | Unauthenticated | login / auth | | ↩> | Auth pending | Press Enter to poll after completing browser login | | api> | Authenticated | scenarios, up <id>, show/cd/describe <id>, status, ssh, check, down, config [--path <path>], logout, help |

Keyboard shortcuts:

• Ctrl+Q — quit
• Ctrl+C — quit (when input focused) or kill active subprocess
• Tab / Shift+Tab — cycle difficulty groups in the scenarios list
• ↑ / ↓ / PgUp / PgDn — scroll scenarios list or problem pane
• Esc — return from scenario detail to the scenarios list