fluxzero-cli

A command-line interface for Flux that helps you scaffold new projects, perform dependency upgrades, generate example code, and manage Flux Cloud resources.

Installation

Option 1: Package Managers (Recommended)

macOS or Linux with Homebrew:

brew install fluxzero-io/tap/fluxzero

Windows with WinGet:

winget install --exact --id Fluxzero.FluxzeroCLI

Package-manager installations receive normal brew upgrade and winget upgrade support.

Option 2: Automated Installation

Unix/Linux/macOS:

curl -sSL https://github.com/fluxzero-io/fluxzero-cli/releases/latest/download/install.sh | sh

Windows PowerShell:

iwr -useb https://github.com/fluxzero-io/fluxzero-cli/releases/latest/download/install.ps1 | iex

The installer will:

🎯 Auto-detect your platform and architecture
📦 Download the native package (no Java required; the Windows package includes its Visual C++ runtime)
⚡ Install to ~/.fluxzero/bin/fz
🔗 Add to PATH (optional - you'll be prompted)
✅ Verify installation with test commands

Option 3: Manual Native Download

Download the native package or executable for your platform from the releases page:

Linux x86_64: flux-linux-amd64
macOS Intel: flux-macos-amd64
macOS Apple Silicon: flux-macos-arm64
Windows x64: flux-windows-amd64.zip (extract all files into one directory)

The raw Windows .exe release asset is retained for compatibility and tooling. On a clean Windows installation, use WinGet, install.ps1, or the complete ZIP so the required runtime libraries are installed as well.

# Example for macOS Apple Silicon
curl -L -o fz https://github.com/fluxzero-io/fluxzero-cli/releases/latest/download/flux-macos-arm64
chmod +x fz
sudo mv fz /usr/local/bin/fz

Benefits of native downloads:

⚡ 5x faster startup (~0.27s vs ~1.36s for JAR)
📦 No Java installation required
🚀 Instant execution (no JVM warm-up time)
🌍 Cross-platform (Linux, macOS, Windows)

Option 4: Fluxzero Launchpad

Fluxzero also ships a macOS app, Fluxzero Launchpad, for generating projects locally and opening them in coding agents.

The signed and notarized macOS DMG is published with each release:

macOS Intel / Apple Silicon: Fluxzero-Launchpad.dmg

Windows and Linux Launchpad apps are planned, but are not published yet.

The app manages its own fz binary, checks for the latest CLI release on launch, writes a START_PROMPT.md containing the user's project brief, opens local coding agents with the generated project path and prompt, and keeps a local history of generated projects. Installed macOS builds register experimental Fluxzero URL schemes:

fluxzero://new?... opens Launchpad and pre-fills the generator.
fluxzero://open?path=...&prompt=...&agent=codex|claude|cursor|finder|none opens an existing project directly.
fluxzero://create?name=...&prompt=...&agent=codex|claude|cursor|finder|none creates a project with defaults and opens it directly.

Option 5: Manual JAR Installation (Legacy)

Download the latest fluxzero-cli.jar from the releases page
Run it with Java: java -jar fluxzero-cli.jar

Uninstallation

To remove FluxZero CLI from your system:

Unix/Linux/macOS:

curl -sSL https://github.com/fluxzero-io/fluxzero-cli/releases/latest/download/uninstall.sh | sh

Windows PowerShell:

iwr -useb https://github.com/fluxzero-io/fluxzero-cli/releases/latest/download/uninstall.ps1 | iex

The uninstaller will:

🔍 Detect installations (both current .fluxzero and legacy .flux directories)
📋 Show what will be removed with confirmation prompts
🗑️ Clean removal of binaries, directories, and PATH entries
✨ Complete cleanup leaves no traces

Add --force (Unix) or -Force (Windows) to skip confirmation prompts.

Project Versioning

The fluxzero-cli uses per-project versioning rather than global installation. Each project determines which version of the CLI it uses in the .flux/config.yaml file.

Usage

Once installed, you can use the CLI with either the short fz command or the equivalent fluxzero command:

# Initialize a new project (interactive template selection)
fz init my-project

# List available templates
fz templates list

# Start the local Fluxzero development environment
fz dev

# Expose the active environment to an MCP client over stdio
fz mcp

# Show version
fz version

# Upgrade CLI to latest version
fz upgrade

Local development

fz dev (or fluxzero dev) starts the newest compatible stable Fluxzero dev server from Fluxzero Packages. It supervises the local runtime, proxy, IDP, application reloads, background tests, optional frontend process, diagnostics, and MCP endpoint. Ports and credentials are allocated and discovered automatically through .fluxzero/dev/session.json.

The application main class is detected from compiled Java or Kotlin classes. Use --main-class only when a project contains multiple executable entrypoints and the intended one is ambiguous.

Fluxzero uses Java 25 for local development. When it is not available, interactive use offers to install it through Homebrew or WinGet. Agent-driven use reports the same requirement without opening a prompt, so the agent can ask for permission, perform the installation, and retry the original command.

fz dev

The default command starts the environment independently from the terminal and attaches a live semantic event view. Type q or quit and press Enter to open a menu, use the arrow keys to select an action, and press Enter to confirm. Type d or detach and press Enter to leave it running. Ctrl-C and an unexpected terminal disconnect stop the environment and all applications; background ownership is therefore always an explicit choice. When no Maven or Gradle project exists in the selected folder, interactive use offers to create a project in that folder or a new subfolder before startup. Common overrides include:

fz dev --fast-compiler
fz dev --app app
fz dev --app app --app audittrail
fz dev --environment dev
fz dev --port 4200
fz dev --idp external
fz dev --frontend-command "npm run dev"
fz dev --frontend-directory frontend --frontend-setup-command "npm install --prefer-offline --no-audit --no-fund"
fz dev --frontend-url http://localhost:5173
fz dev --no-tests

Attach to an existing project environment with fz dev attach; a bare fz dev does the same when the environment is already running. Events produced while detached are replayed from the last attach cursor before live events resume. Use background mode to start and return immediately after readiness without opening the attached view:

fz dev --background
fz dev list
fz dev list --json
fz dev attach
fz dev status
fz dev status --json
fz dev logs --follow
fz dev logs --follow --errors
fz dev logs --follow --app orders
fz dev restart
fz dev stop
fz dev stop --force
fz dev stop --all
fz dev config

fz dev list is global: run it from any directory to see every known Fluxzero development environment, including its project, applications, browser URL, and whether it is running, unresponsive, or stale. Project-specific control commands still use the current project or --project-dir. fz dev stop --all stops every registered environment and removes stale or legacy macOS launchd registrations.

fz dev restart performs a complete reinitialization: it stops the current environment and all managed processes, starts a fresh in-memory runtime from the current project configuration and any supplied start options, waits for readiness, and returns with the new environment running in the background. Startup commands run again against the new runtime. If no environment is active, restart starts one. For example, use fz dev restart --profile auditlog to restart with a named configuration profile.

logs --follow closes automatically when the environment stops, so it is safe to use as a long-running agent command. fz dev config prints the complete, valid .fluxzero/dev.yaml reference owned by the current compatible dev-server version. This gives humans and coding agents the exact supported field names, nesting, and frontend routing options without requiring a repository checkout or separate documentation lookup.

Only one dev session may be active per project. status, logs, stop, MCP discovery, and the next dev launch reconcile stale session state when the supervisor was killed unexpectedly. Because that also means the embedded test runtime lost its in-memory data, startup commands run again in the next session. Detaching keeps that state alive when a terminal closes, but also keeps the environment's processes and memory in use until fz dev stop or its configured idle timeout.

Start options:

Option	Meaning
`--app`	Start one module, main class, test app, or named app configuration; repeatable.
`--main-class`	Override main-class detection.
`--application-name`	Override the Fluxzero runtime application name.
`--profile`	Select a named development profile from `.fluxzero/dev.yaml`.
`--environment`	Set `ENVIRONMENT`; defaults to `local`.
`--namespace`	Set the Fluxzero namespace.
`--port`	Prefer a public browser/gateway port; dynamic by default.
`--idp managed	external`
`--no-idp`	Alias for `--idp external`.
`--frontend-command`	Start a managed frontend; use `{port}` for its private upstream port.
`--frontend-directory`	Working directory for managed frontend commands.
`--frontend-setup-command`	Run setup once before the managed frontend starts for this dev session.
`--frontend-url`	Proxy an externally managed frontend.
`--no-frontend`	Run a backend-only environment.
`--backend-path`	Route an extra public path directly to Fluxzero; repeatable.
`--fast-compiler`	Enable the Maven-correct fast Java path; Maven remains the fallback.
`--no-tests`	Disable background test selection and execution.
`--no-watch`	Disable source watching.
`--no-compile-on-start`	Start infrastructure without compiling applications.
`--app-arg`	Pass an application argument; repeatable.
`--startup-timeout-ms`	Override application/frontend readiness timeout.
`--graceful-shutdown-timeout-ms`	Override rolling app shutdown timeout.
`--debounce-ms`	Override source-change debounce.
`--idle-timeout`	Stop an inactive environment; defaults to `24h`, use `disabled` to opt out.
`--background`, `--detach`, `-d`	Start without an attached live view and return after startup succeeds or fails.

Shared project defaults belong in the tracked .fluxzero/dev.yaml; session state, logs, tokens, and build snapshots remain ignored under .fluxzero/dev/:

version: 1
environment: local
apps:
  - app
port: 4200
idp: external
frontend:
  command: "cd frontend &amp;&amp; npm start -- --host 127.0.0.1 --port {port}"
  backendPaths:
    - /api
lifecycle:
  idleTimeout: 24h
applicationConfig:
  rebound-encrypted:
    application: rebound
    applicationName: rebound
    env:
      FEATURE_MODE: local
    secrets:
      ENCRYPTION_KEY: "op://Fluxzero Cloud/flux_cloud_flux-encryption-key/local encryption-key"
commands:
  create-admin:
    type: com.example.CreateUser
    payload:
      name: Local Admin

For multiple complete local setups, define named profiles and select one explicitly or configure a default. Legacy top-level settings remain supported and cannot be mixed with profiles:

version: 1
defaultProfile: encrypted
profiles:
  encrypted:
    environment: local
    apps: [rebound-encrypted]
    frontend:
      directory: frontend
      command: "npm run dev -- --port {port}"
  reporting:
    environment: local
    apps: [rebound, reporting]

Run the non-default setup with fz dev --profile reporting. A single profile is selected automatically when no defaultProfile is configured.

apps may contain direct selectors or keys from applicationConfig. Secret values never belong in this file: only tracked op:// references are allowed, and op run injects their values directly into the selected child process. YAML commands execute in declaration order, followed by JSON commands under src/test/resources/fluxzero/dev/commands in filename order.

Command-line options override environment variables, which override dev.yaml; built-in defaults apply last. Unknown keys and unsupported config versions fail startup instead of being silently ignored.

fz mcp or fluxzero mcp is intended as the stdio command in an agent's MCP configuration. It discovers the active environment from the project directory and reads the dynamic endpoint and token without exposing either in agent configuration. Agent plugins can use --ensure-dev to start exactly one background environment when needed; an already active project session is reused:

fz mcp --ensure-dev --project-dir /path/to/project

For distributions containing DevServerBootstrapMain, the dev-server distribution owns coordinated start/reuse, preflight, readiness and process lifetime. The CLI and Maven/Gradle launchers select Java and the artifact, then delegate to that entrypoint. Older distributions continue through the existing launcher path. Both paths use .fluxzero/dev/ensure.lock to coordinate with older CLI releases; new distributions acquire that lock themselves, so the CLI must not hold it while delegating. The stdio start_dev tool uses the same bootstrap directly without invoking the CLI. A project pinned to an older distribution retains that distribution's tool surface; upgrade the dev-server distribution to use start_dev and standalone docs.

Once connected, the dev environment owns source watching, compilation, application replacement, configured startup commands, and background test execution. Coding agents should consume its structured MCP feedback rather than start duplicate builds, tests, applications, watchers, or unbounded log followers.

fz dev resolves the newest stable dev-server 1.x release for a new environment. The verified standalone JAR is cached under ~/.fluxzero/cache/dev-server, while .fluxzero/dev/launcher pins the concrete version used by the project. Attach, status, logs, stop, and MCP commands keep using that pinned version. Set FLUXZERO_DEV_SERVER_VERSION or pass --dev-server-version only when testing a specific local or prerelease build.

Project-local launchers provide the same environment without a globally installed CLI:

./mvnw fluxzero:dev
./mvnw fluxzero:dev -Dfluxzero.dev.background=true

./gradlew fluxzeroDev
./gradlew fluxzeroDev -Pfluxzero.dev.background=true

The Gradle plugin also owns fluxzeroDevMetadata, the compile/classpath contract consumed by the dev server. Apply the plugin to the root project so multi-project applications are discovered together.

CLI Commands & Parameters

`fz init` - Initialize a new project

Basic usage:

fz init [OPTIONS]

Options:

Parameter	Description	Example
`--template`	Name of the template to use	`--template flux-basic-kotlin`
`--template-path`	Path to custom template directory or ZIP file	`--template-path ./my-templates`
`--name`	Project name (1-50 chars: 0-9, a-z, -, _)	`--name my-app`
`--dir`	Parent directory for the named project, or the exact target with `--in-place`	`--dir ./projects`
`--in-place`	Generate directly in `--dir` (or the current directory); the target must be empty except for managed `.fluxzero/dev` state	`--in-place`
`--package`	Java package name	`--package com.example.myapp`
`--group-id`	Maven/Gradle group ID	`--group-id com.example`
`--artifact-id`	Maven/Gradle artifact ID	`--artifact-id my-app`
`--application-id`	Fluxzero application ID to configure for package publishing	`--application-id app-...`
`--description`	Project description	`--description "My application"`
`--build`	Build system (`maven` or `gradle`)	`--build gradle`
`--git`	Initialize Git repository	`--git`

fz init examples:

# Interactive mode (prompts for all options)
fz init

# With built-in template
fz init --template flux-basic-kotlin --name my-app --package com.example.myapp --build gradle

# Into the current empty workspace while pre-init Fluxzero dev state is present
fz init --in-place --template flux-basic-java --name my-app --package com.example.myapp --build maven

# Using custom template directory
fz init --template-path ./my-templates --template custom-template --name my-project

# Using custom template ZIP file
fz init --template-path ./templates/my-template.zip --template my-template --name my-project

# Full example with all options
fz init \
  --template flux-basic-java \
  --name awesome-app \
  --dir ./workspace \
  --package com.company.awesome \
  --group-id com.company \
  --artifact-id awesome-app \
  --description "An awesome application" \
  --build maven \
  --git

Custom Templates

The --template-path parameter allows you to use templates from:

Local directory containing multiple templates:

# Directory structure:
# my-templates/
# ├── web-template/
# ├── api-template/
# └── cli-template/
fz init --template-path ./my-templates --template web-template

Single ZIP file template:

fz init --template-path ./my-template.zip --template my-template

Templates should follow the same structure as built-in templates with optional refactor.yaml for customization.

`fz templates list` - List available templates

# List built-in templates
fz templates list

# List templates from custom directory (not currently supported - use fz init with --template-path)

`fz version` - Show version information

fz version

`fz upgrade` - Upgrade CLI to latest version

fz upgrade

See fz --help or fz --help for detailed help on any command.

Installation Location

FluxZero CLI installs to:

Directory: ~/.fluxzero/bin/fz (or fz.exe on Windows)
PATH Integration:
- Unix: /usr/local/bin/fz → ~/.fluxzero/bin/fz
- Windows: ~/.fluxzero/bin added to user PATH
Legacy Support: Also detects and can upgrade from old .flux/fluxzero-cli.jar installations

Requirements

Native executables: Self-contained for regular CLI commands
Development server: Java 25 or higher; fz dev detects it and can offer installation through Homebrew or WinGet
JAR version: Java 21 or higher for regular CLI commands; fz dev has the development-server requirement above

Templates

Template sources live in templates/src/main/template-sources and are versioned, tested, and released atomically with the CLI and its Maven and Gradle plugins. The :templates:packageTemplates task creates the embedded ZIP resources and injects the current release version into each generated project's plugin configuration. Development builds use the configured released fallback plugin version by default; pass -PtemplatePluginVersion= when validating a different locally published version.

Template features:

Package name replacement
File removal based on configuration
Line-by-line content modification
File permission management
Interactive customization during project creation

Available templates:

flux-basic-java - Java starter with Maven and Gradle wrappers
flux-basic-kotlin - Kotlin starter with Maven and Gradle wrappers

These are generic starters. Generated code must still be adapted to the actual product requirements. The templates do not contain local AI-agent manuals; current Fluxzero guidance is distributed by the separately installable Fluxzero Codex plugin and its MCP server. Existing projects may still opt into local instruction files through the supported Gradle plugin or Maven sync-project-files goal described below.

Template Customization with `refactor.yaml`

Templates can include a refactor.yaml file to customize the generated project. This file defines operations that are applied during project initialization.

Supported Operations

replace - Text replacement

- type: replace
  files: ["**/*.kt", "**/*.java"]     # Glob patterns for files to modify
  find: "com\\.example\\.template"    # Text or regex to find
  replace: "${package}"               # Replacement text (supports variables)
  regex: true                         # Whether to use regex matching (default: false)

delete - File removal

- type: delete
  files: ["**/*.tmp", "build/"]       # Glob patterns for files/directories to delete

rename - File/directory renaming

- type: rename
  from: "src/main/kotlin/com/example/template"
  to: "src/main/kotlin/${packagePath}"

createDirectory - Directory creation

- type: createDirectory
  directory: "logs"                   # Directory path (supports variables)

chmod - File permission management

- type: chmod
  files: ["gradlew", "scripts/*.sh"]  # Glob patterns for files to modify
  mode: "755"                         # Standard Unix permissions: 755 (executable), 644 (read-only), 777 (full access)

cleanupEmptyDirectories - Remove empty directories

- type: cleanupEmptyDirectories
  paths: ["src/main", "src/test"]     # Directory paths to clean (default: ["src/main", "src/test"])

Variable Substitution

The following variables are available for use in replace, rename, createDirectory operations:

${package} - Java package name (e.g., com.example.myapp)
${packagePath} - Package as file path (e.g., com/example/myapp)
${projectName} - Project name
${groupId} - Maven/Gradle group ID
${artifactId} - Maven/Gradle artifact ID
${description} - Project description

Variables can be used in either ${variable} or {{variable}} format.

Example `refactor.yaml`

operations:
  # Replace package names in source files
  - type: replace
    files: ["**/*.kt"]
    find: "package com\\.example\\.template"
    replace: "package ${package}"
    regex: true

  # Update build files
  - type: replace
    files: ["pom.xml", "build.gradle.kts"]
    find: "com.example.template"
    replace: "${package}"

  # Make scripts executable
  - type: chmod
    files: ["gradlew", "scripts/*.sh"]
    mode: "755"

  # Make config files read-only
  - type: chmod
    files: ["config/*.conf"]
    mode: "644"

  # Rename package directories
  - type: rename
    from: "src/main/kotlin/com/example/template"
    to: "src/main/kotlin/${packagePath}"

  # Clean up temporary files
  - type: delete
    files: ["**/*.tmp"]

  # Create log directory
  - type: createDirectory
    directory: "logs"

Build the embedded template resources directly with ./gradlew :templates:packageTemplates. They are written to templates/build/generated/resources/templates and are included automatically in CLI JARs and native executables.

Build Plugins

Fluxzero provides Gradle and Maven plugins that run the local development environment, publish layered Java OCI packages, and optionally synchronize AI agent instruction files.

Gradle Plugin

build.gradle.kts

plugins {
    id("io.fluxzero.tools.gradle.plugin") version "1.0.0"
}

// Minimal setup - everything is auto-detected
fluxzero {
    projectFiles {
        enabled.set(true)
    }
    packagePublishing {
        packageName.set("my-service")
        images.add("registry.fluxzero.io/\${organisationId}/\${packageName}")
        authentications {
            create("fluxzero") {
                host.set("registry.fluxzero.io")
                githubOidc {
                    audience.set("https://cloud.fluxzero.io")
                }
            }
        }
    }
}

// Or with explicit configuration
fluxzero {
    projectFiles {
        // Keep the plugin configured but skip all syncing when false (default: true).
        enabled.set(true)

        // Sync once from the root project in multi-module builds (default: true).
        rootProjectOnly.set(true)

        // Re-download and rewrite files even when local sync metadata is current (default: false).
        forceUpdate.set(false)

        // Use only when language detection is wrong or unavailable. Values: "kotlin" or "java".
        overrideLanguage.set("kotlin")

        // Use only when the SDK version cannot be inferred from dependencies, BOMs, or properties.
        overrideSdkVersion.set("1.2.0")
    }
}

settings.gradle.kts

pluginManagement {
    repositories {
        maven { url = uri("https://packages.fluxzero.io/maven") }
        gradlePluginPortal()
        mavenCentral()
    }
}

Command line properties:

./gradlew build -Pfluxzero.projectFiles.enabled=false
./gradlew build -Pfluxzero.projectFiles.overrideLanguage=kotlin
./gradlew syncProjectFiles -Pfluxzero.projectFiles.forceUpdate=true
./gradlew build fluxzeroPublishPackage

Maven Plugin

Add the plugin repository to pom.xml (or merge it with the existing section):


    
        fluxzero-plugins
        https://packages.fluxzero.io/maven
        false

pom.xml


    
        
            io.fluxzero.tools
            fluxzero-maven-plugin
            1.0.0
            
                
                    
                        sync-project-files

With explicit configuration:


    io.fluxzero.tools
    fluxzero-maven-plugin
    1.0.0
    
        
        true

        
        true

        
        false

        
        kotlin

        
        1.75.1
    
    
        
            
                sync-project-files

Command line properties:

mvn clean install -Dfluxzero.projectFiles.enabled=false
mvn clean install -Dfluxzero.projectFiles.overrideLanguage=kotlin
mvn clean install -Dfluxzero.projectFiles.forceUpdate=true

Plugin Documentation

For detailed documentation, troubleshooting, and advanced examples:

Development

Building the CLI

./gradlew build :cli:shadowJar

Building Native Executable

Requires GraalVM with native-image support:

# Switch to GraalVM (example using jenv)
jenv local oracle64-21.0.1

# Build native executable
./gradlew :cli:nativeCompile

# Test the native executable
./cli/build/native/nativeCompile/flux version

Running

./gradlew run
# or
java -jar cli/build/libs/fluxzero-cli-dev.jar version

Testing

./gradlew test

Architecture

Kotlin-based with Clikt for command-line parsing and JLine for interactive prompts
Template system with ZIP-based project scaffolding and YAML-based customization
Multi-platform builds via GitHub Actions for Linux, macOS, and Windows (ARM64/x86_64)
Native image compilation using GraalVM for optimal performance
Automated installation with platform detection and PATH integration
Per-project versioning via .flux/config.yaml

CI/CD

Native Build Workflow: Builds native executables for Linux, macOS, and Windows with integration testing
Release Workflow: Auto-versioning with git tags and comprehensive artifact releases
Package-manager publishing: Opens tested Homebrew formula updates and submits WinGet manifests from immutable release assets without rebuilding the CLI
Automated testing:
- Unit tests with MockK
- Integration tests (CLI functionality + project generation)
- Installation script verification
- Cross-platform build verification
Release Artifacts:
- Native executables for all platforms
- WinGet-compatible portable Windows archive
- JAR for cross-platform compatibility
- Installation and uninstallation scripts

Package-manager publishing requires the organization secrets FLUXZERO_BOT_APP_ID and FLUXZERO_BOT_PRIVATE_KEY for the fluxzero-io/homebrew-tap repository. WinGet publishing uses two tokens from the account that has accepted Microsoft's contributor license agreement:

WINGET_CREATE_GITHUB_TOKEN: a classic PAT with only the public_repo scope for WingetCreate submissions to microsoft/winget-pkgs.
WINGET_FORK_SYNC_GITHUB_TOKEN: a fine-grained PAT limited to that account's winget-pkgs fork, with Contents: Read and write and Workflows: Read and write, for synchronizing the fork before WingetCreate runs. GitHub requires the latter whenever the upstream synchronization includes changes under .github/workflows.

Keeping these tokens separate avoids granting a classic PAT the broad repo scope that GitHub automatically requires when its workflow scope is selected.

Build-plugin releases

The release workflow publishes the existing Maven and Gradle publications (including io.fluxzero.tools.gradle.plugin's marker) to https://packages.fluxzero.io/publish/maven with standard Gradle Maven Publish tasks, then verifies independent consumers using https://packages.fluxzero.io/maven. Until 1 October 2026, it subsequently publishes to Maven Central and verifies those artifacts. From that date, new plugin releases are available only from Fluxzero Packages; existing Central releases remain available. GitHub OIDC uses audience https://packages.fluxzero.io/publish/maven; only the publishing job has id-token: write. A fresh short-lived token is requested before each publication; the Gradle marker is uploaded after its implementation. Existing GPG signing secrets remain in use.

A reserved version is never uploaded again on a workflow rerun. If either repository contains an incomplete release, fix the cause and start a new Release workflow to reserve the next version. Do not rebuild or overwrite already published release bytes.

Run scripts/test-plugin-publication.sh to publish with an ephemeral signing key to a temporary file repository, verify the existing attachments/signatures, and execute Maven and Gradle consumers with empty caches. Run scripts/verify-published-plugins.sh VERSION https://packages.fluxzero.io/maven to qualify a live release. The Maven consumer checks repository provenance; Gradle exclusively routes Fluxzero coordinates, including the plugin marker, to the repository being qualified. Central is used for third-party dependencies.

License

The CLI and build plugins are licensed under the EUPL-1.2; see LICENSE. The embedded starter-template sources under templates/src/main/template-sources retain their Apache-2.0 license; see templates/LICENSE.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

fluxzero-cli

A command-line interface for Flux that helps you scaffold new projects, perform dependency upgrades, generate example code, and manage Flux Cloud resources.

Installation

Option 1: Package Managers (Recommended)

macOS or Linux with Homebrew:

brew install fluxzero-io/tap/fluxzero

Windows with WinGet:

winget install --exact --id Fluxzero.FluxzeroCLI

Package-manager installations receive normal brew upgrade and winget upgrade support.

Option 2: Automated Installation

Unix/Linux/macOS:

curl -sSL https://github.com/fluxzero-io/fluxzero-cli/releases/latest/download/install.sh | sh

Windows PowerShell:

iwr -useb https://github.com/fluxzero-io/fluxzero-cli/releases/latest/download/install.ps1 | iex

The installer will:

🎯 Auto-detect your platform and architecture
📦 Download the native package (no Java required; the Windows package includes its Visual C++ runtime)
⚡ Install to ~/.fluxzero/bin/fz
🔗 Add to PATH (optional - you'll be prompted)
✅ Verify installation with test commands

Option 3: Manual Native Download

Download the native package or executable for your platform from the releases page:

Linux x86_64: flux-linux-amd64
macOS Intel: flux-macos-amd64
macOS Apple Silicon: flux-macos-arm64
Windows x64: flux-windows-amd64.zip (extract all files into one directory)

# Example for macOS Apple Silicon
curl -L -o fz https://github.com/fluxzero-io/fluxzero-cli/releases/latest/download/flux-macos-arm64
chmod +x fz
sudo mv fz /usr/local/bin/fz

Benefits of native downloads:

⚡ 5x faster startup (~0.27s vs ~1.36s for JAR)
📦 No Java installation required
🚀 Instant execution (no JVM warm-up time)
🌍 Cross-platform (Linux, macOS, Windows)

Option 4: Fluxzero Launchpad

Fluxzero also ships a macOS app, Fluxzero Launchpad, for generating projects locally and opening them in coding agents.

The signed and notarized macOS DMG is published with each release:

macOS Intel / Apple Silicon: Fluxzero-Launchpad.dmg

Windows and Linux Launchpad apps are planned, but are not published yet.

fluxzero://new?... opens Launchpad and pre-fills the generator.
fluxzero://open?path=...&prompt=...&agent=codex|claude|cursor|finder|none opens an existing project directly.
fluxzero://create?name=...&prompt=...&agent=codex|claude|cursor|finder|none creates a project with defaults and opens it directly.

Option 5: Manual JAR Installation (Legacy)

Download the latest fluxzero-cli.jar from the releases page
Run it with Java: java -jar fluxzero-cli.jar

Uninstallation

To remove FluxZero CLI from your system:

Unix/Linux/macOS:

curl -sSL https://github.com/fluxzero-io/fluxzero-cli/releases/latest/download/uninstall.sh | sh

Windows PowerShell:

iwr -useb https://github.com/fluxzero-io/fluxzero-cli/releases/latest/download/uninstall.ps1 | iex

The uninstaller will:

🔍 Detect installations (both current .fluxzero and legacy .flux directories)
📋 Show what will be removed with confirmation prompts
🗑️ Clean removal of binaries, directories, and PATH entries
✨ Complete cleanup leaves no traces

Add --force (Unix) or -Force (Windows) to skip confirmation prompts.

Project Versioning

The fluxzero-cli uses per-project versioning rather than global installation. Each project determines which version of the CLI it uses in the .flux/config.yaml file.

Usage

Once installed, you can use the CLI with either the short fz command or the equivalent fluxzero command:

# Initialize a new project (interactive template selection)
fz init my-project

# List available templates
fz templates list

# Start the local Fluxzero development environment
fz dev

# Expose the active environment to an MCP client over stdio
fz mcp

# Show version
fz version

# Upgrade CLI to latest version
fz upgrade

Local development

The application main class is detected from compiled Java or Kotlin classes. Use --main-class only when a project contains multiple executable entrypoints and the intended one is ambiguous.

fz dev

fz dev --fast-compiler
fz dev --app app
fz dev --app app --app audittrail
fz dev --environment dev
fz dev --port 4200
fz dev --idp external
fz dev --frontend-command "npm run dev"
fz dev --frontend-directory frontend --frontend-setup-command "npm install --prefer-offline --no-audit --no-fund"
fz dev --frontend-url http://localhost:5173
fz dev --no-tests

fz dev --background
fz dev list
fz dev list --json
fz dev attach
fz dev status
fz dev status --json
fz dev logs --follow
fz dev logs --follow --errors
fz dev logs --follow --app orders
fz dev restart
fz dev stop
fz dev stop --force
fz dev stop --all
fz dev config

Start options:

Option	Meaning
`--app`	Start one module, main class, test app, or named app configuration; repeatable.
`--main-class`	Override main-class detection.
`--application-name`	Override the Fluxzero runtime application name.
`--profile`	Select a named development profile from `.fluxzero/dev.yaml`.
`--environment`	Set `ENVIRONMENT`; defaults to `local`.
`--namespace`	Set the Fluxzero namespace.
`--port`	Prefer a public browser/gateway port; dynamic by default.
`--idp managed	external`
`--no-idp`	Alias for `--idp external`.
`--frontend-command`	Start a managed frontend; use `{port}` for its private upstream port.
`--frontend-directory`	Working directory for managed frontend commands.
`--frontend-setup-command`	Run setup once before the managed frontend starts for this dev session.
`--frontend-url`	Proxy an externally managed frontend.
`--no-frontend`	Run a backend-only environment.
`--backend-path`	Route an extra public path directly to Fluxzero; repeatable.
`--fast-compiler`	Enable the Maven-correct fast Java path; Maven remains the fallback.
`--no-tests`	Disable background test selection and execution.
`--no-watch`	Disable source watching.
`--no-compile-on-start`	Start infrastructure without compiling applications.
`--app-arg`	Pass an application argument; repeatable.
`--startup-timeout-ms`	Override application/frontend readiness timeout.
`--graceful-shutdown-timeout-ms`	Override rolling app shutdown timeout.
`--debounce-ms`	Override source-change debounce.
`--idle-timeout`	Stop an inactive environment; defaults to `24h`, use `disabled` to opt out.
`--background`, `--detach`, `-d`	Start without an attached live view and return after startup succeeds or fails.

Shared project defaults belong in the tracked .fluxzero/dev.yaml; session state, logs, tokens, and build snapshots remain ignored under .fluxzero/dev/:

version: 1
environment: local
apps:
  - app
port: 4200
idp: external
frontend:
  command: "cd frontend &amp;&amp; npm start -- --host 127.0.0.1 --port {port}"
  backendPaths:
    - /api
lifecycle:
  idleTimeout: 24h
applicationConfig:
  rebound-encrypted:
    application: rebound
    applicationName: rebound
    env:
      FEATURE_MODE: local
    secrets:
      ENCRYPTION_KEY: "op://Fluxzero Cloud/flux_cloud_flux-encryption-key/local encryption-key"
commands:
  create-admin:
    type: com.example.CreateUser
    payload:
      name: Local Admin

For multiple complete local setups, define named profiles and select one explicitly or configure a default. Legacy top-level settings remain supported and cannot be mixed with profiles:

version: 1
defaultProfile: encrypted
profiles:
  encrypted:
    environment: local
    apps: [rebound-encrypted]
    frontend:
      directory: frontend
      command: "npm run dev -- --port {port}"
  reporting:
    environment: local
    apps: [rebound, reporting]

Run the non-default setup with fz dev --profile reporting. A single profile is selected automatically when no defaultProfile is configured.

fz mcp --ensure-dev --project-dir /path/to/project

Project-local launchers provide the same environment without a globally installed CLI:

./mvnw fluxzero:dev
./mvnw fluxzero:dev -Dfluxzero.dev.background=true

./gradlew fluxzeroDev
./gradlew fluxzeroDev -Pfluxzero.dev.background=true

CLI Commands & Parameters

`fz init` - Initialize a new project

Basic usage:

fz init [OPTIONS]

Options:

Parameter	Description	Example
`--template`	Name of the template to use	`--template flux-basic-kotlin`
`--template-path`	Path to custom template directory or ZIP file	`--template-path ./my-templates`
`--name`	Project name (1-50 chars: 0-9, a-z, -, _)	`--name my-app`
`--dir`	Parent directory for the named project, or the exact target with `--in-place`	`--dir ./projects`
`--in-place`	Generate directly in `--dir` (or the current directory); the target must be empty except for managed `.fluxzero/dev` state	`--in-place`
`--package`	Java package name	`--package com.example.myapp`
`--group-id`	Maven/Gradle group ID	`--group-id com.example`
`--artifact-id`	Maven/Gradle artifact ID	`--artifact-id my-app`
`--application-id`	Fluxzero application ID to configure for package publishing	`--application-id app-...`
`--description`	Project description	`--description "My application"`
`--build`	Build system (`maven` or `gradle`)	`--build gradle`
`--git`	Initialize Git repository	`--git`

fz init examples:

# Interactive mode (prompts for all options)
fz init

# With built-in template
fz init --template flux-basic-kotlin --name my-app --package com.example.myapp --build gradle

# Into the current empty workspace while pre-init Fluxzero dev state is present
fz init --in-place --template flux-basic-java --name my-app --package com.example.myapp --build maven

# Using custom template directory
fz init --template-path ./my-templates --template custom-template --name my-project

# Using custom template ZIP file
fz init --template-path ./templates/my-template.zip --template my-template --name my-project

# Full example with all options
fz init \
  --template flux-basic-java \
  --name awesome-app \
  --dir ./workspace \
  --package com.company.awesome \
  --group-id com.company \
  --artifact-id awesome-app \
  --description "An awesome application" \
  --build maven \
  --git

Custom Templates

The --template-path parameter allows you to use templates from:

Local directory containing multiple templates:

# Directory structure:
# my-templates/
# ├── web-template/
# ├── api-template/
# └── cli-template/
fz init --template-path ./my-templates --template web-template

Single ZIP file template:

fz init --template-path ./my-template.zip --template my-template

Templates should follow the same structure as built-in templates with optional refactor.yaml for customization.

`fz templates list` - List available templates

# List built-in templates
fz templates list

# List templates from custom directory (not currently supported - use fz init with --template-path)

`fz version` - Show version information

fz version

`fz upgrade` - Upgrade CLI to latest version

fz upgrade

See fz --help or fz --help for detailed help on any command.

Installation Location

FluxZero CLI installs to:

Directory: ~/.fluxzero/bin/fz (or fz.exe on Windows)
PATH Integration:
- Unix: /usr/local/bin/fz → ~/.fluxzero/bin/fz
- Windows: ~/.fluxzero/bin added to user PATH
Legacy Support: Also detects and can upgrade from old .flux/fluxzero-cli.jar installations

Requirements

Native executables: Self-contained for regular CLI commands
Development server: Java 25 or higher; fz dev detects it and can offer installation through Homebrew or WinGet
JAR version: Java 21 or higher for regular CLI commands; fz dev has the development-server requirement above

Templates

Template features:

Package name replacement
File removal based on configuration
Line-by-line content modification
File permission management
Interactive customization during project creation

Available templates:

flux-basic-java - Java starter with Maven and Gradle wrappers
flux-basic-kotlin - Kotlin starter with Maven and Gradle wrappers

Template Customization with `refactor.yaml`

Templates can include a refactor.yaml file to customize the generated project. This file defines operations that are applied during project initialization.

Supported Operations

replace - Text replacement

- type: replace
  files: ["**/*.kt", "**/*.java"]     # Glob patterns for files to modify
  find: "com\\.example\\.template"    # Text or regex to find
  replace: "${package}"               # Replacement text (supports variables)
  regex: true                         # Whether to use regex matching (default: false)

delete - File removal

- type: delete
  files: ["**/*.tmp", "build/"]       # Glob patterns for files/directories to delete

rename - File/directory renaming

- type: rename
  from: "src/main/kotlin/com/example/template"
  to: "src/main/kotlin/${packagePath}"

createDirectory - Directory creation

- type: createDirectory
  directory: "logs"                   # Directory path (supports variables)

chmod - File permission management

- type: chmod
  files: ["gradlew", "scripts/*.sh"]  # Glob patterns for files to modify
  mode: "755"                         # Standard Unix permissions: 755 (executable), 644 (read-only), 777 (full access)

cleanupEmptyDirectories - Remove empty directories

- type: cleanupEmptyDirectories
  paths: ["src/main", "src/test"]     # Directory paths to clean (default: ["src/main", "src/test"])

Variable Substitution

The following variables are available for use in replace, rename, createDirectory operations:

${package} - Java package name (e.g., com.example.myapp)
${packagePath} - Package as file path (e.g., com/example/myapp)
${projectName} - Project name
${groupId} - Maven/Gradle group ID
${artifactId} - Maven/Gradle artifact ID
${description} - Project description

Variables can be used in either ${variable} or {{variable}} format.

Example `refactor.yaml`

operations:
  # Replace package names in source files
  - type: replace
    files: ["**/*.kt"]
    find: "package com\\.example\\.template"
    replace: "package ${package}"
    regex: true

  # Update build files
  - type: replace
    files: ["pom.xml", "build.gradle.kts"]
    find: "com.example.template"
    replace: "${package}"

  # Make scripts executable
  - type: chmod
    files: ["gradlew", "scripts/*.sh"]
    mode: "755"

  # Make config files read-only
  - type: chmod
    files: ["config/*.conf"]
    mode: "644"

  # Rename package directories
  - type: rename
    from: "src/main/kotlin/com/example/template"
    to: "src/main/kotlin/${packagePath}"

  # Clean up temporary files
  - type: delete
    files: ["**/*.tmp"]

  # Create log directory
  - type: createDirectory
    directory: "logs"

Build Plugins

Fluxzero provides Gradle and Maven plugins that run the local development environment, publish layered Java OCI packages, and optionally synchronize AI agent instruction files.

Gradle Plugin

build.gradle.kts

plugins {
    id("io.fluxzero.tools.gradle.plugin") version "1.0.0"
}

// Minimal setup - everything is auto-detected
fluxzero {
    projectFiles {
        enabled.set(true)
    }
    packagePublishing {
        packageName.set("my-service")
        images.add("registry.fluxzero.io/\${organisationId}/\${packageName}")
        authentications {
            create("fluxzero") {
                host.set("registry.fluxzero.io")
                githubOidc {
                    audience.set("https://cloud.fluxzero.io")
                }
            }
        }
    }
}

// Or with explicit configuration
fluxzero {
    projectFiles {
        // Keep the plugin configured but skip all syncing when false (default: true).
        enabled.set(true)

        // Sync once from the root project in multi-module builds (default: true).
        rootProjectOnly.set(true)

        // Re-download and rewrite files even when local sync metadata is current (default: false).
        forceUpdate.set(false)

        // Use only when language detection is wrong or unavailable. Values: "kotlin" or "java".
        overrideLanguage.set("kotlin")

        // Use only when the SDK version cannot be inferred from dependencies, BOMs, or properties.
        overrideSdkVersion.set("1.2.0")
    }
}

settings.gradle.kts

pluginManagement {
    repositories {
        maven { url = uri("https://packages.fluxzero.io/maven") }
        gradlePluginPortal()
        mavenCentral()
    }
}

Command line properties:

./gradlew build -Pfluxzero.projectFiles.enabled=false
./gradlew build -Pfluxzero.projectFiles.overrideLanguage=kotlin
./gradlew syncProjectFiles -Pfluxzero.projectFiles.forceUpdate=true
./gradlew build fluxzeroPublishPackage

Maven Plugin

Add the plugin repository to pom.xml (or merge it with the existing section):


    
        fluxzero-plugins
        https://packages.fluxzero.io/maven
        false

pom.xml


    
        
            io.fluxzero.tools
            fluxzero-maven-plugin
            1.0.0
            
                
                    
                        sync-project-files

With explicit configuration:


    io.fluxzero.tools
    fluxzero-maven-plugin
    1.0.0
    
        
        true

        
        true

        
        false

        
        kotlin

        
        1.75.1
    
    
        
            
                sync-project-files

Command line properties:

mvn clean install -Dfluxzero.projectFiles.enabled=false
mvn clean install -Dfluxzero.projectFiles.overrideLanguage=kotlin
mvn clean install -Dfluxzero.projectFiles.forceUpdate=true

Plugin Documentation

For detailed documentation, troubleshooting, and advanced examples:

Development

Building the CLI

./gradlew build :cli:shadowJar

Building Native Executable

Requires GraalVM with native-image support:

# Switch to GraalVM (example using jenv)
jenv local oracle64-21.0.1

# Build native executable
./gradlew :cli:nativeCompile

# Test the native executable
./cli/build/native/nativeCompile/flux version

Running

./gradlew run
# or
java -jar cli/build/libs/fluxzero-cli-dev.jar version

Testing

./gradlew test

Architecture

Kotlin-based with Clikt for command-line parsing and JLine for interactive prompts
Template system with ZIP-based project scaffolding and YAML-based customization
Multi-platform builds via GitHub Actions for Linux, macOS, and Windows (ARM64/x86_64)
Native image compilation using GraalVM for optimal performance
Automated installation with platform detection and PATH integration
Per-project versioning via .flux/config.yaml

CI/CD

Native Build Workflow: Builds native executables for Linux, macOS, and Windows with integration testing
Release Workflow: Auto-versioning with git tags and comprehensive artifact releases
Package-manager publishing: Opens tested Homebrew formula updates and submits WinGet manifests from immutable release assets without rebuilding the CLI
Automated testing:
- Unit tests with MockK
- Integration tests (CLI functionality + project generation)
- Installation script verification
- Cross-platform build verification
Release Artifacts:
- Native executables for all platforms
- WinGet-compatible portable Windows archive
- JAR for cross-platform compatibility
- Installation and uninstallation scripts

WINGET_CREATE_GITHUB_TOKEN: a classic PAT with only the public_repo scope for WingetCreate submissions to microsoft/winget-pkgs.
WINGET_FORK_SYNC_GITHUB_TOKEN: a fine-grained PAT limited to that account's winget-pkgs fork, with Contents: Read and write and Workflows: Read and write, for synchronizing the fork before WingetCreate runs. GitHub requires the latter whenever the upstream synchronization includes changes under .github/workflows.

Keeping these tokens separate avoids granting a classic PAT the broad repo scope that GitHub automatically requires when its workflow scope is selected.

Build-plugin releases

License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fluxzero CLI Fluxzero

README

fluxzero-cli

Installation

Option 1: Package Managers (Recommended)

Option 2: Automated Installation

Option 3: Manual Native Download

Option 4: Fluxzero Launchpad

Option 5: Manual JAR Installation (Legacy)

Uninstallation

Project Versioning

Usage

Local development

CLI Commands & Parameters

fz init - Initialize a new project

Custom Templates

fz templates list - List available templates

fz version - Show version information

fz upgrade - Upgrade CLI to latest version

Installation Location

Requirements

Templates

Template Customization with refactor.yaml

Supported Operations

Variable Substitution

Example refactor.yaml

Build Plugins

Gradle Plugin

Maven Plugin

Plugin Documentation

Development

Building the CLI

Building Native Executable

Running

Testing

Architecture

CI/CD

Build-plugin releases

License

Contributing

Fluxzero CLI Fluxzero

README

fluxzero-cli

Installation

Option 1: Package Managers (Recommended)

Option 2: Automated Installation

Option 3: Manual Native Download

Option 4: Fluxzero Launchpad

Option 5: Manual JAR Installation (Legacy)

Uninstallation

Project Versioning

Usage

Local development

CLI Commands & Parameters

fz init - Initialize a new project

Custom Templates

fz templates list - List available templates

fz version - Show version information

fz upgrade - Upgrade CLI to latest version

Installation Location

Requirements

Templates

Template Customization with refactor.yaml

Supported Operations

Variable Substitution

Example refactor.yaml

Build Plugins

Gradle Plugin

Maven Plugin

Plugin Documentation

Development

Building the CLI

Building Native Executable

Running

Testing

Architecture

CI/CD

Build-plugin releases

License

Contributing

`fz init` - Initialize a new project

`fz templates list` - List available templates

`fz version` - Show version information

`fz upgrade` - Upgrade CLI to latest version

Template Customization with `refactor.yaml`

Example `refactor.yaml`

`fz init` - Initialize a new project

`fz templates list` - List available templates

`fz version` - Show version information

`fz upgrade` - Upgrade CLI to latest version

Template Customization with `refactor.yaml`

Example `refactor.yaml`