Skip to main content

​
Quick Start Guide

Get your Kanagawa dotfiles setup ready in just 5 minutes! This guide covers the essential steps to go from zero to a fully functional, beautiful desktop environment.
Prerequisites: Make sure you have Arch Linux installed and the required packages ready. See the Installation Guide for detailed requirements.

​
One-Command Setup

If you already have all prerequisites installed, you can set up everything with these commands: 
# Clone the repository
git clone https://github.com/nixer112/dotfiles.git ~/dotfiles
cd ~/dotfiles

# Run the installer
chmod +x install.sh
./install.sh

# Make scripts executable
chmod +x ~/.local/bin/*

# Reload your shell
exec zsh
That’s it! You’re now running Kanagawa dotfiles.

​
Step-by-Step Quick Setup

1

Clone & Install

Get the dotfiles and deploy them:
git clone https://github.com/nixer112/dotfiles.git ~/dotfiles
cd ~/dotfiles
The installer uses GNU Stow to create symlinks, so your original files in ~/dotfiles remain the source of truth.
2

Start Hyprland

Launch Hyprland to see your new environment:
Hyprland
Or reboot and select Hyprland from your display manager (GDM, SDDM, etc.).
On first launch, you may need to configure Powerlevel10k. Just follow the interactive wizard - it takes about 30 seconds.
3

Choose Your Theme

Open the theme selector with:
theme-selector
Or use the keyboard shortcut (check your Hyprland keybinds).Available themes:
  • Kanagawa 🌊 - The default, inspired by The Great Wave
  • Gruvbox 📦 - Warm, retro colors
  • Catppuccin ☕ - Pastel perfection
  • Everforest 🌲 - Comfortable green
Theme Selector
4

Explore Your New Setup

Try these essential keybindings (default Hyprland config):
ActionKeybind
Open TerminalSuper + Return
Launch ApplicationsSuper + D
Close WindowSuper + Q
Toggle FloatingSuper + V
Switch WorkspacesSuper + 1-9
Move Window to WorkspaceSuper + Shift + 1-9
ScreenshotSuper + Shift + S
Power MenuSuper + Shift + E
Super is usually the Windows key on most keyboards.

​
First Steps After Installation

​
1. Configure Your Terminal

Open Ghostty (press Super + Return) and you’ll see the Kanagawa theme already applied. Test some modern CLI tools: 
# Instead of cat, use bat for syntax highlighting
bat ~/.config/hypr/hyprland.conf

​
2. Switch Themes

The theme switcher updates everything instantly. Try it out: 
# Use the interactive selector
theme-selector

# Or switch directly from terminal
theme-switcher gruvbox
theme-switcher catppuccin
theme-switcher everforest
theme-switcher kanagawa  # Back to default
What gets updated:
  • ✓ Hyprland window borders and decorations
  • ✓ Waybar status bar colors
  • ✓ Wofi launcher appearance
  • ✓ Ghostty terminal colors
  • ✓ Neovim color scheme
  • ✓ VSCodium theme (if installed)
  • ✓ SwayNC notification styling
  • ✓ Wlogout power menu
  • ✓ Btop system monitor
  • ✓ Cava audio visualizer
  • ✓ Desktop wallpaper
The theme switcher is defined in ~/.local/bin/theme-switcher. Here’s how it works:
The theme-switcher script is a powerful tool that orchestrates theme changes across your entire system:
# Basic usage
theme-switcher <theme-name>

# Available themes
theme-switcher kanagawa    # 🌊 Default Kanagawa Wave
theme-switcher gruvbox     # 📦 Gruvbox Dark Hard
theme-switcher catppuccin  # ☕ Catppuccin Mocha
theme-switcher everforest  # 🌲 Everforest Night Hard
What it does:
  1. Updates CSS imports for Waybar, Wofi, SwayNC, and Wlogout
  2. Updates Hyprland color configuration
  3. Switches Ghostty color scheme
  4. Changes VSCodium color theme (if installed)
  5. Updates Neovim colorscheme via Lua bridge
  6. Links Btop and Cava theme files
  7. Prompts for wallpaper selection (if multiple available)
  8. Reloads all affected applications
  9. Sends a notification when complete
All theme files are stored in custom/ subdirectories:
  • ~/.config/hypr/colors/custom/
  • ~/.config/waybar/colors/custom/
  • ~/.config/wofi/colors/custom/
  • And so on…

​
3. Customize Waybar

Your status bar is powered by Waybar. It shows:
  • Active workspaces
  • Window title
  • System tray
  • Network status
  • Volume
  • CPU/Memory usage
  • Date and time
Click different modules to interact with them (e.g., click volume to mute/unmute).

​
4. Use the Application Launcher

Press Super + D to open Wofi, the application launcher. Start typing to search for apps: 
Super + D → type "brave" → Enter
Super + D → type "code" → Enter  (for VSCodium)
Super + D → type "theme" → Enter (for theme-selector)

​
5. Master Window Management

Hyprland is a tiling window manager. Windows automatically tile:
1

Open Multiple Windows

Press Super + Return multiple times to open several terminals.
2

Navigate Between Windows

Use Super + Arrow Keys or Super + H/J/K/L (Vim-style).
3

Move Windows

Hold Super + Shift and use arrow keys or H/J/K/L.
4

Resize Windows

Enter resize mode with Super + R, then use arrow keys.
5

Toggle Floating

Press Super + V to make a window float. Drag it with Super + Left Click.

​
6. Check System Info

View your beautiful system information: 
fastfetch
This displays your system specs with the Kanagawa color scheme.

​
7. Monitor System Resources

Launch the themed system monitor: 
btop
Press Q to quit.

​
8. Visualize Audio

Play some music and run: 
cava
You’ll see a beautiful audio visualizer in your terminal.

​
Essential Commands Cheat Sheet

File Operations

bat file.txt       # View with syntax
eza -la            # List files
z directory        # Jump to dir
fzf                # Find files

Theme Management

theme-selector     # GUI selector
theme-switcher kanagawa
theme-switcher gruvbox

System Info

fastfetch          # System info
btop               # Resource monitor
cava               # Audio visualizer

Notifications

notify-send "Title" "Message"
swaync-client -t   # Toggle center
swaync-client -d   # Dismiss all

​
Default Hyprland Keybindings

ActionKeybind
Close windowSuper + Q
Toggle floatingSuper + V
Toggle fullscreenSuper + F
Move focusSuper + Arrow Keys
Move windowSuper + Shift + Arrow Keys
Resize modeSuper + R
Toggle splitSuper + J
Check ~/.config/hypr/hyprland.conf for the complete list of keybindings and customize them to your preference.

​
What’s Next?

Now that you’re up and running, explore these guides:

Configuration

Learn how to customize every aspect of your setup

Themes Deep Dive

Create your own themes and customize colors

Hyprland Config

Master Hyprland configuration and animations

Shell & CLI Tools

Get the most out of Zsh and modern CLI utilities

​
Need Help?

Check the Installation Guide troubleshooting section for common issues.
Edit ~/.config/hypr/hyprland.conf and look for the bind= lines. Changes take effect immediately with Super + Shift + R.
Create new CSS/config files in the custom/ directories for each component. See the Themes Guide for details.
Wallpapers are stored in ~/.config/hypr/wallpapers/. Name them with the theme prefix (e.g., kanagawa-wave.png) for automatic selection.
Enjoy your new setup! The Kanagawa dotfiles are designed to be both beautiful and productive. Take your time to explore and make it your own.

Build docs developers (and LLMs) love

Get started for freeTalk to us