cli — API Reference

API reference for the cli package.

Functions & Classes

Symbol	Kind	Description
`configureLogger()`	function	Configures the global `forgeLogger` based on CLI flags. Call this once at th...
`emitResult()`	function	Wraps a command result in a LAFS envelope and emits it. Output format is det...
`resolveExitCode()`	function	Returns the LAFS-compliant exit code for a command output.
`runAudit()`	function	Reads the audit log and returns a typed command output.
`runBarometer()`	function	Runs the barometer generation pass. Loads the project config, walks the symb...
`runBarometerScore()`	function	Scores agent answers against the barometer answer key.
`runBuild()`	function	Runs the full build pipeline and returns a typed command output.
`runBypassCreate()`	function	Runs the bypass creation: creates a new bypass record with budget enforcement.
`runBypassStatus()`	function	Runs the bypass status query: shows active bypasses and remaining budget.
`getStagedFiles()`	function	Returns the list of staged .ts/.tsx files (relative paths) by querying git. R...
`runCheck()`	function	Runs the TSDoc enforcement pass and returns a typed command output.
`runDocsDev()`	function	Starts the local dev server for the configured SSG target. Reads...
`readPkgJson()`	function	Read and parse package.json from a project root. Detects indent style and tr...
`serializePkgJson()`	function	Serialize a package.json object preserving original formatting.
`writePkgJson()`	function	Write a modified package.json back to disk, preserving formatting.
`addScripts()`	function	Add scripts to package.json idempotently. Only adds scripts where the key do...
`detectHookManager()`	function	Detects which hook manager is present in the project. Checks for: - husky:...
`generateHuskyHook()`	function	Generates the husky pre-commit hook file content (modern husky v9+).
`generateHuskyPrePushHook()`	function	Generates the husky pre-push hook file content (modern husky v9+).
`generateLefthookBlock()`	function	Generates the lefthook block with both pre-commit and pre-push sections.
`detectVersionGuard()`	function	Checks whether a versionguard config file exists in the project root. When d...
`runInitHooks()`	function	Scaffolds git hook integration for the project. Detects the hook manager (hu...
`detectEnvironment()`	function	Detects the project environment by checking for files and dependencies.
`buildTsdocContent()`	function	Builds tsdoc.json content, merging in customTags from the forge config. When...
`runInitProject()`	function	Runs the full project init flow.
`runDoctor()`	function	Runs the doctor integrity check flow.
`runInitDocs()`	function	Scaffolds a documentation site for the target SSG platform. Resolves the tar...
`runLock()`	function	Runs the lock command: reads current config and creates `.forge-lock.json`.
`runPrepublish()`	function	Runs the prepublish safety gate: check then build. If the check step fails,...
`runTest()`	function	Runs the doctest pipeline and returns a typed command output.
`runUnlock()`	function	Runs the unlock command: removes `.forge-lock.json` with a mandatory reason.

Types & Interfaces

Symbol	Kind	Description
`ForgeLoggerOptions`	interface	Options for configuring the forge-ts logger at CLI startup.
`CommandOutput`	interface	Typed result from a forge-ts command.
`ForgeCliError`	interface	Structured error for CLI commands.
`ForgeCliWarning`	interface	Structured warning for CLI commands.
`OutputFlags`	interface	Output format flags passed through from citty args.
`AuditArgs`	interface	Arguments for the `audit` command.
`AuditResult`	interface	Typed result for the `audit` command.
`BarometerSource`	interface	Source provenance for a barometer question.
`BarometerQuestion`	interface	A single barometer question with its ground-truth answer.
`BarometerRatingBand`	interface	A single rating band in the barometer scoring rubric.
`BarometerInstructions`	interface	Agent instructions included in `--questions-only` output.
`BarometerResult`	interface	Full barometer output written to `.forge/barometer.json`.
`BarometerScoredAnswer`	interface	A single scored answer in the barometer score output.
`BarometerScoreResult`	interface	Full barometer score output.
`BarometerArgs`	interface	Arguments for the `barometer` command.
`BuildArgs`	interface	Arguments for the `build` command.
`BuildStep`	interface	A single step in the build pipeline.
`BuildResult`	interface	Typed result for the `build` command.
`BypassCreateResult`	interface	Typed result for the `bypass` command when creating a bypass.
`BypassStatusResult`	interface	Typed result for the `bypass --status` command.
`CheckArgs`	interface	Arguments for the `check` command.
`CheckFileError`	interface	A single error entry within a file group.
`CheckFileWarning`	interface	A single warning entry within a file group.
`CheckFileGroup`	interface	Errors and warnings grouped by file.
`CheckRuleCount`	interface	Error breakdown by rule code, sorted by count descending.
`CheckTriage`	interface	Triage data for prioritizing fixes. Always present when the check has errors,...
`CheckPage`	interface	Pagination metadata for byFile results.
`CheckResult`	interface	Typed result for the `check` command.
`PkgJson`	interface	Parsed package.json with formatting metadata for lossless round-tripping.
`HookManager`	type	Detected hook manager in the project.
`InitHooksResult`	interface	Result of the `init hooks` command.
`InitHooksArgs`	interface	Arguments for the `init hooks` command.
`InitProjectEnvironment`	interface	Detected project environment from Step 1 of the init flow.
`InitProjectResult`	interface	Result of the `init` (project setup) command.
`InitProjectArgs`	interface	Arguments for the `init` (project setup) command.
`DoctorCheckStatus`	type	Status of a single doctor check.
`DoctorCheckResult`	interface	Result of a single doctor check.
`DoctorResult`	interface	Result of the `doctor` command.
`DoctorArgs`	interface	Arguments for the `doctor` command.
`InitDocsResult`	interface	Result of the `init docs` command.
`InitDocsArgs`	interface	Arguments for the `init docs` command.
`LockResult`	interface	Typed result for the `lock` command.
`PrepublishResult`	interface	Typed result for the `prepublish` command.
`PrepublishArgs`	interface	Arguments for the `prepublish` command.
`TestArgs`	interface	Arguments for the `test` command.
`TestFailure`	interface	A single test failure entry, included at standard and full MVI levels.
`TestResult`	interface	Typed result for the `test` command.
`UnlockResult`	interface	Typed result for the `unlock` command.

Other Exports

Symbol	Kind	Description
`tsup.config.ts`	file
`forgeLogger`	variable	Pre-configured consola instance branded for forge-ts.
`forge-logger.ts`	file	Forge-ts branded logger built on consola from the UnJS ecosystem. Provides a...
`output.ts`	file	Central output layer for forge-ts CLI. Wraps all command results in LAFS env...
`auditCommand`	variable	Citty command definition for `forge-ts audit`.
`audit.ts`	file	CLI command for reading the forge-ts audit trail. Reads `.forge-audit.jsonl`...
`barometerCommand`	variable	Citty command definition for `forge-ts barometer`. Generates a documentation...
`barometer.ts`	file	`forge-ts barometer` command — documentation effectiveness test generator. A...
`buildCommand`	variable	Citty command definition for `forge-ts build`.
`build.ts`	file
`bypassCommand`	variable	Citty command definition for `forge-ts bypass`.
`bypass.ts`	file	`forge-ts bypass` command — create or inspect temporary rule bypasses. Bypas...
`checkCommand`	variable	Citty command definition for `forge-ts check`.
`check.ts`	file
`docsDevCommand`	variable	Citty command definition for `forge-ts docs dev`.
`docs-dev.ts`	file	The `forge-ts docs dev` command — starts a local doc preview server. Reads t...
`pkg-json.ts`	file	Shared utilities for idempotent package.json read-modify-write operations. E...
`initHooksCommand`	variable	Citty command definition for `forge-ts init hooks`. Scaffolds git hook integ...
`init-hooks.ts`	file	`forge-ts init hooks` command — scaffolds git hook integration. Detects husk...
`initProjectCommand`	variable	Citty command definition for `forge-ts init` (bare — full project setup). De...
`init-project.ts`	file	`forge-ts init` command — full project setup. Detects the project environmen...
`doctorCommand`	variable	Citty command definition for `forge-ts doctor`. Performs project integrity c...
`doctor.ts`	file	`forge-ts doctor` command — project integrity check and repair. Validates th...
`initDocsCommand`	variable	Citty command definition for `forge-ts init docs`. Scaffolds a complete docu...
`initCommand`	variable	Citty command definition for `forge-ts init`. Exposes subcommands for scaffo...
`init-docs.ts`	file
`lockCommand`	variable	Citty command definition for `forge-ts lock`.
`lock.ts`	file	`forge-ts lock` command — snapshots the current config and creates...
`prepublishCommand`	variable	Citty command definition for `forge-ts prepublish`. Runs check then build as...
`prepublish.ts`	file	`forge-ts prepublish` command — safety gate for npm publish. Runs...
`testCommand`	variable	Citty command definition for `forge-ts test`.
`test.ts`	file
`unlockCommand`	variable	Citty command definition for `forge-ts unlock`.
`unlock.ts`	file	`forge-ts unlock` command — removes `.forge-lock.json` with a mandatory reaso...
`index.ts`	file	Unified command-line interface for the forge-ts toolchain. Provides the...
`cli.test.ts`	file
`doctor.test.ts`	file
`init-docs.test.ts`	file
`init-hooks.test.ts`	file
`init-project.test.ts`	file
`prepublish.test.ts`	file

cli — API Reference

Functions & Classes

Types & Interfaces

Other Exports

On this page