Skip to content

Installation

Null Terminal is cross-platform and can be installed on Linux, macOS, and Windows. Choose the method that best fits your workflow.

System Requirements

Null Terminal requires Python 3.10 or higher. We recommend using the latest stable Python version for the best experience.

Quick Start

The fastest way to get up and running is using pipx.

pipx install null-terminal
null

Installation Methods

pipx is the recommended tool for installing Python applications. It creates an isolated environment for each application, preventing dependency conflicts.

  1. Install pipx (if not already installed): 
    python3 -m pip install --user pipx
python3 -m pipx ensurepath
  2. Install Null Terminal: 
    pipx install null-terminal
  3. Launch: Type null in your terminal.

Automatic Updates

To update Null Terminal to the latest version, simply run: 

pipx upgrade null-terminal

Null Terminal is available as a Docker image, perfect for isolated environments or trying it out without local installation.

  1. Run the container: 
    docker run -it --rm \
  -v ~/.null:/root/.null \
  ghcr.io/starhound/null-terminal:latest

Persistence

Always mount the ~/.null volume as shown above to persist your configuration, API keys, and session history. Without this, all data will be lost when the container exits.

  1. Custom Build (Optional): If you want to build the image locally: 
    git clone https://github.com/starhound/null.git
cd null
docker build -t null-terminal .
docker run -it --rm -v ~/.null:/root/.null null-terminal

Windows users have several options, from native installers to standalone binaries.

EXE Installer

  1. Download the latest NullTerminal-Setup.exe from the Releases page.
  2. Run the installer and follow the instructions.
  3. Open PowerShell or Command Prompt and type null.

Portable Version

  1. Download NullTerminal-Windows.zip from the Releases page.
  2. Extract it to your preferred location.
  3. Run null.exe directly.

PATH Refresh

If the null command is not recognized after installation, try restarting your terminal session to refresh the environment variables.

Installing from source is best for developers or those who want the latest features before they hit a stable release.

  1. Clone the repository: 
    git clone https://github.com/starhound/null.git
cd null
  2. Install dependencies: We recommend using uv for lightning-fast environment management. 
    pip install uv
uv sync
  3. Run: 
    uv run main.py

Post-Installation

Once installed, follow these steps to complete your setup:

  1. Configure AI Providers: Open the settings with F3 or type /settings.
  2. Select a Model: Use F2 or type /model to choose your preferred AI model.
  3. Toggle AI Mode: Press Ctrl+Space to switch between standard CLI and AI-assisted modes.

Troubleshooting

"Command not found: null"

  • Linux/macOS: Ensure ~/.local/bin is in your $PATH. If you used pipx, run pipx ensurepath.
  • Windows: Restart your terminal or computer to ensure the PATH changes take effect.

Terminal Compatibility

Null Terminal works best in modern terminals that support: * TrueColor (24-bit): For accurate theme rendering. * Unicode/Emoji: For icons and UI elements. * Mouse Interaction: For scrolling and clicking UI components.

Recommended terminals: WezTerm, Kitty, Alacritty, or Windows Terminal.