UCD.js Docs

CLI

Architecture notes for @ucdjs/cli

@ucdjs/cli is the human-facing command layer for store, files, lockfile, codegen, and pipeline workflows.

Role

  • Parses raw terminal arguments into command groups and subcommands.
  • Delegates real work to package-level APIs instead of re-implementing storage or pipeline logic.
  • Owns terminal output formatting, JSON mode, and command help text.

Public Package Docs

User-facing overview of commands and usage.

UCD Store

Store commands wrap store initialization, mirror, sync, and verify flows.

Lockfile

Lockfile commands validate and inspect store metadata.

Pipelines

Pipeline commands load, list, and execute pipeline definitions.

Mental Model

The CLI is a thin dispatcher:

  • bin/ucd.js passes process.argv into runCLI()
  • parseFlags() and resolveCommand() identify the top-level command
  • runCommand() lazy-loads the relevant command root
  • subcommand modules call the real package APIs and render terminal output

Method Flows

CLI startup

runCommand()resolveCommand()parseFlags()runCLI()bin/ucd.jsrunCommand()resolveCommand()parseFlags()runCLI()bin/ucd.jsUserucd store sync --jsonrunCLI(process.argv.slice(2))parse raw argsflagsresolve top-level command"store"runCommand("store", flags)dynamic import of store rootformatted result or CLIErrorUser

Command dispatch

target package APIsubcommand modulecommand root modulerunCommand()target package APIsubcommand modulecommand root modulerunCommand()CallerrunCommand(cmd, flags)import ./cmd/<group>/rootresolve subcommand from flags._[1]invoke subcommand runnercall package APIresult or errorformatted terminal outputCaller

Help and version fast path

runCommand()runCommand()alt[--version][no valid command or --help]Userucd --versionprint package versionucd helprender help tables and usage textUser

Design Notes

  • Top-level command modules are lazy-loaded so the startup path stays small.
  • The CLI is intentionally a composition layer; storage, pipeline, and lockfile behavior should live in their own packages.
  • JSON mode is handled in output helpers so commands can share the same rendering rules.
  • Errors should be normalized into user-readable CLI output instead of leaking package stack traces by default.

Testing Use

  • top-level command resolution
  • help and version output
  • delegation to command roots and subcommands
  • JSON output mode
  • package-error normalization for store, lockfile, and pipeline commands

Overview

Architecture notes for each package in the monorepo

Client

Architecture notes for @ucdjs/client

On this page

RoleRelated DocsMental ModelMethod FlowsCLI startupCommand dispatchHelp and version fast pathDesign NotesTesting Use