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 root, it runs both apps/api and apps/web concurrently.
• 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, a generated workspace root 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.

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

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.