chore(cli): migrate @fern-api/cli to use CliError

[FedeZara]

Description

Migrates @fern-api/cli (the main CLI package) to use explicit CliError error codes on every failAndThrow / failWithoutThrowing call site.

This is one of ~35 package migration PRs that follow the error classification system introduced in #14749.

Changes Made

Assigned typed error codes across 42 files in packages/cli/cli/src/, covering every failAndThrow and failWithoutThrowing invocation (excluding generic catch blocks where resolveErrorCode auto-extracts codes from CliError instances).

Error codes used

Code	Usage
CONFIG_ERROR	Missing config, invalid flags, bad file paths, missing generators.yml, unknown group/generator names, missing docs.yml
AUTH_ERROR	Authentication failures (fern login required, token creation)
NETWORK_ERROR	HTTP/API call failures, translation service errors, generation task polling failures
VALIDATION_ERROR	Schema validation failures, broken-link checks, workspace validation
PARSE_ERROR	Malformed YAML/JSON, invalid IR files, export schema issues
VERSION_ERROR	Invalid semver, version already registered, generator version incompatibility
ENVIRONMENT_ERROR	Missing environment prerequisites, self-update failures, dependency installation
INTERNAL_ERROR	Unexpected states that indicate bugs, failed reruns, missing IR fields

Files touched (grouped by area)

• Top-level CLI: cli.ts, cliV2.ts, rerunFernCliAtVersion.ts, resolveGroupGithubConfig.ts
• Generate commands: generateAPIWorkspace.ts, generateAPIWorkspaces.ts, generateDocsWorkspace.ts
• Docs commands: docsDiff.ts, generateLibraryDocs.ts, listDocsPreview.ts, deleteDocsPreview.ts
• SDK commands: sdkDiffCommand.ts, sdkPreview.ts
• Diff: diff.ts
• Validation: validateWorkspaces.ts, validateDocsBrokenLinks.ts, validateDocsWorkspaceAndLogIssues.ts
• Upgrade/Downgrade: upgrade.ts, upgradeGenerator.ts, downgrade.ts
• Self-update: selfUpdate.ts
• Export: servicesConverter.ts, typeConverter.ts, security.ts
• Other: token.ts, testOutput.ts, mockServer.ts, mergeOpenAPIWithOverrides.ts, compareOpenAPISpecs.ts, writeOverridesForWorkspaces.ts, getGeneratorList.ts, getOrganization.ts, installDependencies.ts, registerWorkspacesV1.ts

Testing

• Existing tests pass

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

[github-actions]

🌱 Seed Test Selector

Select languages to run seed tests for:

• Python
• TypeScript
• Java
• Go
• Ruby
• C#
• PHP
• Swift
• Rust
• OpenAPI
• Postman

---

How to use: Click the ⋯ menu above → "Edit" → check the boxes you want → click "Update comment". Tests will run automatically and snapshots will be committed to this PR.

[Swimburger]

there should be a helper in the codebase already to do error instanceof Error ? ...

[graphite-app]

Invalid TypeScript syntax: Cannot use dot notation in export declarations. The syntax export const CliError.Code and export type CliError.Code is not valid TypeScript and will cause compilation errors.

// Fix: Use namespace syntax instead
export namespace CliError {
    export const Code = {
        InternalError: "INTERNAL_ERROR",
        // ... rest of codes
    } as const;
    
    export type Code = (typeof Code)[keyof typeof Code];
}

This will break compilation across all files importing CliError.Code.

Suggested change

	export namespace CliError {
	export const Code = {
	InternalError: "INTERNAL_ERROR",
	ResolutionError: "RESOLUTION_ERROR",
	IrConversionError: "IR_CONVERSION_ERROR",
	ValidationError: "VALIDATION_ERROR",
	NetworkError: "NETWORK_ERROR",
	AuthError: "AUTH_ERROR",
	ConfigError: "CONFIG_ERROR",
	Unclassified: "UNCLASSIFIED"
	} as const;
	export type Code = (typeof Code)[keyof typeof Code];
	}

Spotted by Graphite



Is this helpful? React 👍 or 👎 to let us know.

[FedeZara]

• chore(cli): migrate @fern-api/cli to use CliError #14753 👈 (View in Graphite)
• chore(cli): temporarily disable Sentry reporting for unclassified errors #14750 : 1 other dependent PR (#14752 )
• feat(cli): introduce structured CliError with typed error codes and Sentry routing #14749
• chore(cli): eagerly resolve TelemetryClient distinctId via async factory #14748
• chore(cli): make instrumentPostHogEvent synchronous #14747
• chore(cli): rename FernCliError to TaskAbortSignal #14746
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[FedeZara]

Merge activity

• Apr 14, 7:45 PM UTC: @FedeZara merged this pull request with Graphite.