CLI · Tier 1

Lifecycle

The five standard commands every workspace exposes — init / dev / build / preview / typecheck. Same shape as Vite or Astro, no openpress: prefix.

Tier 1 covers the everyday workspace loop: create one, develop in it, ship it, verify it. Each command below has a matching npm run script in the scaffolded package.json, so this is the surface most authors and CI scripts use.

Command Impl

# `init`

Create a new OpenPress workspace at <target>. Copies the framework runtime, patches metadata, installs the framework skill bundle, runs npm install + git init by default. Starter content (chapters, theme, components) is added by domain skills after init — not bundled in the CLI.

npx @open-press/cli init <target> [flags]

Positional + content flags

Name	Type	Default	Description
`<target>` required	`string`		Target directory — created if missing. Must be empty (a lone `.git/`, `.gitignore`, `.gitkeep`, or `.DS_Store` is fine — common when scaffolding into a fresh repo).
`--title`	`string`		Document title — written into `<Press title>` in `press/index.tsx`. Subtitle, organization, author, etc. are not CLI flags — render them directly in your Cover JSX.

Behavior flags

Name	Type	Default	Description
`--no-install`	`flag`		Skip the automatic `npm install` after template copy. Use when you're working offline, managing deps with pnpm/bun yourself, or scripting init from a parent monorepo.
`--no-git`	`flag`		Skip `git init` + the initial commit. Use when scaffolding inside an existing repo, or when your tooling manages git state separately.

Scaffold with title

npx @open-press/cli init my-paper \
  --title "Transport models in dense networks"

Scaffold into existing repo

# Inside an existing git repo, no auto-commit, manage deps yourself:
npx @open-press/cli init ./docs \
  --no-git \
  --no-install
pnpm install

Domain-specific starters (chapters, theme, components) are not bundled in the CLI. After init, install a domain skill (npx skills add <owner/repo>) and ask the agent to populate press/ from that skill's starter.

Command Impl

# `dev`

Start the local workbench at http://127.0.0.1:5173. Hot-reloads CSS, theme tokens, and React UI chrome; MDX content edits refresh through the engine's source watcher.

npm run dev

Start the workbench

npm run dev
# → workspace at http://127.0.0.1:5173/workspace
# → document preview at http://127.0.0.1:5173/<press-slug>/preview

The workbench uses path-based routes: /workspace for the project gallery and /<press-slug>/preview for a specific document preview with inspector, source-edit endpoint, and comment markers enabled.

Command Impl

# `build`

Produce the deploy-ready bundle in dist-react/. Chains source validation, MDX → React export, and Vite production build. If validation fails, the build aborts before Vite runs.

npm run build

Build for production

npm run build
# → dist-react/ ready to host

The intermediate engine steps (export, validate) exist for advanced callers but are not user-facing — they run automatically inside build. To validate without rendering, call open-press validate . directly; that's mostly a CI lint or agent preflight.

Command Impl

# `preview`

Serve dist-react/ as a static site without workbench chrome. Use to verify the public reader matches expectations before deploy.

npm run preview

Preview after build

npm run build
npm run preview
# → reader at http://127.0.0.1:4173 (no workbench)

Command Impl

# `typecheck`

Run TypeScript checks across the workspace tree. Literally tsc --noEmit -p tsconfig.json — catches type errors that the bundler doesn't surface (unused exports, prop mismatches, narrowed types broken by edits).

npm run typecheck

What it does NOT do: validate MDX content shape, resolve cross-section links, or check theme tokens — those belong to Tier 3 tools (validate, inspect). Typecheck is purely about TypeScript correctness.