Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/AhmedSaadi0/NibrasShell/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through everything you need to do after installing NibrasShell to get a fully working, personalized shell. By the end you will have your identity and location configured, an AI provider connected, a theme selected, and a solid understanding of how to discover the shell’s shortcuts and features. If you have not installed NibrasShell yet, start with the installation guide.
The easiest way to configure NibrasShell is through the built-in Settings App (Control Hub). It provides a visual interface for every option covered in this guide, so you do not need to edit ~/.nibrasshell.json by hand unless you prefer to.
1

Install NibrasShell

If you have not already installed NibrasShell, clone the repository and run the automated installer:
git clone --depth 1 https://github.com/AhmedSaadi0/NibrasShell.git
cd NibrasShell/nibras_installer
python main.py
Select 1 to install dependencies, then 2 to install NibrasShell. The installer will guide you through creating ~/.nibrasshell.json at the end. See the installation guide for full details and distro-specific notes.
2

Set up your user config

NibrasShell reads your personal settings from ~/.nibrasshell.json. The installer creates this file for you, but you can edit it at any time. The most important fields for initial setup are your name, location, and wallpaper paths.Here is the core structure of ~/.nibrasshell.json:
{
  "username": "Ahmed",
  "subtitle": "Developer",
  "profilePicture": "/home/ahmed/Pictures/profile.png",
  "networkMonitor": "wlp0s20f3",
  "networkInterval": 400,
  "weatherLocation": "Sana'a",
  "city": "Sana'a",
  "country": "Yemen",
  "usePrayerTimes": false,
  "aiProvider": "gemini",
  "aiApiKey": "YOUR_API_KEY_HERE",
  "aiPreferredLanguage": "English"
}
Set username to your name — it appears in the welcome message on the shell. Set city and country so the weather widget can show accurate forecasts. Set networkMonitor to the name of your primary network interface (run ip link to find it).
To regenerate or update ~/.nibrasshell.json interactively, run the installer again and choose option 5 (Create/Edit User Config).
3

Connect an AI provider

NibrasShell’s AI daemon and Smart Capsule features require an API key from a supported AI provider. Set aiProvider and aiApiKey in ~/.nibrasshell.json:
{
  "aiProvider": "gemini",
  "aiApiKey": "your-gemini-api-key",
  "aiPreferredLanguage": "English"
}
The AI system uses separate keys for different features. You can optionally set dedicated keys for music and weather AI analytics:
{
  "aiApiKey": "your-main-key",
  "musicAiApiKey": "your-music-key",
  "weatherAiApiKey": "your-weather-key",
  "systemAiApiKey": "your-system-key"
}
Set aiPreferredLanguage to the language you want AI responses delivered in — for example "English", "Arabic", or "Czech".
Keep your API keys out of version control. Never commit ~/.nibrasshell.json to a public repository.
4

Pick a theme

NibrasShell supports Material 3 dynamic color generation from your wallpaper, as well as several hand-crafted built-in themes. Open the Settings App → Appearance to switch themes visually and set your wallpaper folder.NibrasShell supports static images, GIFs, and video wallpapers. Set your wallpaper from the Settings App → Wallpapers section — select a local image, browse downloaded wallpapers, or search Wallhaven directly.Built-in themes (selectable from the Settings App) include:
  • Material / Material You — Dynamic palette generated from your wallpaper
  • Dracula — Purple-toned dark theme
  • Catppuccin — Soft pastel palette
  • Nord — Cool Arctic tones
  • Gruvbox — Warm retro palette
  • Tokyo Night — Deep blue-purple cityscape palette
See Themes and color schemes for the full list of 8 preset themes and customization options.
5

Explore shortcuts with the cheatsheet

Once your shell is running, open the Cheatsheet overlay to see all available keyboard shortcuts and discover every feature of NibrasShell. The cheatsheet is built into the shell — you do not need to look anything up externally.
You can find the cheatsheet shortcut by looking at the top bar or left menu. All shortcuts available in NibrasShell are listed inside the Cheatsheet window.

​
Next steps

UI Components

Learn how the Top Bar, Smart Capsule, Left Menu, and Desktop components work.

Theming

Go deeper into Material 3 color generation and theme customization.

AI & Services

Understand how the AI daemon monitors your system and when it fires alerts.

Configuration

See the full reference for every field in ~/.nibrasshell.json.

Build docs developers (and LLMs) love

Get started for freeTalk to us