Skip to content

Development ​

Commands you'll run dozens of times a day while building.

orion dev ​

Run your app locally and let the host EMR iframe it for live preview. The CLI starts a Vite dev server, opens a Cloudflare tunnel, and registers the tunnel with your sandbox tenant.

bash
orion dev

The CLI prints the local Vite URL, the resolved tunnel URL, and registers the tunnel with your sandbox tenant. Save a file in your editor to trigger HMR inside the iframe.

Flags ​

FlagDefaultPurpose
-p, --port <port>5173Dev server port.
--no-tunnel—Skip the tunnel. Only useful if you've configured the sandbox to reach localhost directly (rare).

The CLI bundles cloudflared via the npm cloudflared dev dependency and invokes that binary directly. There's a --tunnel-provider flag that's parsed for forward compatibility, but cloudflared is the only provider currently wired through.

Requires ​

orion config sandbox must be set. orion dev won't fall back to the home tenant — this is intentional, so dev code never runs against your home tenant. See Host vs Sandbox.


orion build ​

Run your production build into dist/.

bash
orion build

Flags ​

FlagDefaultPurpose
-o, --out-dir <dir>distOutput directory. Override only if your vite.config.ts already does.
--no-minify—Disable minification (useful when chasing a stack trace through the bundle).
--sourcemap—Emit source maps.

orion validate ​

Run all the checks orion publish runs, but stop before authentication and upload — manifest schema, bundle layout, scope rules, archive forbidden-paths. Catches issues early so you fix them before authentication and upload.

bash
orion validate

The CLI prints one section per check group (Manifest (orion-app.json), Bundle (dist/index.js), Source archive) followed by a summary line — 0 problems found., 0 problems, 1 warning., or 2 problems, 0 warnings.

publish runs validate too — running it explicitly during development gives you faster feedback.

Schema checks include the extensions.writableExtensions block when present: required fields (key, title, valueType, appliesTo), kebab-case key shape, the 9-value-type allow-list, duplicate keys across entries, and the 50-entry manifest cap. Mismatches surface with the offending index and field name — fix in orion-app.json and rerun.

Flags ​

FlagPurpose
--manifestValidate the manifest only; skip bundle + source-archive checks. Useful for checking a manifest before npm run build.
--jsonEmit findings as newline-delimited JSON, one record per line. CI-friendly.

orion doctor ​

Environment + manifest health check. Validates Node/npm versions, working-directory config, manifest shape, build artifacts, and (optionally) network reachability of the host tenant.

bash
orion doctor

Sections checked: Environment, Authentication (local), Working directory, Manifest, Build, and (with --network) Identity. Each check is ✓ (pass), ! (warn), or ✗ (fail). A ✗ exits non-zero.

Flags ​

FlagPurpose
--jsonMachine-readable JSON output for CI scripting.
--networkOpt-in remote-identity verification. Otherwise the doctor stays local-only.

orion generate <kind> <id> ​

Aliased as orion g. Scaffold a new extension into the current app — manifest entry plus the corresponding source file. The available mount points, triggers, and placements match what the host EMR currently supports.

bash
orion generate page reports --path /reports
orion generate block status-bar --target encounter-detail/status-bar --action after
orion generate widget patient-vitals --mount-point patient-detail-sidebar
orion generate action send-summary --trigger patient-context-menu
orion generate nav reports --placement sidebar --path /reports --icon FileText

Kinds ​

KindRequired flagsOptional flags
page <id>—--path <path> (default /<id>), --layout app|fullscreen|modal (default app)
block <id>--target <name>--action before|after (default before)
widget <id>--mount-point <slot>—
action <id>--trigger <name>—
nav <id>--placement <name>, --path <path>--icon <lucide-icon> (default LayoutDashboard)

All subcommands accept --force to skip catalog/collision/overwrite checks.

For the field shape of each manifest entry generate writes (and how to hand-edit one), see Manifest schema.

Listing the catalog ​

To see which tokens are valid for --target, --mount-point, --trigger, and --placement without having to guess and read the rejection error, use:

bash
orion generate list              # all four catalogs, grouped
orion generate list block        # just block targets
orion generate list widget       # just widget mount points
orion generate list action       # just action triggers
orion generate list nav          # just nav placements
orion generate list --json       # machine-readable output

The values match what the host EMR currently supports. Drift here is a bug — file an issue if your dev server accepts a token list doesn't print, or vice versa.

What it writes ​

For each invocation, generate writes two things:

  • An entry under the matching extensions.pages[] / extensions.blocks[] / extensions.widgets[] / extensions.actions[] / extensions.navigation[] array in orion-app.json.
  • A starter source file in the matching plural directory (src/pages/, src/blocks/, src/widgets/, src/actions/, or src/nav/) named <PascalCaseId>.tsx (.ts for actions). The generator also adds an import for the new component to your entry file (src/main.tsx or equivalent) — wire the route or mount manually.

Kind reference ​

Five extension kinds, each with its own host surface and scaffolded shape. The table at the top of this section gives the quick syntax; the entries below cover what each kind is, where the host renders it, and what the generator drops on disk.

For the full manifest field shape of each kind, see Manifest schema.

Page (page) — full-page extension that owns a route

A full-page extension that owns a route inside the host EMR. The host renders your component edge-to-edge inside the app frame when the user navigates to the path you declared.

When to use it: anything that needs its own dedicated screen — dashboards, list views, settings panels.

orion generate page reports --path /reports writes:

  • extensions.pages[] entry: { id, path, title, component, layout } (layout is app | fullscreen | modal, defaults to app).
  • src/pages/Reports.tsx — a Reports() component returning a centered Card with a "Get started" placeholder and a Button. The component uses @orion-ehr/ui primitives so it matches the host's design tokens out of the box.

Wiring: on the legacy template the generator also writes the createPage(ReportsComponent) registration into your entry file; on the SMART template it prints the JSX snippet to paste into mount().

Block (block) — small inline component injected into a host slot

A small inline component injected into one of the host's named slots — typically a row of metadata on a detail screen (encounter status bar, patient sidebar header, case overview stats). The host renders your component before or after the slot's own content; multiple blocks from different apps stack at the same slot.

When to use it: in-context additions that should sit next to existing host UI rather than take over a screen.

orion generate block status-bar --target encounter-detail/status-bar --action after writes:

  • extensions.blocks[] entry: { id, target, action, component } (action is before | after, defaults to before).
  • src/blocks/StatusBar.tsx — a Card-wrapped component with the slot path captured in the file's doc-block so you can grep your way back to the manifest.

Discover valid --target values with orion generate list block — the host publishes a fixed catalog of slots; arbitrary strings are rejected.

Widget (widget) — persistent panel rendered in a fixed host region

A persistent panel rendered in a fixed host region: the patient detail sidebar, the dashboard widgets row, an appointment sidebar. Unlike a block (which annotates an existing row), a widget owns its container.

When to use it: panels that should be visible while the user is in a host context — quick reference data, action shortcuts, embedded charts.

orion generate widget patient-vitals --mount-point patient-detail-sidebar writes:

  • extensions.widgets[] entry: { id, mountPoint, title, component }.
  • src/widgets/PatientVitals.tsx — a Card with the widget's title and a body placeholder.

Discover valid --mount-point values with orion generate list widget. Two widgets at the same mount point stack vertically in declaration order.

Action (action) — headless handler invoked from a menu, palette, or toolbar

A headless handler invoked from a host menu, command palette pick, or toolbar press. Actions don't render UI themselves — they expose a default-exported async function the host calls when the trigger fires. The host owns presentation (the menu row label, the palette icon, the toolbar position); your code owns the behavior.

When to use it: behaviors attached to a host UI surface — "export this patient's record," "send to fax queue," "fire a workflow." Use a block or widget if you need to draw anything.

orion generate action send-summary --trigger patient-context-menu writes:

  • extensions.actions[] entry: { id, trigger, title, handler }.
  • src/actions/SendSummary.ts (note: .ts, not .tsx) — an async SendSummary(ctx) function with a typed Context interface declaring the optional ids the trigger carries (e.g. patientId, appointmentId).

Discover valid --trigger values with orion generate list action.

Nav (nav) — link in the sidebar, header, settings, or patient-actions menu

A navigation entry — a link in the sidebar, header, settings menu, or patient-actions menu that routes to a path. The host owns the rendering; you provide the placement, target path, and icon.

When to use it: every time you want users to be able to reach a page you've built. Nav entries pair naturally with generate page (see the sidebar-navigated page recipe).

orion generate nav reports --placement sidebar --path /reports --icon FileText writes:

  • extensions.navigation[] entry: { id, title, icon, placement, target } (the manifest field is target; the CLI flag is --path for readability).
  • src/nav/Reports.tsx — a stub component returning null. Nav entries are almost always pure manifest data; the file exists so the manifest's optional component reference still resolves at build time.

Discover valid --placement values with orion generate list nav. --icon accepts any Lucide icon name (defaults to LayoutDashboard).

Documents @orion-ehr/cli v0.0.16 — released under the MIT License.