Make sense of
your terminal.
HackersGhost AI CLI brings a little less guessing and a lot more understanding. Get clear explanations of Linux commands, logs and errors from an AI assistant built for your terminal.
Python 3.11+ · Your own OpenAI API key · API usage billed separately
hg> What does ss -tuln do?
It shows listening TCP and UDP sockets, with numeric addresses and port numbers.
hg> And if I add -p?
You also see associated process information, where your permissions allow it.
hg>
Illustrative conversation. AI responses may vary.Decode the command.
Ask what a command does, compare flags and follow up without repeating your question.
Find meaning in the logs.
Attach a sanitized text file, confirm the upload and get explanations with suggested checks.
Choose how you update.
Install signed releases manually or enable automatic updates at startup. Keep a previous version for rollback.
Get started in 3 steps.
Download, install, ask. The full commands are in the guide below.
Grab the Linux installer.
Download the ZIP and extract it on Linux. No GitHub account is needed.
Give it a home.
Open a terminal in the extracted folder, run python3 install.py and confirm with INSTALL.
Bring your own key.
Start the CLI with your chosen model, enter your OpenAI API key at the hidden prompt and ask your first question.
Beta, with a clear test status. AI chat, file analysis, signed updates, automatic update installation and rollback have been tested on Parrot OS. Package verification and 22 automated tests pass. A complete first installation on a clean system remains untested; Kali Linux is also untested.
The installation and usage guide
Everything you need to install, ask questions, analyze a file and manage updates.
What you can do
Ask one question or start an interactive conversation. Follow-up questions use the current session’s context. Type /clear to discard local conversation history, or /exit to leave. The CLI can analyze one explicitly selected UTF-8 text file after you type SEND. Files and questions are limited to 64 KiB combined.
There is no automatic shell-command execution, browsing or persistent conversation memory. The updater can run verified application code to test and activate a new release. AI explanations can still be wrong: review suggested commands before using them.
Before you install
You need Linux, Python 3.11 or newer, Python virtual-environment support and an internet connection. The installer downloads cryptography dependencies from PyPI. You also need an OpenAI API account, an API key and access to a supported model. See the official OpenAI API quickstart for API setup guidance. API usage is billed separately from ChatGPT subscriptions.
Run the installer as your normal user. Do not use sudo. If HackersGhost AI is already installed, use its update command instead of reinstalling.
Install HackersGhost AI CLI on Linux
Download the installer ZIP above, extract it and open a terminal inside the extracted hackersghost-ai-0.2.5-linux-installer folder. Run:
python3 install.pyType INSTALL when prompted. The installer verifies the publisher-signed application package, creates a dedicated Python environment and adds a launcher at ~/.local/bin/hackersghost-ai. Its runtime lives under ~/.local/share/hackersghost-ai/runtime. Keep that runtime directory; you may remove the downloaded installer after installation succeeds.
On Debian-based systems, if Python reports that virtual-environment support is unavailable, install your distribution’s python3-venv package, then try again.
Optional API key storage in your Linux keyring
HackersGhost AI CLI can remember your API key through your desktop Secret Service keyring. This is optional: the hidden prompt remains available, and the CLI never falls back to a plaintext key file. On Parrot or Kali, install the helper:
sudo apt update
sudo apt install libsecret-toolsRun the following as your normal desktop user, without sudo. Enter your key only at the hidden prompt; your desktop may ask you to unlock or create a keyring. Use a password-protected keyring.
~/.local/bin/hackersghost-ai api-key save
~/.local/bin/hackersghost-ai api-key statusSubsequent AI sessions retrieve the saved key automatically while the keyring is accessible. An existing OPENAI_API_KEY environment variable takes precedence. Status never prints the key. To remove the saved entry:
~/.local/bin/hackersghost-ai api-key deleteDeletion removes the local keyring entry; it does not revoke the key at OpenAI or unset an environment variable. If the keyring is missing, locked or unavailable, ordinary interactive use falls back to hidden input. Installing libsecret-tools alone does not create a Secret Service keyring: you also need a compatible desktop service, such as GNOME Keyring or a compatible KWallet setup. SSH sessions and a different user started through sudo may not have access to your desktop keyring. Do not save keys in shell history, screenshots or support reports.
Ask your first question
Start with a model available to your API account. The following model was used in our Parrot tests:
~/.local/bin/hackersghost-ai --model gpt-4.1-miniEnter your own API key at the hidden prompt. No characters appear while you paste it, and the CLI does not save the key. At hg>, type a question such as Explain what ss -tuln does on Linux. Model access depends on your API account; you can choose a different model with --model.
Analyze a text file
~/.local/bin/hackersghost-ai --model gpt-4.1-mini --file ./sanitized-log.txt 'Explain these errors and suggest checks.'Review the file and remove passwords, tokens and personal information before sending it. The CLI has no automatic secret redaction. Type uppercase SEND to confirm; any other response cancels the request. Binary files are not supported.
HackersGhost AI CLI updates: choose your preference
Automatic installation is off by default. Check for a newer version or install one manually:
~/.local/bin/hackersghost-ai check-update
~/.local/bin/hackersghost-ai updateTo enable automatic installation, run:
~/.local/bin/hackersghost-ai auto-update onThe CLI then checks at normal startup, at most once per day. It verifies a newer release, installs it and restarts before asking for your API key. There is no background service: updates happen when you launch the app. Help, version and update-management commands do not trigger the daily startup check.
~/.local/bin/hackersghost-ai auto-update status
~/.local/bin/hackersghost-ai auto-update offOptional success statistics: your choice
Success reports are off by default. To opt in, run the command below, read the disclosure and type ENABLE. Enabling reports your currently installed version; subsequent successful updates send a best-effort report. Only the event type and CLI version go to hackersghost.com: never your API key, questions, logs or a persistent client identifier.
~/.local/bin/hackersghost-ai statistics on
~/.local/bin/hackersghost-ai statistics status
~/.local/bin/hackersghost-ai statistics offThe web server may record your IP address in normal access logs; the receiver temporarily uses a salted network hash for abuse limiting. Reports are optional counts, not unique people. Re-enabling can count your current installation again. Failed reports are not queued or retried and never prevent an update. Disabling stops future reports, but cannot subtract past aggregate counts. Updates from versions before 0.2.5 do not send upgrade reports. Separately, website download clicks may be measured by Google Analytics according to your website consent preferences; a click does not prove a completed installation.
Restore the previous version
~/.local/bin/hackersghost-ai rollbackRollback switches to the retained previous release and disables automatic installation. It is available after a successful update. A failed download, invalid signature or failed startup test leaves the current version selected; startup tests do not detect every possible runtime bug.
Where HackersGhost AI CLI sends your data
Questions, confirmed file contents and the current conversation context are sent to OpenAI over HTTPS. Conversation history stays in process memory locally and is resent for follow-up questions. Requests use store: false; this is not a guarantee of zero provider-side retention. API keys and signing secrets are not included in the download.
Update requests go to HackersGhost’s public download location. Releases use an Ed25519-signed manifest and a SHA-256 package checksum. The initial installer must be obtained from this official website; its bootstrap relies on that trusted first download.
Troubleshooting and beta feedback
An invalid-key message usually means the API key was rejected. A rate-limit or quota message may indicate request limits or API billing quota. An expired-manifest message means you need a freshly published download: signed manifests currently expire after 30 days. Do not bypass signature checks.
Report problems through the HackersGhost contact page. Include your Linux distribution, Python version, CLI version and sanitized error message. Never include API keys, GitHub tokens or private signing keys.