# Configuration (/docs/codegen/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 config [#create-a-config]

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

```ts title="kysoql.config.ts"
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:

```bash
pnpm exec kysoql generate
```

## Settings [#settings]

| Key          | Default                                                                                            | What it controls                                       |
| ------------ | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `auth`       | None                                                                                               | Returns the Salesforce session used by CLI generation. |
| `apiVersion` | `65.0`                                                                                             | Salesforce REST API version without the `v` prefix.    |
| `objects`    | All queryable objects                                                                              | Salesforce object API names to generate.               |
| `fields`     | All described fields                                                                               | Optional include or exclude rules per object.          |
| `output`     | `src/kysoql/salesforce.generated.ts` when `src` exists, otherwise `kysoql/salesforce.generated.ts` | Generated file location.                               |
| `schemaName` | `SalesforceSchema`                                                                                 | Name of the generated TypeScript interface.            |

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

## Filter fields when a schema is too large [#filter-fields-when-a-schema-is-too-large]

Use one exact include or exclude rule per object:

```ts title="kysoql.config.ts"
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](/docs/codegen/field-filtering) for the full rules.

## CLI overrides [#cli-overrides]

CLI flags take precedence over config values:

```bash
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:

```bash
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 paths [#config-discovery-and-paths]

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 orgs [#multiple-salesforce-orgs]

Keep separate configs when different orgs have meaningfully different schemas:

```json title="package.json"
{
  "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.

<Accordions type="single">
  <Accordion title="Why is my output file in the wrong place?">
    Check whether the path came from the config or a CLI flag. Config-relative paths use the config directory. CLI `--output` paths use the directory where you ran the command.
  </Accordion>

  <Accordion title="Why is a config setting being ignored?">
    Look for an explicit CLI flag in package scripts or CI. CLI flags always win over config values.
  </Accordion>

  <Accordion title="Why does generation fail when the config typechecks?">
    TypeScript can validate the config shape, but Salesforce metadata and authentication are runtime inputs. The connected user still needs access to the requested objects and metadata.
  </Accordion>
</Accordions>