schemarch

The TypeScript/Bun Schemarch CLI in this repo.

This workspace contains:

• the published schemarch package
• the schemarch binary entrypoint
• local-development commands backed by @schemarch/stack
• login and machine-readable output support

Status

This workspace contains the stable, shipped schemarch CLI. Earlier revisions carried two shells (a legacy/ tree and an experimental next/ tree); both are gone and src/ is the single CLI tree.

For current migration/parity status, see:

• docs/go-cli-porting-status.md — the residual Go delegation surface
• docs/go-cli-divergences.md — TS-only flags and behavioral divergences from the old Go CLI

For the generated command/reference docs, see:

• docs/go-cli-reference.md
• docs/schemarch-home.md
• ../../packages/stack/docs/service-versioning.md

The README is intentionally brief. Command details should live in the generated docs and the parity tracker above.

Run From Source

From the workspace:

cd apps/cli
pnpm dev -- --help

Examples:

pnpm dev -- hello

CLI and the Go binary

Phase 0 commands in the CLI proxy to the Go CLI binary. To run these commands from source you need schemarch (the Go CLI) available on your PATH.

For convenience, create a shell alias instead of using pnpm dev directly. For example in .zshrc:

alias schemarch-dev="bun /absolute/path/to/dx-lab/apps/cli/src/main.ts"

Then Phase 0 commands resolve the Go binary via PATH automatically:

schemarch-dev orgs list   # proxied to schemarch on PATH
schemarch-dev login       # native TypeScript

You can also point SCHEMARCH_GO_BINARY at a specific binary to skip the PATH lookup:

export SCHEMARCH_GO_BINARY=/path/to/schemarch

Build

There are two separate build paths depending on what you need.

Source bundles (development)

From apps/cli:

pnpm build
pnpm build:binary
pnpm build:shim

Output in dist/:

• dist/schemarch.js — base shim that routes to the correct platform binary
• dist/schemarch — CLI compiled binary (Bun single-file executable for the host platform)

The shim resolves SCHEMARCH_CLI_BINARY_OVERRIDE (an absolute binary path) before falling back to the @schemarch/cli-<platform> optional-dependency lookup. The e2e test harness uses this override to invoke the real shim + compiled binary handoff against the per-shell builds in dist/.

Platform releases (Bun single-file executables)

Used at release time to produce the compiled binaries that go into the platform-specific npm packages:

# CLI (TS SFE + Go binary for each platform)
bun scripts/build.ts --version X.Y.Z

For the CLI, this also cross-compiles the Go CLI binary from apps/cli-go/ and places both binaries in packages/cli-{platform}/bin/.

See docs/binary-distribution.md for a full explanation of the packaging model.

Architecture

The CLI is built on effect/cli.

Important areas:

• src/shared/cli/ for shared runner logic and roots
• src/commands/ for the command tree
• src/shared/output/ for text / JSON / NDJSON output policies
• src/shared/runtime/ for TTY, stdin, browser, and process-control services
• src/auth/ for credential and platform API services; src/shared/auth/ keeps the JWKS and keyring helpers

The local stack commands use @schemarch/stack for lifecycle, status, logs, and runtime operations. Managed ownership uses stable loopback GET /owner and session-fenced POST /stop; same-version runtime calls use Effect RPC over framed NDJSON at POST /rpc. That stack layer now has an explicit preparation phase, so foreground and detached start flows can surface Downloading before normal runtime states. CLI-managed stacks use lazy service startup: direct listeners and Realtime start with the stack, while HTTP services activate on first proxied use. The package API itself keeps eager startup as its default.

Useful companion docs:

• ../../packages/stack/docs/architecture.md

Development

Repo-wide quality checks run from the repository root:

pnpm check:all
pnpm fix:all

Package-local checks and tests run from apps/cli:

pnpm types:check
pnpm test

Useful subsets:

pnpm run test:unit && pnpm run test:integration  # unit + integration (no binary required)
pnpm test:e2e                  # end-to-end subprocess tests

Publishing

This workspace publishes the main schemarch package.

Release channels are split by npm dist-tag:

• stable publishes the CLI to latest
• beta publishes the CLI to beta

The release automation lives in .github/workflows/release.yml.

Platform packages

Platform-specific packages live under:

• packages/cli-darwin-*
• packages/cli-linux-*
• packages/cli-windows-*

Each platform package ships two binaries for the stable channel:

• bin/schemarch — the compiled TypeScript SFE (Bun single-file executable)
• bin/schemarch-go — the compiled Go CLI binary, used by Phase 0 proxy commands

The Go binary is compiled from apps/cli-go/ at release time. Run pnpm repos:install after a fresh clone to make that source available.

See docs/binary-distribution.md for the full packaging model.