instantOS

ins ​

ins is the main command-line interface shipped by instantCLI. It bundles most user-facing instantOS tools into one binary, including settings, wallpaper management, diagnostics, updates, dotfiles, game-save sync, installer workflows, and several utility interfaces.

The larger ins subcommands have their own pages:

This page covers the remaining core commands.

Top-level commands ​

The main command groups are:

  • arch
  • dot
  • game
  • pass
  • resolvething
  • doctor
  • dev
  • launch
  • assist
  • menu
  • notify
  • clip
  • scratchpad
  • setup
  • settings
  • video
  • wallpaper
  • debug
  • completions
  • self-update
  • update
  • autostart
  • welcome

Settings ​

screenshot

ins settings opens the instantOS settings interface. It can also be used non-interactively to reopen a specific section, list all categories, or reapply settings that are not persistent across reboots.

bash
# Open the settings UI
ins settings

# Jump to one specific setting
ins settings --setting "appearance.animations"

# Jump to a category
ins settings --category appearance

# Start directly in search mode
ins settings --search

# Launch inside a GUI terminal window (uses kitty)
ins settings --gui

ins settings apply ​

ins settings apply re-applies non-persistent settings from the saved settings store, then tries to re-apply the configured wallpaper.

This is useful when:

  • you do not want to run ins autostart
  • your compositor or desktop session started after login
  • you want to restore settings after changing environments manually
bash
ins settings apply

ins settings list ​

Use list to inspect available categories and setting IDs from the terminal:

bash
# Show all categories and their settings
ins settings list

# Show category overview only
ins settings list --categories

# Filter to one category
ins settings list --filter appearance

Category IDs include:

  • install
  • appearance
  • display
  • network
  • bluetooth
  • input_devices
  • desktop
  • audio
  • apps
  • storage
  • printers
  • users
  • language
  • system

Wallpaper ​

Wallpaper management is built into ins and works across several environments.

bash
# Save a wallpaper path and apply it immediately
ins wallpaper set ~/Pictures/wallpaper.png

# Re-apply the saved wallpaper
ins wallpaper apply

# Fetch a random wallpaper
ins wallpaper random

# Fetch a random wallpaper without the instantOS logo overlay
ins wallpaper random --no-logo

# Generate a colored wallpaper
ins wallpaper colored --bg "#1a1a2e" --fg "#ffffff"

ins wallpaper can apply wallpapers on:

  • Sway
  • instantWM
  • i3
  • dwm
  • GNOME
  • Hyprland
  • KWin

Doctor ​

ins doctor runs health checks and optionally applies fixes.

bash
# Run the default doctor flow
ins doctor

# List checks
ins doctor list

# Run one check
ins doctor run <check-name>

# Fix one check
ins doctor fix <check-name>

# Fix everything fixable
ins doctor fix --all

# Choose fixes interactively
ins doctor fix --choose

The top-level ins doctor command also accepts --concurrency <N>.

Update ​

ins update runs the full instantOS update.

bash
ins update

See Updating instantOS for what it updates and the user-facing workflow.

Self-update ​

To update the ins binary itself without running the full system update flow:

bash
ins self-update

Autostart ​

ins autostart runs instantOS session startup tasks such as restoring settings and updating dotfiles.

bash
ins autostart

If you prefer not to use it, ins settings apply is the manual fallback for reapplying non-persistent settings.

Setup ​

ins setup configures instantOS integrations for supported window managers and compositors.

Supported targets:

  • ins setup sway
  • ins setup i3
  • ins setup instant-wm
  • ins setup niri

Scratchpad, Menu, Launch, and Pass helpers ​

These utility commands don't have their own page yet:

  • ins scratchpad
  • ins menu (script dialogs; see Menu API for scripts)
  • ins launch
  • ins pass (password-store picker)
  • ins welcome (opens itself in a terminal when launched graphically)

ins launch is the interactive application launcher. It ranks entries with a built-in launch frecency namespace and streams discovery results live:

bash
# Open the launcher
ins launch

# Also include every executable found in PATH
ins launch --include-path

# List applications instead of launching
ins launch --list

# Force a specific menu backend
ins launch -b instantmenu|tui|scratchpad

ins launch and ins menu are mostly used internally or from desktop integrations.