The CLI

The ossido binary drives everything: scaffolding, development, and production builds. Install it from npm (@ossido-labs/ossido-cli) or the ossido_cli crate - see Installation. This page covers each command.

ossido dev

Starts the development environment:

ossido dev

In one process, ossido dev:

• Scaffolds and generates code - builds the route tree and server entry into .ossido/.
• Generates TypeScript types - turns your Rust Type derives into .ts definitions your pages import.
• Compiles and bundles - the Rust server and the JS bundles.
• Serves with HMR - hot-reloads the browser as you edit, proxying Vite for fast client updates.

Leave it running while you work; it re-runs the relevant steps as files change:

• Editing a route component swaps the new version into the running app without a full page reload.
• Adding or removing a route swaps in the regenerated route tree. A new .rs route rebuilds and restarts the server; a deleted route stops being served after a hard refresh.
• Editing a .env file reloads it inside the running server, with no restart (see Environment Variables).

ossido build

Produces a production build:

ossido build

By default it uses the output mode from ossido.config.ts. You can override that mode per build, and control JavaScript emission:

• --static (-s) - statically generate the site's HTML (SSG), overriding the config.
• --server - build the standalone SSR server binary, overriding the config.
• --no-js-emit - skip emitting the client JavaScript bundle.
• --no-cargo - skip compiling the server binary (see below).
• --verbose (-v) - show the full output of Vite, cargo and the build hooks, including cargo's progress bar.

# Force a static build regardless of config
ossido build --static

# Force an SSR server build
ossido build --server

The two output modes produce different artifacts:

• Static - a folder of pre-rendered HTML and assets you can deploy to any static host.
• Server - a standalone binary that renders pages per request.

Compiling the server

For server output, ossido build also runs cargo build --release and finishes by reporting where the server binary is and how big it is. That release compile is the slowest part of a build, so if something else already compiles the binary - for example a CI job or a Dockerfile that runs its own cargo build --release - pass --no-cargo to skip it:

ossido build --server --no-cargo

Build output

The build prints a short checklist with a spinner per step: scaffolding, types, the app bundle, the server compile, and static generation. Once everything has finished, it prints the route tree and the emitted files.

prebuild and postbuild hook logs appear dimmed and indented under the checklist. In CI, or whenever output is piped, each step prints as a plain line instead of an animated spinner. Pass --verbose to see everything Vite and cargo print.

ossido new

Scaffolds a new project. This is covered in detail in Installation & project setup; in short:

ossido new my-app

It supports flags for every wizard option (--template, --tailwind, --mdx, --output, --alias, --head, --yes) so you can scaffold non-interactively. --template starts from one of the official examples, such as kitchen-sink or with-websockets. From a bare JS toolchain, npm create ossido@latest my-app wraps this same command (see Installation).

ossido doctor

Runs read-only diagnostics on your project and toolchain - Rust and Node/Bun versions, your installed CLI and package versions against the latest published, and common setup problems - then prints a pass / warn / fail report:

ossido doctor

It changes nothing and exits non-zero only on a hard failure, so it's useful in CI or when something just won't build.

• --offline - skip the network checks (the crates.io / npm latest-version lookups).

ossido upgrade

Bumps your project's ossido crate and @ossido-labs/* npm packages to a newer version - keeping the two runtimes aligned - and refreshes the lockfiles. Run it with no arguments for an interactive version picker:

ossido upgrade

• --version <x.y.z> - upgrade to a specific version (defaults to the latest published).
• --dry-run - report the planned change without touching any files.
• --yes (-y) - skip the confirmation prompt.
• --no-install - update the manifests but don't run cargo update or the package-manager install.

The generated .ossido/ directory

Both ossido dev and ossido build write to a .ossido/ directory at the project root. It contains generated code, including:

• the route tree derived from src/routes/, and
• the server entry that boots the axum app.

You don't edit anything in .ossido/ - it's regenerated from your source on every run, and hand edits are overwritten. Treat it as build output (and it's fine to keep it out of version control).

Back to Mental model & architecture · Installation & project setup