create-semaphor-app

Create a Semaphor Data App starter project.

npx create-semaphor-app@latest

The CLI scaffolds the public Semaphor Data App Starter, installs local dependencies by default, and can optionally install or update the Semaphor Agent Plugin for detected Codex and Claude Code installations. The starter already includes the Semaphor-specific Data App components and local samples used by agents for first-run dashboard quality.

It does not authenticate to Semaphor, write tokens, or choose a project/domain. The Semaphor Agent Plugin handles OAuth, project selection, runtime token minting, planning, code generation, validation, save, and publish.

Usage

npx create-semaphor-app@latest [app-name]

When app-name is omitted, the CLI creates ./semaphor-data-app.

Options:

--no-install              Skip dependency installation.
--package-manager <name>  Use npm, pnpm, yarn, or bun. Defaults to detected npm.
--skip-plugin             Skip Codex/Claude plugin install prompts.
--install-codex-plugin    Install the Codex plugin without prompting.
--install-claude-plugin   Install the Claude Code plugin without prompting.
--template <source>       Starter source. Defaults to the public starter repo.
--template-ref <ref>      Git branch/tag for the default starter repo. Defaults to main.
--shadcn-preset <preset>  Apply a shadcn preset after scaffolding.
--shadcn-base <base>      Pass base or radix to shadcn init when using a preset.
--yes                     Use noninteractive defaults; skip optional plugin installs unless explicit.
--help                    Show help.

shadcn Presets

The starter ships with a working shadcn setup. For teams that bring their own style, pass a shadcn preset during creation:

npx create-semaphor-app@latest my-app --shadcn-preset <preset-id>

--shadcn-preset runs the shadcn CLI. To skip installs entirely, pass --no-install, then run dependency and shadcn commands manually later if needed.

Included Semaphor Components

The generated starter includes Semaphor-specific source components under src/components/semaphor/* and browsable local samples at /samples. The components are normal app source files, not a separate runtime package:

• query loading/error/empty/success states;
• SDK-shaped query state boundaries;
• view cards with scoped filter affordances;
• metric KPI and multi-measure KPI helpers;
• filter controls;
• server-backed tables;
• matrix/pivot tables.

This keeps the default scaffold fast and avoids shadcn overwrite prompts for Semaphor components. Customers can still customize shadcn primitives or apply a preset, but the default path does not require installing a second component registry.

Local Validation

npm test

The smoke test creates temporary projects under the OS temp directory, verifies the local and default starter scaffold paths, exercises fake Codex and Claude plugin installation/update paths without touching real agent installs, and removes the temporary projects before exiting.

After creation:

cd semaphor-data-app
npm run dev

For Codex OAuth, run:

codex mcp login semaphor

For Claude Code OAuth, start Claude Code and run the interactive MCP flow:

claude
/mcp

Then complete auth for the semaphor server.

After Semaphor auth, ask your agent:

@semaphor Build a Data App from my Semaphor project.