Ricekit

# List wallpapers for current/specific theme
ricekit wallpaper list [theme-name] --json

# Get current wallpaper
ricekit wallpaper current --json

# Apply a wallpaper
ricekit wallpaper apply <path> --json
ricekit wallpaper apply <path> --display 1 --json  # specific display

Application Management

# List detected applications
ricekit apps list --json
ricekit apps list --installed --json
ricekit apps list --configured --json

# Setup an app for theming (adds import to config)
ricekit apps setup <app> --json

# List apps that can be set up
ricekit apps supported --json

Plugin Management

# List available plugins
ricekit plugins list --json

# Get plugin status
ricekit plugins status <name> --json

# Install a plugin via Homebrew
ricekit plugins install <name> --json

Configuration

# Show all preferences
ricekit config show --json

# Get a specific preference
ricekit config get <key> --json

# Set a preference
ricekit config set <key> <value> --json

Status & Diagnostics

# Get overall status
ricekit status --json

# Diagnose issues
ricekit doctor --json

Creating Custom Themes

CRITICAL: ricekit theme create only generates theme.json and an empty wallpapers/ directory. Apps like SketchyBar need their own color files with specific formats.

Recommended: Use --base Flag

# Creates complete theme with all app-specific files
ricekit theme create my-theme --base tokyo-night --json

This copies ALL files from the base theme, so you only need to edit theme.json.

From Scratch: Required App-Specific Files

If creating without --base, you MUST manually create files for configured apps. Check which apps need files:

ricekit status --json  # see configuredApps list

SketchyBar requires sketchybar-colors.sh with this format (colors use 0xAARRGGBB - alpha + RGB):

#!/bin/bash
# SketchyBar color configuration - Generated by Ricekit

# Convert theme.json hex colors: #RRGGBB → 0xffRRGGBB (ff = full opacity)
export COLOR_BACKGROUND="0xff0d1520"
export COLOR_FOREGROUND="0xffb8c5d4"
export COLOR_ACCENT="0xffdaa54c"
export COLOR_SELECTION="0xff1e3a5f"
export COLOR_BORDER="0xff3a5a7a"

# Bar colors
export BAR_COLOR="0xff0d1520"
export BAR_BORDER_COLOR="0xff3a5a7a"

# Item colors
export ITEM_BG_COLOR="0xff1e3a5f"
export ICON_COLOR="0xffdaa54c"
export LABEL_COLOR="0xffb8c5d4"

# ANSI colors (from theme.json black/red/green/yellow/blue/magenta/cyan/white)
export COLOR_BLACK="0xff0a0e14"
export COLOR_RED="0xffc25a5a"
export COLOR_GREEN="0xff5a9e7a"
export COLOR_YELLOW="0xffdaa54c"
export COLOR_BLUE="0xff4a7ea8"
export COLOR_MAGENTA="0xff8a6a9e"
export COLOR_CYAN="0xff5a9eb8"
export COLOR_WHITE="0xff9eaab8"

# Bright ANSI colors
export COLOR_BRIGHT_BLACK="0xff2a3a4a"
export COLOR_BRIGHT_RED="0xffd87070"
export COLOR_BRIGHT_GREEN="0xff6ab88a"
export COLOR_BRIGHT_YELLOW="0xffe8b860"
export COLOR_BRIGHT_BLUE="0xff5a8eb8"
export COLOR_BRIGHT_MAGENTA="0xff9a7aae"
export COLOR_BRIGHT_CYAN="0xff6aaec8"
export COLOR_BRIGHT_WHITE="0xffc8d0dc"

# Transparent variants (80 = 50% alpha, cc = 80% alpha)
export COLOR_TRANSPARENT="0x800d1520"
export COLOR_SEMI_TRANSPARENT="0xcc0d1520"

After creating the file, reload SketchyBar: sketchybar --reload

Theme File Checklist (from-scratch creation)

For complete file format examples, see app-formats.md in this skill directory.

Usage Notes

• Always use --json flag for machine-readable output
• Theme names are lowercase with hyphens (e.g., tokyo-night, catppuccin-mocha)
• Check status before/after operations to verify changes
• Theme application automatically:
  • Updates the symlink at ~/Library/Application Support/Ricekit/current/theme
  • Notifies terminals (Kitty, WezTerm, SketchyBar, AeroSpace)
  • Applies the first wallpaper from the theme
  • Executes user hook scripts if configured

JSON Output Examples

Theme Operations

# List themes
$ ricekit theme list --json
{
  "themes": [
    {"name": "tokyo-night", "isCustom": false, "isLight": false, "isCurrent": true},
    {"name": "catppuccin-mocha", "isCustom": false, "isLight": false, "isCurrent": false}
  ]
}

# Get current theme
$ ricekit theme current --json
{"name": "tokyo-night", "isCustom": false, "isLight": false}

# Apply theme
$ ricekit theme apply tokyo-night --json
{
  "success": true,
  "previousTheme": "catppuccin-mocha",
  "currentTheme": "tokyo-night",
  "notifiedApps": ["sketchybar", "aerospace", "wallpaper"]
}

# Create theme (from scratch)
$ ricekit theme create my-theme --author "Me" --json
{"success": true, "name": "my-theme", "path": "/Users/.../custom-themes/my-theme"}

# Create theme (from existing)
$ ricekit theme create my-variant --base tokyo-night --json
{"success": true, "name": "my-variant", "path": "/Users/.../custom-themes/my-variant"}

# Duplicate theme
$ ricekit theme duplicate tokyo-night my-copy --json
{"success": true, "source": "tokyo-night", "name": "my-copy", "path": "/Users/.../custom-themes/my-copy"}

# Export theme
$ ricekit theme export tokyo-night --json
{"success": true, "theme": "tokyo-night", "path": "/Users/Downloads/tokyo-night.ricekit"}

# Import theme (from file or URL)
$ ricekit theme import ~/Downloads/theme.ricekit --json
{"success": true, "source": "~/Downloads/theme.ricekit", "name": "theme", "path": "/Users/.../custom-themes/theme"}

# Delete theme
$ ricekit theme delete my-theme --force --json
{"success": true, "deleted": "my-theme"}

Wallpaper Operations

# List wallpapers
$ ricekit wallpaper list --json
{"wallpapers": ["/path/to/wallpaper1.jpg", "/path/to/wallpaper2.png"]}

# Current wallpaper
$ ricekit wallpaper current --json
{"path": "/path/to/current-wallpaper.jpg"}

# Apply wallpaper
$ ricekit wallpaper apply /path/to/image.jpg --json
{"success": true, "path": "/path/to/image.jpg"}

Plugin Operations

# List plugins
$ ricekit plugins list --json
{
  "plugins": [
    {"name": "sketchybar", "isInstalled": true, "hasConfig": true},
    {"name": "aerospace", "isInstalled": true, "hasConfig": false}
  ]
}

# Plugin status
$ ricekit plugins status sketchybar --json
{"name": "sketchybar", "isInstalled": true, "hasConfig": true, "version": "2.21.0"}

# Install plugin
$ ricekit plugins install bat --json
{"success": true, "plugin": "bat"}

Status

$ ricekit status --json
{
  "currentTheme": "tokyo-night",
  "currentWallpaper": "/path/to/wallpaper.jpg",
  "installedApps": ["kitty", "cursor", "sketchybar"],
  "configuredApps": ["cursor", "sketchybar"],
  "themesCount": 16,
  "customThemesCount": 5
}

Error Handling

All errors return JSON with success: false and an error message:

# Theme not found
$ ricekit theme apply nonexistent --json
{"success": false, "error": "Theme \"nonexistent\" not found"}

# Cannot delete bundled theme
$ ricekit theme delete tokyo-night --force --json
{"success": false, "error": "Cannot delete bundled themes. Only custom themes can be deleted."}

# Cannot delete active theme
$ ricekit theme delete my-theme --force --json
{"success": false, "error": "Cannot delete the currently active theme. Switch to a different theme first."}

# Theme already exists
$ ricekit theme create existing-theme --json
{"success": false, "error": "Theme \"existing-theme\" already exists"}

# Invalid import file
$ ricekit theme import /bad/path.zip --json
{"success": false, "error": "File not found: /bad/path.zip"}

# Unknown plugin
$ ricekit plugins status unknown --json
{"success": false, "error": "Unknown plugin: unknown. Available: sketchybar, aerospace, starship, tmux, bat, delta"}

Tip: Check success field in JSON responses to determine if operation succeeded.

Exit Codes

• 0 - Success
• 1 - Runtime error (theme not found, permission denied, etc.)
• 2 - Invalid arguments/usage error

Available Themes

Common bundled themes: tokyo-night, catppuccin-mocha, catppuccin-latte, dracula, nord, gruvbox-dark, gruvbox-light, rose-pine, solarized-dark, solarized-light, one-dark

Supported Apps for Setup

alacritty, kitty, neovim, starship, wezterm, sketchybar, aerospace

Note: VS Code and Cursor are configured automatically when themes are applied.