Documentation — ghost.

01 / GETTING STARTED

Installation

Ghost is a Linux companion CLI, designed primarily for CachyOS and other Arch-based distributions. It requires Python 3.10 or newer.

Requirements

Linux
Python 3.10 or newer
Git
pip

Some system reports use optional tools such as lspci, smartctl, systemctl and pacman.

Clone the repository

git clone https://github.com/blawyxd/ghost.git
cd ghost

Create a virtual environment

python -m venv .venv

Bash / Zsh:

source .venv/bin/activate

Fish:

source .venv/bin/activate.fish

Install Ghost

python -m pip install -e .

The editable install makes the ghost command available inside the active virtual environment while keeping it linked to your local source files.

02 / FIRST RUN

Getting started

Run Ghost without arguments to open its home screen.

ghost

Display the available commands:

ghost --help
ghost help

Every command also has its own help output:

ghost COMMAND --help

For example:

ghost hardware --help
ghost exercise --help
ghost serve --help

03 / SYSTEM

System diagnostics

These commands inspect your system and report information. They do not change system settings.

ghost doctor

Run a general system health check and identify common problems.

ghost hardware

Display detailed hardware information, including available CPU, GPU, memory and storage details.

ghost processes

View running processes and their resource usage.

ghost services

Inspect systemd services and their current states.

ghost network

Inspect network interfaces and connectivity information.

ghost ports

Display listening network ports.

ghost logs

Display recent system journal entries.

ghost updates

Check for available package updates using pacman. This does not install updates and is intended for Arch-based distributions.

04 / STORAGE

Storage and maintenance

Inspect disk usage and identify files or dependencies that may need attention.

ghost disk

Show filesystem capacity, used space, available space and usage percentages.

ghost large

Search your home directory for large files. The scan is limited to avoid an unbounded search. It does not delete anything.

ghost cache

Inspect the size and usage of your user cache.

ghost temp

Inspect temporary storage without deleting anything.

ghost orphans

Identify unneeded pacman dependencies. Ghost reports them but does not remove them.

ghost clean

Preview the contents and estimated size of your user cache, then ask for confirmation before removing entries. Applications may need to rebuild their caches.

05 / BACKUPS

Backups and security

ghost backup

Create a local archive of configuration files from ~/.config.

ghost backups

List locally stored configuration backups.

ghost restore-backup ARCHIVE_NAME

Restore missing configuration files from a selected archive. Ghost previews the changes and does not overwrite files that already exist.

ghost security

Run basic security checks and report potential issues.

Configuration backups can contain private settings, credentials or tokens. Keep them somewhere secure.

06 / DEVELOPMENT

Developer tools

Ghost includes utilities for inspecting and working with software projects.

ghost dev

Detect installed development tools.

ghost git [ACTION]

Inspect a Git repository. Supported actions include status, diff, log, branches and remotes. The default action is status.

ghost git
ghost git diff
ghost git branches

ghost project [DIRECTORY]

Inspect a project, detect its type, find its virtual environment and examine its directory structure.

ghost project-deps [DIRECTORY]

List dependencies declared by a Python project.

ghost env

Inspect the active Python environment.

ghost deps

List installed Python dependencies.

ghost vars

Check whether selected environment variables are present without displaying their values.

ghost install-deps [DIRECTORY]

Review the dependencies declared by a detected project and ask for confirmation before installing them.

ghost test [DIRECTORY]

Detect and run a project's test suite.

ghost build [DIRECTORY]

Build supported Python, Node.js or Rust projects.

ghost serve [DIRECTORY]

Start a supported static, Django or npm development server in the foreground. Options include --host, --port and --script.

ghost serve
ghost serve --host 127.0.0.1 --port 8000

Project tests, builds and development servers execute project tools or code. Only run them in projects you trust.

07 / LEARN

Python learning

Ghost includes a structured Python course with 24 lessons, progressing from programming fundamentals to more advanced application design.

Course topics

Beginner: variables, values, operators, input, conditions, loops and functions.
Intermediate: collections, strings, exceptions, files, modules, classes, generators, type hints, packages, APIs and testing.
Advanced: decorators, context managers, architecture, design patterns, optimisation and building applications.

Lessons contain explanations, runnable examples, walkthroughs, common mistakes, recaps and links to related exercises.

Browse the course

ghost learn
ghost learn LESSON_ID

You can select a lesson by its number or ID. Use next to continue from the next incomplete lesson.

The current course teaches Python. Other programming languages are not currently supported by the curriculum.

08 / PRACTICE

Exercises and hints

Exercises let you apply what you learn. Each exercise includes instructions, starter code, automated test cases, progressive hints and a solution.

Browse exercises

ghost exercises

Open an exercise

ghost exercise EXERCISE_ID

Submit a source file

ghost exercise EXERCISE_ID --file answer.py

Get a hint

ghost exercise EXERCISE_ID --hint 1

View the solution

ghost exercise EXERCISE_ID --solution

Exercises use different test modes: function-based submissions, complete scripts and HTTP exercises with mocked responses. HTTP exercises do not contact a live API.

Important: submitted code runs in a separate timed Python process and temporary working directory. This is not a security sandbox. It can still access your files, network and other system resources. Only run code you trust.

09 / BUILD

Learning projects

Ghost includes eight progressive Python projects that turn course concepts into larger pieces of software.

Browse projects

ghost projects

Open a project

ghost projects PROJECT_ID

Complete a milestone

ghost projects PROJECT_ID --complete-milestone 1

Milestones must be completed in order. You cannot skip ahead.

Review a project directory

ghost projects PROJECT_ID --review ./my-project

The project reviewer performs read-only structural checks. It can check for Python source files, tests, syntax errors and certain project files. It does not execute your project, run its tests or prove that the application works correctly. Review the acceptance criteria and run your own tests as well.

10 / PROGRESSION

Game Mode

Learning progression is optional. You can use the entire course without enabling gamification.

Enable Game Mode

ghost learning on

Disable Game Mode

ghost learning off

Check its status

ghost learning status

When enabled, you can earn XP, gain levels, build streaks and unlock achievements. XP is earned through learning activities such as completing lessons, exercises and project milestones.

Disabling Game Mode does not delete your saved progress. Your lessons, exercises and projects remain usable without it.

View your progress

ghost progress

Other learning references

ghost glossary
ghost cheatsheet

Use the glossary for programming terminology and the cheatsheet for a quick Python reference.

11 / SAFETY

Safety and permissions

Ghost is designed to make system inspection straightforward without silently changing your machine.

System reports are read-only.
Cache cleanup previews the operation and asks for confirmation.
Configuration restoration previews changes and skips existing files.
Dependency installation requires confirmation.
Ghost does not install system packages.
Project commands and exercise submissions may execute code.

Some reports depend on optional system tools or permissions. Ghost reports when a tool or permission is unavailable rather than assuming it can access everything.

Never treat the exercise runner as a sandbox. Do not submit untrusted code.

12 / OTHER

Additional commands

ghost vault

Display saved useful Linux commands. They are shown as text and are not executed automatically.

ghost help

Display the command overview.

ghost ship is a maintainer-only publishing command. It is not part of the normal user workflow.

13 / CONTRIBUTING

Running tests

From the repository root, activate your virtual environment and run:

python -m unittest discover -s tests -v
python -m compileall -q main.py ghost tests

These commands run the Python test suite and check the source files for compilation errors.

Documentation.