@genxapi/cli

CLI to scaffold, regenerate, synchronise, and publish multiple API clients using the GenX API templates.

Requirements

• Node.js v20+ (required by Orval's Commander dependency; older runtimes will emit engine warnings).
• 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), initialise/synchronise a GitHub repository, and publish to npm.
• genxapi publish – Create GitHub releases using Octokit.

Running the CLI

• One-off (no install): 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 (generated clients default to public access, matching the publish scripts in this monorepo).

Semantic-release examples

After running the generator, you can compare swagger revisions and generate a commit message for semantic-release:

# Compare swagger files and classify the change
node --input-type=module -e "import base from './packages/cli/src/utils/swaggerDiff/fixtures/base.json' assert { type: 'json' };
import { analyzeSwaggerDiff } from './packages/cli/src/utils/swaggerDiff/index.js';
const next = structuredClone(base);
next.paths['/pets/{id}'] = { get: { operationId: 'getPet', responses: { '200': { description: 'single pet' } } } };
console.log(analyzeSwaggerDiff(base, next));"

This prints the commit suggestion (feat, fix, or chore) that feeds semantic-release version bumps.

Type safety

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

Publishing the CLI

# Build + publish to npmjs.org (public)
npm run build --workspace @genxapi/cli
npm publish --workspace @genxapi/cli --access public

Publishing to GitHub Packages is optional; include --registry https://npm.pkg.github.com and use a PAT with read:packages and write:packages scopes.

Installing from GitHub Packages

1. Authenticate (requires GITHUB_TOKEN with read:packages + write:packages):

   npm config set @genxapi:registry https://npm.pkg.github.com/
   npm config set //npm.pkg.github.com/:_authToken ${GITHUB_TOKEN}

2. Run the bundled sample:

   npx genxapi generate \
     --config samples/orval-multi-client.config.json \
     --target ./examples/multi-client-demo \
     --log-level info