CLI and Generators

The semitra CLI is the operational entrypoint for Semitra applications.

Core commands

The current CLI supports:

• semitra new [name]
• semitra dev [app-root|workspace-root]
• semitra console [app-root]
• semitra migrate [app-root]
• semitra db:migrate [app-root]
• semitra deploy [app-root]
• semitra test [app-root]
• semitra codegen [app-root]
• semitra generate <type> <name>

What each command does

• new creates a new Semitra workspace with apps/api and apps/web.
• dev runs the local Cloudflare dev environment. In a generated workspace, it runs both apps/api and apps/web concurrently unless --api-only is passed.
• console starts a REPL with the generated app and registries loaded.
• migrate applies pending D1 migrations through the configured binding.
• deploy runs remote migrations and then deploys the Worker.
• test prepares the app and runs Bun tests.
• codegen generates the Semitra manifest and bootstrap.
• generate creates conventional framework files.

Generators

The built-in generators include:

• model
• controller
• policy
• resource
• job
• channel
• mailer
• mailbox

New workspace output

semitra new [name] creates the opinionated full-stack shape:

apps/
  api/
  web/

apps/api is the Semitra Worker backend. apps/web is the React Router 7, Vite, and Tailwind frontend with a centralized API client in apps/web/app/lib/api.ts and frontend models in apps/web/app/models.

App-root resolution

If you omit [app-root], the CLI resolves:

• the nearest Semitra app
• or the single app inside ./apps

A Semitra app root is defined by convention. It must contain both config/routes.ts and src/index.ts.

For semitra dev, the nearest generated workspace containing apps/api and apps/web is treated as a full-stack dev target before app-root fallback.

Workspace commands in this repository

From the repository root:

bun run codegen
bun run dev
bun run migrate:local
bun run migrate:remote
bun test
bun run docs:dev
bun run docs:build

The docs scripts target the Astro/Starlight site in apps/docs.

CLI and docs release workflow

CLI changes are released from the local machine to the production registry and production docs site. The all-in-one command is:

bun run deploy

That command bumps the @semitra/cli package version with a patch SemVer increment by default, builds the package distribution, publishes it to the registry, builds the docs, and deploys the docs to Cloudflare Pages branch main.

Each stage can also run independently:

bun run version:bump
bun run version:bump -- --minor
bun run package:build
bun run package:deploy
bun run docs:build
bun run docs:deploy

Use --major or --minor with version:bump or the root deploy command when the release is not a patch update.

Example workflow

A typical CLI flow for a new Semitra app looks like this:

semitra new support-portal
cd support-portal
semitra generate model Post
semitra generate controller Posts
semitra generate policy Post
semitra generate resource Post
semitra codegen apps/api
bun run migrate:local
bun run dev

bun run dev delegates to semitra dev, which starts the generated API and frontend together. You can still run either side directly when needed:

bun run dev:api
bun run dev:web

bun run dev:api uses semitra dev --api-only so you still have a focused Worker-only path.

After the local app is working, the usual next steps are:

bun run test:api
bun run build:web
bun run deploy:api

That workflow matches the framework’s conventions: generate conventional files, regenerate the manifest, apply migrations, run the Worker locally, then test and deploy.