CLI

npm install -g @fluxta/cli

The CLI creates plugin and iconset projects, checks them, and talks to a running Fluxta.

Two things it deliberately does not do:

• It never builds. Building belongs to the project — pnpm build and pnpm dev. There is no fluxta build, dev, or run. Commands that need build output use what is already there.
• It never launches Fluxta. Anything that touches the app needs it already running.

Run fluxta help or fluxta help <command> for the same information in your terminal.

Starting a project

fluxta create

Scaffolds a new plugin — or iconset — project into a new directory named after it. A plugin also gets its dependencies installed.

fluxta create
# What do you want to create? Plugin / Iconset
# Name:
# Author (Jane Doe):
# Description:
# Categories:
# Platforms:

Run in a terminal, it prompts for the plugin's name and Package Metadata (author defaults to git config user.name, editable). Categories and platforms are checkboxes: pick one to three categories, and at least one platform. Of the platforms, only the system you are running on starts ticked — the one you can certainly test. An iconset is asked for neither. Run non-interactively — CI, a script, no attached terminal — the matching flags are required instead:

fluxta create --name my-plugin --author "Jane Doe" --description "..." \
  --categories streaming,audio --platforms windows,macos
fluxta create --type iconset --name my-icons --author "Jane Doe" --description "..."

--categories and --platforms are the exception to "required": without them, the manifest gets an empty list and fluxta publish reports it. When given, they are checked by the same rules publishing applies. An iconset refuses both.

It validates the name before writing anything, refuses a directory that is not empty, initializes a git repository, and — for a plugin — runs pnpm install. If the install fails, the generated files stay put so it can be retried. An iconset has no dependencies, so nothing is installed.

repository and maintainers are not asked for here — fluxta publish fills them in from the package's own git remote and the GitHub account you authenticate as.

See Your first plugin for what it generates.

Checking your work

fluxta validate

Checks the project and its build output against everything publishing requires, including the metadata fields and any leftover TODO placeholders.

pnpm build
fluxta validate

It does not build. Run pnpm build first, or the check runs against stale output. This is the command for your own CI: it talks to nothing and needs no credentials.

In an iconset, it checks the manifest, the licence file, and every icon — see Iconsets for the rules.

fluxta package

Builds a distributable zip from existing build output, after running the same full validation as validate.

pnpm build
fluxta package --out my-plugin-1.0.0.zip

The archive is deterministic and contains a single top-level folder named after the plugin — the shape a user can drop straight into their plugins directory. An iconset is zipped straight from its folder, since it has no build.

fluxta publish

Validates everything, then opens a pull request adding the plugin to the public plugin repository. Merging that pull request is what publishes it.

pnpm build
fluxta publish

The first run authenticates with GitHub through a browser prompt; later runs reuse it. It does not build, and it does not release anything by itself — see Publishing.

An iconset is published the same way and lands in the repository's iconsets/ folder instead of plugins/. Plugins and iconsets share one set of names, so a name another package already has is refused before anything is pushed.

Talking to a running Fluxta

All of these need Fluxta open. They address a plugin by its id, defaulting to the name in the manifest of the current directory. An iconset has no process, so start, stop, and restart refuse one.

fluxta link

Points Fluxta at build output, so the app runs local code instead of an installed copy of the same plugin.

pnpm build
fluxta link
fluxta link --status # what is linked right now, without changing it

It validates the folder before registering it, and it does not build.

fluxta unlink

Removes the link, stops the linked plugin, and restores the installed copy if there is one. If there is not, it says so.

fluxta unlink

fluxta restart

Refreshes the link from current build output and restarts the plugin. This is what the dev loop calls after every successful build; it is rarely typed by hand.

fluxta restart
fluxta restart my-plugin

fluxta start

Starts a stopped plugin's process without touching its link.

fluxta start my-plugin

fluxta stop

Stops a running plugin's process without touching its link.

fluxta stop my-plugin

Exit codes

0 on success, 1 on failure. With --warnings-as-errors, warnings count as failure too — which is what automation usually wants, and usually not what you want while writing the plugin.