Shell

The Shell namespace provides access to the in-game terminal. Execute commands, query system info, and inject custom command response data.

Required permission: shell

Import

import { Shell } from "@hotbunny/hackhub-content-sdk";

Methods

Shell.exec(command)

Execute a terminal command programmatically as if the player typed it.

Returns: Promise<void>

Throws: Error if the terminal is not open/available.

await Shell.exec("nmap 192.168.1.1");
await Shell.exec("ssh [email protected]");

WARNING

The terminal must be open for this to work. If no terminal instance is available, an error will be thrown.

Shell.getUsername()

Get the player's OS username.

Returns: string

Shell.getHostname()

Get the computer's hostname.

Returns: string

Shell.getPlayerIp()

Get the player's IP address.

Returns: string

Shell.getInstalledPackages()

Get a list of all installed terminal packages.

Returns: string[]

const packages = Shell.getInstalledPackages();
// ["nmap", "ssh", "whois", "python3", ...]

Shell.isPackageInstalled(pkg)

Check if a specific package is installed.

Returns: boolean

if (Shell.isPackageInstalled("nmap")) {
    console.log("Player can scan networks");
}

Shell.addCommandData(command, input, data)

Add response data for a terminal command. When the player runs command input, the game uses this data to generate the response.

This is the primary way quests provide dynamic content to terminal commands like nmap, hydra, whois, etc.

Parameter	Type	Description
command	string	Command name (e.g. "nmap", "hydra", "whois")
input	typed per command	The argument the player provides (e.g. IP address, domain, { user, target })
data	typed per command	Response data (format depends on the command)

Typed built-ins

Built-in commands are fully typed — you get autocomplete and compile-time checks on both input and data. Any other command name (e.g. your own mod command) accepts arbitrary input/data, so custom commands keep working without a type entry.

Built-in command shapes

Command	input	data
nmap	string (IP)	NmapPort[] — { port, status, service, version?, destination? }
hydra	{ user, target }	{ credentials: { username, password } }
whois	string	{ ip?, domain?, contact?, email?, status? }
nslookup	string (host)	string (resolved IP)
mxlookup	string (host)	string (mail server IP)
ping	string (IP)	boolean (force host up/down)
lynx	string	{ socialMedia?, ips?, address?, additional?, contact? }
geoip	string (IP)	{ country, city, latitude, longitude }
ssh	{ host, key }	{ ip, status: "OPEN" | "CLOSE" }
ftp	{ host, username, password }	string | null
weechat	{ host, password }	boolean

NmapPort.status is one of "OPEN" | "CLOSE" | "FORWARDED" | "FILTERED".

// When player runs "nmap 10.0.0.1", they see these ports:
Shell.addCommandData("nmap", "10.0.0.1", [
    { port: 22, service: "ssh", status: "OPEN", version: "OpenSSH 8.9" },
    { port: 80, service: "http", status: "OPEN", version: "nginx 1.18" },
]);

// When player brute-forces with "hydra ... -l admin 10.0.0.1":
Shell.addCommandData("hydra", { user: "admin", target: "10.0.0.1" }, {
    credentials: { username: "admin", password: "hunter2" },
});

// When player runs "whois example.com":
Shell.addCommandData("whois", "example.com", {
    domain: "example.com",
    contact: "John Doe",
    email: "[email protected]",
});

Shell.removeCommandData(command, input)

Remove previously added command data. Call this when a quest completes to clean up.

Shell.removeCommandData("nmap", "10.0.0.1");

Shell.getCommandData(command, input)

Get existing command data for a command+input pair. For built-in commands the return type is inferred from the command (e.g. Shell.getCommandData("nmap", ip) returns NmapPort[] | undefined).

Returns: the command's typed data (or unknown for custom commands), or undefined if none set