CLI reference

omnifs ships as a single binary with five commands. Install once, configure providers in omnifs.toml, mount, and read.

Install

npm install -g @0xff-ai/omnifs

Installs the omnifs binary globally. Requires Node 18 or later. The binary bundles the host runtime and the FUSE layer; no separate daemon is needed.

Verify the installation:

omnifs --version

omnifs mount

Mount a configured set of providers at a local path.

omnifs mount [--config <file>] [--mountpoint <path>] [--foreground]

Flag	Default	Description
--config	./omnifs.toml	Path to the provider configuration file.
--mountpoint	/omnifs	Directory to mount the filesystem at. The directory must exist.
--foreground	off	Keep the process in the foreground. Useful for seeing log output. Ctrl-C unmounts.

The mount reads provider credentials from the environment and from omnifs.toml. Each configured provider appears as a top-level directory under the mountpoint.

omnifs mount --mountpoint /omnifs --foreground

ls /omnifs
# github  docker  linear  arxiv  dns
cat /omnifs/github/acme/api/_issues/_open/2853/title
# Auth tokens expire mid-session

To unmount:

umount /omnifs

Note

On macOS, you may need macFUSE installed separately. On Linux, libfuse3 must be present.

omnifs dev

Run a local dev mount that loads a single provider WASM component directly, without a full omnifs.toml. Intended for provider development and testing.

omnifs dev <component.wasm> [--mountpoint <path>] [--name <provider-name>]

Flag	Default	Description
<component.wasm>	required	Path to the compiled provider WASM component.
--mountpoint	/omnifs-dev	Directory to mount the dev filesystem at.
--name	derived from the component filename	Provider name used as the top-level directory.

The dev mount reloads the component on each request, so you can recompile and immediately observe the change without unmounting.

omnifs dev target/wasm32-wasip2/debug/omnifs_provider_acme.wasm --name acme
ls /omnifs-dev/acme
cat /omnifs-dev/acme/widgets/_all

omnifs init

Scaffold a new provider crate from the canonical template.

omnifs init <name>

Creates a directory <name>/ containing:

<name>/
├── Cargo.toml
├── src/
│   └── lib.rs
└── wit/
    └── provider.wit

The scaffolded lib.rs implements the three ops from omnifs:provider@1.0.0 as stubs: lookup-child, list-children, and read-file. The wit/provider.wit file contains the exact interface definition the host runtime expects.

omnifs init my-provider
cd my-provider
# edit src/lib.rs, then build

omnifs build

Compile a provider crate to wasm32-wasip2.

omnifs build [--release]

Flag	Default	Description
--release	off	Build with optimizations. Recommended before publishing a provider.

omnifs build is a thin wrapper around cargo build --target wasm32-wasip2. It requires the wasm32-wasip2 target to be installed:

rustup target add wasm32-wasip2

Run from inside the provider crate directory:

target/wasm32-wasip2/release/my_provider.wasm

cd my-provider
omnifs build --release

The resulting .wasm file is a self-contained component. Point omnifs dev at it to test locally, or reference it in omnifs.toml to include it in a full mount.

Tip

If you prefer to invoke cargo directly, cargo build --target wasm32-wasip2 produces the same output. omnifs build adds no flags beyond the target triple.