@genxapi/cli

CLI for GenX API orchestration. The current public command surface is intentionally small and explicit.

Requirements

• Node.js v20+.
• Access tokens if you plan to push to GitHub (GITHUB_TOKEN) or publish to npm (NPM_TOKEN).

Commands

• genxapi generate – Generate clients defined in configuration, optionally override the output directory (--target), and run configured post-generation GitHub or registry steps.
• genxapi diff – Compare two OpenAPI contracts, render a human-readable summary or JSON report, and optionally write release metadata.
• genxapi publish – Create GitHub releases using Octokit.

Running the CLI

• Primary public alias: npx genxapi --help
• Direct package alternative: npx @genxapi/cli --help
• Local install: add "cli": "genxapi" to package.json scripts, then run npm run cli -- --help

Environment Variables

• GITHUB_TOKEN (configurable via project.repository.tokenEnv) – required to push commits or open pull requests.
• NPM_TOKEN (configurable via project.publish.npm.tokenEnv) – required to publish the generated package to npm.

Ensure project.repository.owner matches your GitHub login (case-insensitive). Leading @ characters are stripped automatically before syncing.

Use project.readme in your configuration to customise the generated package README (introduction, usage text, extra sections).

1. Navigate to Settings ▸ Developer settings ▸ Personal access tokens in GitHub.
2. Create either:
   • a Fine-grained token scoped to the repos you will update and enable:
     • Repository permissions → Contents → Read and write (allows pushing commits and editing files)
     • Repository permissions → Pull requests → Read and write
   • or a Classic token and tick the single checkbox repo (minimal scope for commit + PR access).
3. Copy the token and export it as GITHUB_TOKEN before running the generator.

1. Sign in to npmjs.com.
2. Go to Access Tokens and click Generate new token.
3. Choose an Automation or Publish token (Automation is recommended for CI).
4. Copy the token and export it as NPM_TOKEN before running the generator.

Sample Usage

GITHUB_TOKEN=ghp_xxx NPM_TOKEN=xxx \
genxapi generate \
  --config samples/orval-multi-client.config.json \
  --target ./examples/multi-client-demo \
  --log-level debug

This command will:

1. Load the config (including repository/publish settings) from the provided path or cosmiconfig search.
2. Call @genxapi/template-orval to scaffold the template, apply replacements, copy swagger files, run Orval, and execute hooks.
3. Commit and push the generated changes to GitHub and open a pull request if project.repository exists.
4. Publish the package if project.publish.npm.enabled is true.

Contract diff example:

genxapi diff \
  --base ./contracts/petstore-prev.json \
  --head ./contracts/petstore-next.json \
  --format json \
  --output ./artifacts/genxapi-diff.json \
  --release-manifest-output ./artifacts/genxapi-release.json

Generation can append planning metadata to the same release manifest:

genxapi generate \
  --config ./genxapi.config.json \
  --dry-run \
  --plan-output ./artifacts/genxapi-plan.json \
  --release-manifest-output ./artifacts/genxapi-release.json

Type safety

Run npm run typecheck at the repository root to validate both packages before raising a PR or publishing.

Publishing the CLI

From the repository root:

# Dry-run the repository release configuration locally
npm run release:dry:cli

The published npm release for @genxapi/cli is handled by semantic-release from .github/workflows/publish-cli.yml after merge to main. The genxapi proxy package remains a separate manual release.