Getting started

Once UI CLI

Create a Stack app from the surfaces you pick, without cloning the repo.

@once-ui-system/cli creates a Stack app from the surfaces you pick and adds Once UI blocks to an existing project. It needs Node 20 or newer, and you don't need a copy of this repository.

Create an app

Bash

npx @once-ui-system/cli create my-app --surfaces landing,docs
npx @once-ui-system/cli create my-app --surfaces dashboard --slices billing

--surfaces: surface ids, separated by commas. If you leave it out, the CLI lists the surfaces your plan includes and asks which ones you want.
--slices: extra slices to include beyond the ones your surfaces require. Use it for billing, which no surface requires.
--name: the package name. Defaults to the directory name.
--url: the site's canonical URL.

The target directory must be empty or must not exist yet. Then run:

Bash

cd my-app
npm install
npm run dev

The app is built on the server

create sends your choices to once-ui.com/api/stack/scaffold. The server checks your plan, runs the Stack scaffolder and streams the finished app back as a tarball, which the CLI unpacks into the directory. The CLI never sees the Stack repository or the scaffolder. The docs surface is free and works without signing in. Other surfaces need a plan that includes them. If your plan is missing one, the server tells you which.

Other commands

list: shows the surfaces and slices in the current Stack release, marks the ones you own, and shows which slices each one needs.
login: saves an access token from once-ui.com/account/tokens. You can pass it with --token oui_…, pipe it in, or paste it when prompted. The token is checked before it is saved. ONCE_UI_TOKEN overrides the saved token.
logout: removes the saved token. It still exists on the server, so revoke it on the tokens page.
add <block…>: writes the blocks you name and every block they import into your project, then installs any missing npm packages. Existing files are skipped unless you pass --overwrite. Pass --no-install to skip the install.

If you install it globally with npm install -g @once-ui-system/cli, the command is once-ui.

If you have the repo

If you have a clone of Stack, run the scaffolder directly:

Bash

node scripts/scaffold.mjs --surfaces landing,docs --out ../my-site

It reads the same manifests, works offline, and has flags the CLI doesn't expose: --targets for mobile and desktop shells, --dry-run to see the plan before anything is written, and --force to overwrite an existing directory. See Scaffolding.

Last updated October 18, 2026

Edit this page on GitHub