Configuration

Use kysoql.config.ts when you want schema generation to behave the same way for local development and CI.

The config only affects kysoql generate. It does not configure your runtime Kysoql instance or Salesforce executor.

Create a configCopy Anchor Link

Place the file in the directory where you run the CLI, usually beside package.json:

import { SalesforceAuth } from "@kysoql/auth";
import { defineConfig } from "@kysoql/codegen";

const salesforce = new SalesforceAuth({
  loginUrl: "https://login.salesforce.com",
  clientId: "external-client-app-id",
});

export default defineConfig({
  auth: () =>
    salesforce.jwtBearer({
      username: "integration@example.com",
      privateKey: { type: "file", path: "./salesforce-auth-key.pem" },
    }),
  objects: ["Account", "Contact", "Opportunity", "User"],
  schemaName: "SalesforceSchema",
});

defineConfig gives you editor completion and typechecking. A satisfies KysoqlConfig annotation works too.

Run:

pnpm exec kysoql generate

SettingsCopy Anchor Link

For large orgs, an explicit objects list keeps generation focused and makes changes easier to review.

Filter fields when a schema is too largeCopy Anchor Link

Use one exact include or exclude rule per object:

import { defineConfig } from "@kysoql/codegen";

export default defineConfig({
  objects: ["Account", "Contact", "User"],
  fields: {
    Account: { include: ["Id", "Name", "Industry", "OwnerId"] },
    Contact: { exclude: ["Description"] },
  },
});

User has no field rule, so all described User fields remain in the generated schema.

An include list needs every field your queries depend on, not just fields you return. Remember filters, ordering, grouping, aggregates, lookups, and relationship paths. See field filtering for the full rules.

CLI overridesCopy Anchor Link

CLI flags take precedence over config values:

pnpm exec kysoql generate --config config/kysoql.sandbox.ts
pnpm exec kysoql generate --object Account --output tmp/account.ts
pnpm exec kysoql generate --api-version 65.0

A repeated --object list replaces the configured object list rather than appending to it.

--no-config skips config discovery completely:

pnpm exec kysoql generate --no-config \
  --auth config/salesforce.auth.ts \
  --object Account \
  --output src/account.generated.ts

--config and --no-config cannot be used together.

Config discovery and pathsCopy Anchor Link

The CLI looks in the current working directory for:

• kysoql.config.ts
• kysoql.config.mts
• kysoql.config.cts
• kysoql.config.js
• kysoql.config.mjs
• kysoql.config.cjs

It does not walk up through parent directories. If more than one supported config exists, choose one explicitly with --config.

A relative output inside the config is resolved from the config file's directory. A relative --output CLI value is resolved from the current working directory.

Config files and their imports are executable code. Only run trusted config and auth modules, especially in CI jobs that have Salesforce credentials.

Multiple Salesforce orgsCopy Anchor Link

Keep separate configs when different orgs have meaningfully different schemas:

{
  "scripts": {
    "schema:sandbox": "kysoql generate --config config/kysoql.sandbox.ts",
    "schema:production": "kysoql generate --config config/kysoql.production.ts"
  }
}

Use separate auth providers and output files where that makes the environment boundary clearer. Generated schema files do not contain credentials.