CLI – fluent-wp-client

Overview

fluent-wp-client ships a CLI for discovering live REST schemas from a WordPress site and generating code artifacts for downstream apps, validators, type checking, and AI/tooling workflows.

Command

CLI command

npx fluent-wp-client schemas --url https://example.com

The schemas command discovers WordPress JSON Schema first, then generates a Zod-ready TypeScript module, standalone TypeScript types, JSON Schema, or multiple artifacts in one run.

Authentication

Use non-interactive auth flags when discovery needs authenticated schemas or when you are running in CI:

Authenticated schema generation

npx fluent-wp-client schemas \
  --url https://example.com \
  --username admin \
  --password "xxxx xxxx xxxx xxxx"

Supported auth flags:

• --username and --password for WordPress application passwords
• --token for JWT bearer auth
• --auth-header for a prebuilt Authorization header value

Use only one auth mode at a time.

Environment variables

To avoid passing secrets through CLI arguments (which can appear in shell history and process listings), use environment variables instead:

Authenticated schema generation via environment variables

export FLUENT_WP_USERNAME=admin
export FLUENT_WP_PASSWORD="xxxx xxxx xxxx xxxx"
npx fluent-wp-client schemas --url https://example.com

Supported environment variables:

• FLUENT_WP_USERNAME and FLUENT_WP_PASSWORD for WordPress application passwords
• FLUENT_WP_TOKEN for JWT bearer auth
• FLUENT_WP_AUTH_HEADER for a prebuilt Authorization header value

CLI flags take precedence over environment variables when both are provided.

Resource filtering

Use --include and --exclude to limit generation to specific resources by slug or REST base:

Generating only selected resources

npx fluent-wp-client schemas \
  --url https://example.com \
  --include posts,books,genre \
  --exclude posts

In this example only books and genre are generated.

Output Files

Available output files

npx fluent-wp-client schemas --url https://example.com
npx fluent-wp-client schemas --url https://example.com \
  --zod-out wp-schemas.mjs \
  --types-out wp-types.d.ts
npx fluent-wp-client schemas --url https://example.com \
  --zod-out wp-schemas.ts \
  --json-out wp-schemas.json \
  --types-out wp-types.d.ts

Output paths define the artifacts to generate. If you omit all output paths, the CLI writes wp-schemas.ts.

• --zod-out or --out writes a Zod module with JSON Schema literals and validators. .ts output also includes inferred z.infer<> aliases.
• --json-out writes one JSON document keyed by REST base.
• --types-out writes dependency-free TypeScript declaration files with interfaces and type aliases derived from the same normalized JSON Schemas.

Generated artifact extensions are intentionally strict:

• Zod output must be .ts for TypeScript or .mjs for runtime JavaScript.
• JSON Schema output must be .json.
• Standalone TypeScript declarations must be .d.ts.

Use --types-out when you want a dedicated types file beside runtime validators:

Generating runtime schemas and standalone types

npx fluent-wp-client schemas \
  --url https://example.com \
  --out wp-schemas.ts \
  --types-out wp-types.d.ts

Interactive mode

If you omit --url, the CLI prompts for the site URL and auth method interactively.

Interactive mode

npx fluent-wp-client schemas

Generated artifacts

schemas produces normalized item schemas suitable for downstream validation and codegen. Generated JSON Schema and Zod validators accept WordPress local datetime strings without strict date-time format checks. Optional scalar ACF fields also allow "" when WordPress can return an empty value; null appears only when the REST schema declares it.

Typical flow:

1. Generate schema files from the target site.
2. Import generated Zod validators when you need runtime validation.
3. Import generated interfaces when you only need compile-time types.
4. Validate input or output locally.
5. Call the normal fluent-wp-client method with the validated data.

Validate with one generated schema

import { postsCreateSchema } from './wp-schemas';

const validatedInput = postsCreateSchema.parse({
  title: 'CLI-validated post',
  status: 'draft',
});

await wp.content('posts').create(validatedInput);

Use one generated standalone type

import type { WPPost } from './wp-types';

function getTitle(post: WPPost): string {
  return post.title?.rendered ?? '';
}

Use runtime discovery from schema-discovery.mdx when you want live schemas inside the app instead of build-time generated files.