cli — Examples
Usage examples for the cli package
All usage examples from the package, aggregated for quick reference.
forgeLogger
Pre-configured consola instance branded for forge-ts.
import { forgeLogger } from "./forge-logger.js";
forgeLogger.info("Checking 42 files...");
forgeLogger.success("All checks passed");
forgeLogger.warn("Deprecated import detected");
forgeLogger.error("Build failed");
forgeLogger.debug("Resolved config from forge-ts.config.ts");configureLogger()
Configures the global forgeLogger based on CLI flags. Call this once at the start of a command's run() handler to align consola's output level with the user's intent: - quiet or json sets level to 0 (silent) so only LAFS output appears. - verbose sets level to 4 (debug) for maximum detail. - Default level is 3 (info) which covers info, warn, error, and success.
import { configureLogger, forgeLogger } from "./forge-logger.js";
configureLogger({ quiet: args.quiet, json: args.json, verbose: args.verbose });
forgeLogger.info("This respects the configured level");emitResult()
Wraps a command result in a LAFS envelope and emits it. Output format is determined by LAFS flag resolution: - TTY terminals default to human-readable output. - Non-TTY (piped, CI, agents) defaults to JSON. - Explicit --json or --human flags always take precedence. On failure, the full result is included alongside the error so agents get actionable data (e.g., suggestedFix) in a single response.
import { emitResult } from "@forge-ts/cli/output";
emitResult(output, { human: true }, (data) => `Done: ${data.summary.duration}ms`);runAudit()
Reads the audit log and returns a typed command output.
import { runAudit } from "@forge-ts/cli/commands/audit";
const output = await runAudit({ cwd: process.cwd(), limit: 10 });
console.log(output.data.count); // number of events returnedrunBarometer()
Runs the barometer generation pass. Loads the project config, walks the symbol graph, extracts testable facts from five categories, generates questions with ground-truth answers, and writes the result to .forge/barometer.json.
import { runBarometer } from "@forge-ts/cli/commands/barometer";
const output = await runBarometer({ cwd: process.cwd() });
console.log(`Generated ${output.data.questions.length} questions`);runBarometerScore()
Scores agent answers against the barometer answer key.
import { runBarometerScore } from "@forge-ts/cli/commands/barometer";
const output = await runBarometerScore({ answersPath: "answers.json" });
console.log(`Score: ${output.data.score}%`);barometerCommand
Citty command definition for forge-ts barometer. Generates a documentation effectiveness test (questions + answers + rubric) from the project's source code. Includes a score subcommand for evaluating agent answers.
import { barometerCommand } from "@forge-ts/cli/commands/barometer";
// Registered as a top-level subcommand of `forge-ts`runBuild()
Runs the full build pipeline and returns a typed command output.
import { runBuild } from "@forge-ts/cli/commands/build";
const output = await runBuild({ cwd: process.cwd() });
console.log(output.success); // true if all steps succeededrunBypassCreate()
Runs the bypass creation: creates a new bypass record with budget enforcement.
import { runBypassCreate } from "@forge-ts/cli/commands/bypass";
const output = await runBypassCreate({
cwd: process.cwd(),
reason: "hotfix for release",
rule: "E009",
});
console.log(output.data.remainingBudget);runBypassStatus()
Runs the bypass status query: shows active bypasses and remaining budget.
import { runBypassStatus } from "@forge-ts/cli/commands/bypass";
const output = await runBypassStatus({ cwd: process.cwd() });
console.log(output.data.activeBypasses.length);runCheck()
Runs the TSDoc enforcement pass and returns a typed command output.
import { runCheck } from "@forge-ts/cli/commands/check";
const output = await runCheck({ cwd: process.cwd() });
console.log(output.data.summary.errors); // number of TSDoc errors foundrunDocsDev()
Starts the local dev server for the configured SSG target. Reads gen.ssgTarget from the forge-ts config, resolves the adapter, and spawns the platform's dev server in the output directory.
import { runDocsDev } from "@forge-ts/cli";
await runDocsDev({ cwd: "./my-project" });docsDevCommand
Citty command definition for forge-ts docs dev.
import { docsDevCommand } from "@forge-ts/cli";InitHooksResult
Result of the init hooks command.
import { runInitHooks } from "@forge-ts/cli/commands/init-hooks";
const output = await runInitHooks({ cwd: process.cwd() });
console.log(output.data.hookManager); // "husky" | "lefthook" | "none"detectHookManager()
Detects which hook manager is present in the project. Checks for: - husky: .husky/ directory or husky in package.json devDependencies - lefthook: lefthook.yml or lefthook in package.json devDependencies
import { detectHookManager } from "@forge-ts/cli/commands/init-hooks";
const manager = detectHookManager("/path/to/project");
console.log(manager); // "husky" | "lefthook" | "none"detectVersionGuard()
Checks whether a versionguard config file exists in the project root. When detected, forge-ts appends versionguard's hook lines to the generated hook files so both tools run cooperatively.
import { detectVersionGuard } from "@forge-ts/cli/commands/init-hooks";
if (detectVersionGuard("/path/to/project")) {
console.log("VersionGuard detected — adding cooperative hooks");
}runInitHooks()
Scaffolds git hook integration for the project. Detects the hook manager (husky or lefthook), generates appropriate hook files, and reports what was written.
import { runInitHooks } from "@forge-ts/cli/commands/init-hooks";
const output = await runInitHooks({ cwd: "/my/project" });
console.log(output.data.files); // [".husky/pre-commit"]initHooksCommand
Citty command definition for forge-ts init hooks. Scaffolds git hook integration for the project by detecting the hook manager (husky or lefthook) and generating pre-commit hooks.
import { initHooksCommand } from "@forge-ts/cli/commands/init-hooks";
// Registered as a subcommand of `forge-ts init`InitProjectResult
Result of the init (project setup) command.
import { runInitProject } from "@forge-ts/cli/commands/init-project";
const output = await runInitProject({ cwd: process.cwd() });
console.log(output.data.created); // list of created filesrunInitProject()
Runs the full project init flow.
import { runInitProject } from "@forge-ts/cli/commands/init-project";
const output = await runInitProject({ cwd: process.cwd() });
console.log(output.data.created); // ["forge-ts.config.ts", "tsdoc.json"]initProjectCommand
Citty command definition for forge-ts init (bare — full project setup). Detects the project environment, writes default configuration files, validates tsconfig/package.json, and reports a summary.
import { initProjectCommand } from "@forge-ts/cli/commands/init-project";
// Registered as the default handler for `forge-ts init`DoctorResult
Result of the doctor command.
import { runDoctor } from "@forge-ts/cli/commands/doctor";
const output = await runDoctor({ cwd: process.cwd() });
console.log(output.data.summary.passed); // number of passed checksrunDoctor()
Runs the doctor integrity check flow.
import { runDoctor } from "@forge-ts/cli/commands/doctor";
const output = await runDoctor({ cwd: process.cwd(), fix: false });
console.log(output.data.summary); // { passed: 7, warnings: 2, errors: 1, info: 0 }doctorCommand
Citty command definition for forge-ts doctor. Performs project integrity checks and optionally auto-fixes resolvable issues with --fix.
import { doctorCommand } from "@forge-ts/cli/commands/doctor";
// Registered as a top-level subcommand of `forge-ts`InitDocsResult
Result of the init docs command.
import { runInitDocs } from "@forge-ts/cli/commands/init-docs";
const output = await runInitDocs({ target: "mintlify" });
console.log(output.data.summary.filesCreated); // number of files writtenrunInitDocs()
Scaffolds a documentation site for the target SSG platform. Resolves the target from args, validates it, checks for an existing scaffold, calls the adapter's scaffold() method, and writes all files produced by the manifest to outDir.
import { runInitDocs } from "@forge-ts/cli/commands/init-docs";
const output = await runInitDocs({ target: "mintlify", cwd: process.cwd() });
console.log(output.data.files); // list of created file pathsinitDocsCommand
Citty command definition for forge-ts init docs. Scaffolds a complete documentation site for the target SSG platform. Use --json for LAFS JSON envelope output (agent/CI-friendly).
import { initDocsCommand } from "@forge-ts/cli/commands/init-docs";
// Registered automatically as a subcommand of `forge-ts init`initCommand
Citty command definition for forge-ts init. Exposes subcommands for scaffolding project artefacts.
import { initCommand } from "@forge-ts/cli/commands/init-docs";
// Registered automatically as a subcommand of `forge-ts`runLock()
Runs the lock command: reads current config and creates .forge-lock.json.
import { runLock } from "@forge-ts/cli/commands/lock";
const output = await runLock({ cwd: process.cwd() });
console.log(output.data.locked.rules); // number of rules lockedPrepublishResult
Typed result for the prepublish command.
import { runPrepublish } from "@forge-ts/cli/commands/prepublish";
const output = await runPrepublish({ cwd: process.cwd() });
console.log(output.data.check.success); // true if check passed
console.log(output.data.build?.success); // true if build passedrunPrepublish()
Runs the prepublish safety gate: check then build. If the check step fails, the build step is skipped entirely. Both steps use the same project root (cwd).
import { runPrepublish } from "@forge-ts/cli/commands/prepublish";
const output = await runPrepublish({ cwd: process.cwd() });
if (!output.success) process.exit(1);prepublishCommand
Citty command definition for forge-ts prepublish. Runs check then build as a publish safety gate. Add to package.json as: "prepublishOnly": "forge-ts prepublish"
import { prepublishCommand } from "@forge-ts/cli/commands/prepublish";
// Registered as `forge-ts prepublish`runTest()
Runs the doctest pipeline and returns a typed command output.
import { runTest } from "@forge-ts/cli/commands/test";
const output = await runTest({ cwd: process.cwd() });
console.log(output.data.summary.passed); // number of passing doctestsrunUnlock()
Runs the unlock command: removes .forge-lock.json with a mandatory reason.
import { runUnlock } from "@forge-ts/cli/commands/unlock";
const output = await runUnlock({ cwd: process.cwd(), reason: "Relaxing rules for migration" });
console.log(output.data.success); // trueindex.ts
Unified command-line interface for the forge-ts toolchain. Provides the forge-ts binary with subcommands that wrap every pipeline stage — TSDoc enforcement, doctest execution, documentation generation, OpenAPI spec output, and project health diagnostics — behind a consistent flag surface and structured JSON/human output modes.
// Programmatic usage — run enforcement without spawning a subprocess
import { loadConfig } from "@forge-ts/core";
import { runBarometer } from "@forge-ts/cli";
const config = await loadConfig();
const result = await runBarometer({ cwd: config.rootDir });
console.log(`Documentation score: ${result.score}/100`);