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.

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.

# 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.

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. 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