Use this command to install Fluxzero CLI with WinGet:
winget install --id=Fluxzero.FluxzeroCLI -e
Fluxzero CLI is a command-line interface designed to streamline project development, resource management, and local environment setup for Flux projects.
Key Features:
Project Scaffolding: Quickly generate new projects with interactive template selection, supporting a range of use cases and architectures.
Resource Management: Easily manage and provision resources on Fluxzero Cloud directly from the command line.
Local Development: Run and supervise local Flux development environments, including application reloads, background tests, and frontend processes.
Cross-Platform Support: Available for Linux, macOS, and Windows, ensuring seamless integration across different operating systems.
Efficient Workflows: Use shortcuts like fz dev to start a development environment or fz upgrade to keep the CLI up-to-date.
Audience & Benefit:
Ideal for developers and teams working with Flux projects, Fluxzero CLI simplifies project initialization, resource management, and local development. By automating repetitive tasks and providing tools for efficient workflow management, it helps teams focus on building applications rather than managing infrastructure.
README
Fluxzero CLI
Command-line tools for creating, developing, and deploying Fluxzero applications.
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
📦 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: 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
🔍 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/:
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:
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:
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:
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.
New projects pin fluxzero.defaults.version in src/main/resources/fluxzero.properties to the local calendar date
at generation time (yyyy.MM.dd). This is a literal project setting, not the CLI release date or a build-time value.
Keep it unchanged during SDK upgrades; advance it only as an intentional defaults migration.
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}"
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")
}
}
Local and release builds use -march=compatibility so AMD64 executables do not require
the default GraalVM x86-64-v3 instruction set (including AVX/AVX2). Keep this option in
both cli/build.gradle.kts and .github/workflows/native-build.yml; avoid -march=native
for distributed binaries. OS and native-library requirements still apply.
Linux CI runs the built executable under QEMU's Nehalem CPU model to check startup and
template access without AVX/AVX2. Windows compatibility must also be checked with the
complete Windows package on a VM exposing the supported CPU baseline.
# 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
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. GitHub CLI releases and package-manager updates
require successful Packages publication and verification. New plugin releases are available only
from Fluxzero Packages; existing Maven 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 Packages
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.
Are you a builder or coding agent?We welcome your ideas, issues, and pull requests!
Unpinned launches pass the update policy to the dev server. An update-aware Devboard can periodically call
fz dev check-update --current-version --project-dir --json and show a restart action.
fz dev prepare-update --current-version --dev-server-version --project-dir --json
rechecks that candidate and downloads the standalone artifact through the existing verified cache. Both
commands return JSON; preparation leaves running processes and project configuration untouched.
Only newer stable releases in the supported dev-server major are offered. Explicit --dev-server-version
and FLUXZERO_DEV_SERVER_VERSION selections disable automatic offers. The launch policy is retained beside
the project's cached launcher so subsequent MCP/control launches preserve that choice. Old cached launchers
without a policy are treated conservatively until a fresh CLI start. Devboard requires confirmation before
replacing its process and resetting local application/monitoring data. Agent plugin updates remain managed
by the host agent application.
