@fluxlay/cli

CLI for building, developing, and publishing Fluxlay wallpapers.

• Documentation: https://fluxlay.com/docs/developer/tutorials/getting-started
• CLI reference: https://fluxlay.com/docs/developer/reference/cli/commands
• Manifest reference: https://fluxlay.com/docs/developer/reference/cli/manifest
• Examples: https://github.com/fluxlay/examples

Installation

npm install -g @fluxlay/cli
# or
bun add -g @fluxlay/cli

Commands

fluxlay login

Authenticate with your Fluxlay account via device authorization. A browser window opens for sign-in and a confirmation user code is shown. Once approved, the session is stored locally.

fluxlay login

fluxlay logout

Remove the stored session.

fluxlay logout

fluxlay whoami

Display the currently authenticated user.

fluxlay whoami

fluxlay dev [dir]

Start a development server for live-previewing a wallpaper. The desktop app hot-reloads as you edit files.

fluxlay dev
fluxlay dev ./my-wallpaper

| Argument | Description | Default | | -------- | ----------------- | ----------------------- | | dir | Project directory | . (current directory) |

Behavior:

1. Validate fluxlay.yaml.
2. Find an available port starting from 3000.
3. Start the Vite dev server.
4. Write dev.json to the app data directory.
5. The desktop app renders the wallpaper with HMR.

fluxlay build [dir]

Build a wallpaper into an encrypted .fluxlay package.

fluxlay build
fluxlay build ./my-wallpaper -o output.fluxlay

| Argument / Option | Description | Default | | --------------------- | ----------------- | ------------------- | | dir | Project directory | . | | -o, --output <name> | Output filename | wallpaper.fluxlay |

Requires a logged-in session and a kind field in fluxlay.yaml. Behavior depends on kind:

• kind: web — runs the Vite build and packages dist/.
• kind: video / kind: image — packages the single media file specified by source (Vite build is skipped).

fluxlay publish [dir]

Build and publish a wallpaper to the Fluxlay store.

fluxlay publish
fluxlay publish ./my-wallpaper

| Argument | Description | Default | | -------- | ----------------- | ------- | | dir | Project directory | . |

Requires a logged-in session and completed onboarding. Publish behavior is determined by the kind field in fluxlay.yaml (there is no CLI flag override):

1. Validate fluxlay.yaml (kind is required).
2. Generate a content encryption key.
3. Register the version with the API.
4. Bundle according to kind:
   • web: package the Vite build output (dist/).
   • video / image: package the media file specified by source as media.<ext> (Vite build is skipped). HTML is generated dynamically by the desktop app at delivery time.
5. Encrypt and upload.
6. Notify the API on completion.

Project Structure

A Fluxlay wallpaper project requires a fluxlay.yaml manifest at the root:

schemaVersion: 1
name: My Wallpaper
slug: my-wallpaper
version: 0.1.0
kind: web
description: |
  A description of your wallpaper.

fluxlay.yaml fields

| Field | Required | Description | | --------------- | ------------------------------ | --------------------------------------------------------------- | | schemaVersion | ✓ | Manifest schema version (currently only 1) | | name | ✓ | Display name | | slug | ✓ | URL-safe unique identifier (lowercase letters, digits, hyphens) | | version | ✓ | Semantic version | | kind | ✓ | Bundle type: web / video / image | | source | when kind is video/image | Path to the media file to publish (relative to project root) | | description | | Short description shown in the store listing | | properties | | Custom property definitions (user-tweakable variables) | | shell | | Declared external shell commands | | network | | Allowed network origins |

For the full schema (including properties types and per-type fields), see the manifest reference. Sample projects are available at https://github.com/fluxlay/examples.

Video / image wallpaper example

schemaVersion: 1
name: My Video Wallpaper
slug: my-video-wp
version: 0.1.0
kind: video
source: ./background.mp4

Minimal package.json

{
  "name": "my-wallpaper",
  "private": true,
  "version": "0.1.0",
  "type": "module",
  "scripts": {
    "dev": "fluxlay dev",
    "build": "fluxlay build",
    "publish": "fluxlay publish"
  },
  "dependencies": {
    "@fluxlay/react": "latest",
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  },
  "devDependencies": {
    "@fluxlay/cli": "latest",
    "@fluxlay/vite": "latest"
  }
}