Command-line interface overview

Fission

Product

▾

Setup

›

Command-line interface overview

The Fission command-line interface is the tool you use to put a new Fission app on disk, connect that shared app to real platform hosts, and keep the daily development loop consistent across macOS, Windows, Linux, Web, Android, iOS, Terminal, Static site, and SSR targets.

That distinction matters. Fission's core architecture lives in your shared Rust code: your app state, actions, reducers, widgets, and effects. The command-line interface does not replace that architecture. Its job is narrower and more concrete. It gives you a correct starting scaffold, records which targets your app supports, generates scaffolded host folders where that target needs them, and gives you one place to discover devices, run the app, attach logs, build artifacts, and run smoke tests.

If you are learning Fission, think of the command-line interface as the bridge between two layers:

•

your shared app model, which stays the same across platforms, and

•

the shell hosts, which package and launch that shared app in a macOS, Windows, Linux, Web, Android, iOS, Terminal, Static site, or SSR target.

This page explains how to use that bridge well.

How the command-line interface fits into a real workflow

Most teams meet the command-line interface at two moments.

The first moment is the start of a project. You run fission init when you want a fresh app with the expected file layout, a starter application, an initial desktop host, and a fission.toml manifest that records project metadata and target choices.

The second moment is when your shared app is ready to run in another host. At that point, you use fission add-target to generate scaffolded host folders for Web, Android, iOS, Static site, SSR, or a specific desktop target when needed. Terminal uses the terminal shell and package workflow rather than a mobile-style generated host folder. The important idea is that you are not rewriting your app for each platform. You are using the host wrapper around the same shared app model.

After that, the command-line interface becomes part of the normal development loop. You can ask it which devices are available, choose a device by id, run the app, attach to logs, build without launching, or run the generated smoke test. That keeps the workflow close to the app instead of forcing every developer on the team to memorize different shell scripts for each platform.

Different teams choose a different first validation path. Many developers start on desktop because cargo run is a very short local loop on most machines. Others start in the browser because their product is web-first, or move into Android or iOS early because mobile input, screen size, and safe-area behavior are central to the product. The command-line interface supports that model: one shared app, multiple real hosts, generated when you need them.

Commands at a glance

Fission exposes these public command-line interface entry points:

Command	What it does	When you usually reach for it
fission init <path>	Creates a new Fission project scaffold	When you are starting a new app
fission add-target <targets...>	Adds generated host folders for more platforms	When your existing app needs another host
fission add-capability <capabilities...>	Declares host capabilities and updates generated platform config	Before using device features such as camera, microphone, NFC, Bluetooth, Wi-Fi, or geolocation
fission doctor [targets...]	Checks local SDKs, browsers, emulators, and Rust targets	When setting up a machine or diagnosing a broken platform loop
fission devices	Lists runnable desktop, browser, simulator, emulator, and device targets	Before choosing where to run the app
fission run	Builds and launches the app, attaching output or device logs by default	During normal development
fission build	Builds a target without launching it	Before sharing an artifact with someone else
fission test	Runs the generated platform smoke test	Before merging target-specific work
fission logs	Attaches to logs for a running or detached target where supported	When you launched with --detach or need to reconnect
fission site routes	Lists generated custom and content site routes	Before checking navigation or publishing a static site
fission site check	Renders all static site routes and validates links without writing the final site	In pull-request validation for site content
fission site build	Builds the static site into the configured output directory	Before publishing documentation or marketing pages
fission site serve	Builds and serves the generated static site locally	When reviewing site pages in a browser
fission server build	Builds the server binary and route-local browser artifacts	Before packaging or deploying a server-rendered app
fission server check	Renders all server routes and verifies the server app can produce HTML	Before deploying server-rendered routes
fission server serve	Runs the server-rendered app locally	When reviewing dynamic pages, jobs, workers, and islands
fission server artifacts	Generates per-worker and per-island browser artifacts	Before packaging server pages with browser enhancements
fission package	Packages an app, static site, or server into a release artifact manifest	Before publishing or archiving release output
fission publish	Publishes a packaged artifact to a configured provider	When uploading to static hosts, GitHub Releases, object storage, stores, or Docker registries

Repository developers may see the package name cargo-fission in workspace commands. That is the package that builds and installs the developer-facing fission command; product documentation and generated project files should use fission ....

Starting a new app with fission init

Run fission init <path> when you want a new project directory with the basic pieces already connected correctly.

fission init my-app

This command creates the directory, writes the starter source files, seeds the default app icon, creates an initial desktop-ready entrypoint, and records project metadata in fission.toml.

If the directory already contains files, the command becomes non-destructive. It derives the package name from Cargo.toml when possible, detects existing platforms/<target>/ folders, writes or updates fission.toml, and creates only missing generated support files. It does not overwrite existing source files, README files, host pages, scripts, or assets. That means you can safely run it on an existing example or app that predates fission.toml.

Important init flags

These flags matter most in day-to-day use:

Flag	Type	Meaning	Notes and default behavior
--name <name>	string	Sets the Rust package and crate name explicitly	By default, the directory name is used
--app-id <id>	string	Sets the application identifier used by packaged hosts	Use a reverse-domain name such as com.example.notes if you already know your shipping identifier
--local-path <path>	path	Points the scaffold at a local Fission checkout	Useful when developing against this repository instead of published crates

For a beginner, --local-path is the least obvious flag, so it is worth calling out directly. Rust projects normally depend on published crates from the package registry. When you pass --local-path, the scaffold instead points at a local Fission workspace on your machine. That is mainly useful when you are contributing to Fission itself or testing changes in the framework before publication.

What fission init creates

The generated project is small on purpose. It gives you a runnable starting point without hiding the structure of a Fission app.

These are the files most people open first:

Path	Type	Meaning	Notes and default behavior
src/main.rs	Rust source file	Starts the default desktop host	This is the shortest way to run a fresh scaffold with cargo run
src/lib.rs	Rust source file	Exposes shared entry helpers for non-desktop hosts	Generated hosts call into this shared library layer
src/app.rs	Rust source file	Contains the starter app logic	This is where you edit state, actions, reducers, and widgets
fission.toml	manifest file	Records project metadata and enabled targets	The command-line interface updates this file when you add targets
assets/app-icon.png	image asset	Seeds the default application icon	Generated hosts reuse it as their starting icon asset
platforms/<target>/README.md	generated notes	Explains prerequisites and host-specific commands for that target	Read this whenever you add a new target

The key idea is that only some of those files describe your app. Files under src/ are the shared product logic. Files under platforms/ are host-specific scaffolding. The command-line interface keeps those concerns separate because Fission itself keeps the shared app model separate from the platform shell that runs it.

On an existing project, treat the table as "created if missing." Existing files are preserved. The main required output is fission.toml, because commands such as fission run --project-dir . --target web use it to know which targets belong to the app.

Adding more hosts with fission add-target

Once you have an existing app, use fission add-target to generate another host around it.

fission add-target web ios android --project-dir my-app

This command does not duplicate your shared widgets or reducers. Instead, it updates fission.toml and writes the generated files needed for the requested hosts under platforms/.

If you are new to the term, a target in this context means a host environment that packages and launches your shared app. A generated host is the platform-specific wrapper the command-line interface writes so that environment can start the shared runtime. For web, that means a browser-oriented host page and helper script. For Android, that means the generated NativeActivity packaging files and emulator script. For iOS, that means the simulator bundle template and launch script. For desktop, the initial scaffold already gives you the direct desktop entrypoint.

Important add-target flag

Flag	Type	Meaning	Notes and default behavior
--project-dir <dir>	path	Tells the command-line interface which existing Fission project to update	If omitted, the current directory is used

Supported target values

The current target values are:

Target	Meaning	Generated host output
linux	Linux desktop host	Desktop target metadata and notes
macos	macOS desktop host	Desktop target metadata and notes
windows	Windows desktop host	Desktop target metadata and notes
web	Browser host	platforms/web/ with a helper script and README
server	Server-rendered web host	platforms/server/ notes plus [server].entry in fission.toml
site	Static site target	content/ and static-site configuration
android	Android host	platforms/android/ with packaging files, script, and README
ios	iOS host	platforms/ios/ with simulator bundle files, script, and README

In practice, many projects start with the default desktop scaffold and then add web, android, or ios when that host becomes relevant to the product. The important thing is not the order. The important thing is that the same shared app can be validated through each real host.

Checking your machine with fission doctor

Run doctor when a platform does not build, when you are setting up a new workstation, or when you are preparing a continuous integration runner.

fission doctor web ios android --project-dir my-app

Doctor checks the tools that are visible from your current environment. For web, that includes the WebAssembly Rust target, wasm-pack, Node.js, and Chrome or Chromium. For Android, it checks the Android SDK, Native Development Kit, emulator tooling, and Rust Android target. For iOS, it checks Xcode simulator tooling and the Rust iOS simulator target. Use --strict when you want the command to fail the build if a required tool is missing.

Finding devices with fission devices

Run devices before you run an app on a machine with more than one possible host.

fission devices --project-dir my-app

The output includes stable ids that you can pass back into fission run --device <id>. Desktop uses desktop, web uses chrome, Android uses the adb serial for connected devices and running emulators, and iOS uses the simulator unique device identifier. If you are scripting the workflow, add --json and parse the same data without relying on table formatting.

Running and attaching with fission run

fission run is the default development command once a target exists.

fission run --project-dir my-app
fission run --target web --project-dir my-app
fission run --target android --device emulator-5554 --project-dir my-app
fission run --target ios --device <simulator-udid> --project-dir my-app

If only one runnable device matches the target, the command uses it. If several devices match and the terminal is interactive, the command asks you to choose one. In a script or continuous integration job, pass --device so the choice is explicit.

The command attaches by default because that is the most useful development behavior. Desktop stdout and stderr stay in the terminal. The web target keeps the local static server in the terminal. Android attaches to adb logcat for the launched process. iOS attaches to the simulator log stream for the launched executable.

Use --detach when you want the app or local server to keep running without owning the terminal.

fission run --target web --project-dir my-app --detach
fission logs --target web --project-dir my-app --follow

Web also accepts --host, --port, and --no-open. Mobile targets accept --headless for simulator or emulator runs where the host supports a background launch.

Building and testing targets

Use build when you want the target artifact but do not want to launch it.

fission build --target web --project-dir my-app --release
fission build --target android --project-dir my-app --release

Use test when you want the generated platform smoke test.

fission test --target web --project-dir my-app
fission test --target ios --project-dir my-app --headless
fission test --target android --project-dir my-app --headless

The smoke tests are intentionally not a replacement for your application test suite. They prove that the generated platform host can build, launch, and expose the basic health path for that target. Your app should still have reducer tests, selector tests, widget tests, and product-specific integration tests.

What the generated host files are for

When the command-line interface creates a platforms/<target>/ folder, it is not creating a second app. It is creating the platform-facing wrapper that knows how to build, package, and launch your shared Fission runtime on that host.

That is why generated host folders usually contain two kinds of output:

First, they contain a README. That README is the target-specific checklist. It tells you what the host needs on the current platform, such as browser tooling, simulator prerequisites, or Android environment setup.

Second, they contain scripts or host files. These are the concrete launch paths for that target:

Path	Type	Meaning	Notes and default behavior
platforms/web/run-browser.sh	shell script	Builds the browser package and serves it locally	The current generated host uses wasm-pack for the WebAssembly build step
platforms/android/run-emulator.sh	shell script	Builds, packages, installs, and launches the app on an Android emulator	Reads the expected Android toolchain environment variables
platforms/android/AndroidManifest.xml	Android manifest	Declares the generated Android app package	Written by the command-line interface as part of the host scaffold
platforms/ios/run-sim.sh	shell script	Builds, installs, and launches the app on an iOS simulator	Uses the generated simulator host bundle

If you are a beginner, the practical rule is simple: edit your shared app in src/, then use fission run --target <target> when you want to validate a specific host. The generated scripts remain in platforms/<target>/ for direct CI use and for advanced debugging, but the command-line interface is the normal front door.

A practical way to use the command-line interface without overthinking it

The command-line interface works best when you treat it as a project-setup and host-generation tool, not as the place where application architecture lives.

One common flow looks like this:

Run fission init my-app.

Open src/app.rs and start shaping your real app state, actions, reducers, and widgets.

Run fission doctor --project-dir my-app on a new machine.

Run fission devices --project-dir my-app to see where the app can run.

Run the host that is most convenient for your current work with fission run --target <target> --project-dir my-app.

When you need another platform host, run fission add-target ....

Before merging target work, run fission test --target <target> --project-dir my-app.

That flow stays aligned with Fission's larger design. The shared app model comes first. The command-line interface then helps each platform shell host run that model in a concrete environment.

Command reference

Use this section when you already understand the workflow and just need the exact command shape.

fission init

fission init <path> [--name <name>] [--app-id <id>] [--local-path <path>]

Creates a new Fission project scaffold in the given directory.

fission add-target

fission add-target <targets...> [--project-dir <dir>]

Adds one or more generated host targets to an existing Fission project.

fission add-capability

fission add-capability <capabilities...> [--project-dir <dir>]

Records host capabilities in fission.toml and updates generated platform config where Fission can do that safely. Current manifest values include barcode-scanner, biometric, bluetooth, camera, geolocation, haptics, microphone, nfc, notifications, passkeys, volume-control, and wifi.

Android changes are written to platforms/android/AndroidManifest.xml. iOS usage strings are written to platforms/ios/Info.plist, and entitlement-backed features such as NFC and Wi-Fi update platforms/ios/Entitlements.plist. See Platform capabilities before shipping because some features still need app-specific routes, usage text, app-store setup, or provider implementation.

fission doctor

fission doctor [targets...] [--project-dir <dir>] [--strict]

Checks the local platform toolchains needed for the selected targets.

fission devices

fission devices [--project-dir <dir>] [--json]

Lists launchable macOS, Windows, Linux, Web, Android, and iOS devices known to the command-line interface.

fission run

fission run [--target <target>] [--device <id>] [--project-dir <dir>] [--release] [--detach]

Builds, launches, and attaches to the selected target. Web also accepts --host, --port, and --no-open. Mobile targets also accept --headless.

fission build

fission build [--target <target>] [--project-dir <dir>] [--release]

Builds the selected target without launching it.

fission test

fission test [--target <target>] [--project-dir <dir>] [--headless]

Runs the generated platform smoke test for the selected target.

fission logs

fission logs [--target <target>] [--device <id>] [--project-dir <dir>] [--follow]

Attaches to logs for a selected running or detached target where the platform exposes a log stream.

fission site routes

fission site routes [--project-dir <dir>]

Lists the custom and content routes known to the static site target. Use it when you add Markdown files, change sidebars, or register custom widget routes and want to confirm the generated URL set before building the site.

fission site check

fission site check [--project-dir <dir>] [--release]

Renders every static site route and validates generated internal links without producing a deployable output directory. This is the fastest command to use in pull-request checks for documentation and reference changes.

fission site build

fission site build [--project-dir <dir>] [--release]

Builds the static site into the output directory configured by [site].out_dir in fission.toml. For the Fission documentation site, that means documentation/dist/site. The build writes HTML, site.css, copied assets, optional search files, optional code-highlighting hooks, sitemap.xml, and robots.txt when those features are enabled.

fission site serve

fission site serve [--project-dir <dir>] [--host <host>] [--port <port>] [--release] [--no-open]

Builds the static site and serves the generated output with a local static file server. By default it binds to 127.0.0.1:8123 and opens the browser. Use --no-open for scripts or remote development environments.

fission server check

fission server check [--project-dir <dir>] [--release]

Builds route-local browser artifacts, runs the configured [server].entry, renders every declared server route, and fails if the route cannot produce HTML or a worker/island artifact cannot be generated.

fission server build

fission server build [--project-dir <dir>] [--release]

Builds the server app and the route-local browser artifacts declared by its workers and islands. Use this command when you want the same pre-deployment build that fission build --target server performs: first the worker/island WASM shims are generated and compiled, then the server binary is compiled.

fission server serve

fission server serve [--project-dir <dir>] [--host <host>] [--port <port>] [--release]

Builds route-local browser artifacts, then runs the server-rendered app locally. The default port is 8124.

fission server artifacts

fission server artifacts [--project-dir <dir>] [--release] [--no-compile]

Generates per-worker and per-island browser shim crates, then compiles them unless --no-compile is set.

fission package

fission package --target <target> --format <format> [--project-dir <dir>] [--release] [--json]

Packages an app or site into a release artifact manifest. Current relevant pairs include site/static, site/docker-image, server/docker-image, linux/run, macos/app, macos/pkg, windows/exe, windows/msi, windows/msix, android/apk, android/aab, and ios/ipa.

fission publish

fission publish --provider <provider> --artifact <artifact-manifest.json> [--site <profile>] [--track <track>] [--dry-run] [--yes]

Publishes a packaged artifact to the selected provider. fission distribute publish ... is still available, but publish is the direct command developers should reach for in normal release workflows.

Static site workflow

The site commands are for documentation, marketing, reference, blog, and other mostly-static routes. They are separate from fission run --target web, which launches an interactive web application. A site build starts from the same Fission widget model but resolves it ahead of time into crawlable HTML and CSS.

The Fission documentation site in documentation/ is the production example in this repository. It uses a custom home page widget, Markdown content routes, sidebars, a generated table of contents, light and dark themes, a custom footer, copied static assets, favicon support, generated search, optional code highlighting, route-filtered page elements, sitemap and robots output, JSON-LD structured data, and link validation. You can inspect the route set with:

fission site routes --project-dir documentation

Then check or build it with:

fission site check --project-dir documentation
fission site build --project-dir documentation

The generated output directory is build output, not source. Keep the site project, content, sidebars, assets, and Rust widgets in source control; publish the generated directory from continuous integration.

What the command-line interface does not do

The command-line interface does not explain the runtime model for you, choose your architecture, or replace platform documentation. It creates the shared scaffold and the host wrappers, but you still use the rest of the docs to understand how the app works and how each platform behaves.

If you are still learning the overall shape of a Fission app, read Quickstart and Runtime model next. If you are already working at the platform layer, continue to Targets.