{"schemaVersion":"1.0.0","docId":"cli","source":"cli","slug":"cli","path":"/docs/cli","raw_path":"/raw/cli.md","title":"LakeQL CLI","headings":[],"documentType":"unknown","contentOrigin":"static-doc","canonicalUrl":"/docs/cli/","buildId":"local-1782300258903","generatedAt":"2026-06-24T11:24:18.903Z","content":"---\ntitle: LakeQL CLI\nnavTitle: CLI\ndescription: Schema introspection and code generation CLI.\nentrypoint: /docs/cli/overview/installation\n---\n","description":"Schema introspection and code generation CLI.","navTitle":"CLI","keywords":["lakeql","schema","introspection","generation"]}
{"schemaVersion":"1.0.0","docId":"cli/commands/create-endpoint","source":"cli","slug":"commands/create-endpoint","path":"/docs/cli/commands/create-endpoint","raw_path":"/raw/cli/commands/create-endpoint.md","title":"create-endpoint","headings":[{"level":1,"text":"create-endpoint","id":"create-endpoint"}],"documentType":"unknown","contentOrigin":"static-doc","canonicalUrl":"/docs/cli/commands/create-endpoint/","buildId":"local-1782300258903","generatedAt":"2026-06-24T11:24:18.903Z","content":"---\ntitle: create-endpoint\nnavTitle: create-endpoint\ndescription: Generate a custom endpoint from a JSON definition file.\n---\n\n# create-endpoint\n\nGenerate a custom endpoint (query + mutation) from a JSON definition file. The definition file can be created using the [Endpoint Builder](/endpoint-builder) UI or written by hand.\n\n## Generated files\n\nFiles are written to `schemas/custom/<catalog>/<schema>/<tableName>/`:\n\n- `config.ts` — Endpoint configuration\n- `interface.ts` — TypeScript interface for the endpoint fields\n- `query-schema.ts` — GraphQL query schema definition\n- `mutation-schema.ts` — GraphQL mutation schema with write pipeline resolver (only when mutation is configured)\n- `validations.ts` — Zod validation schema (only when fields have validations configured)\n- `json-schema.json` — JSON Schema representation\n- `endpoint.json` — The endpoint definition (for re-generation)\n\n<Note>\n  The `mutation-schema.ts` and `validations.ts` files are only generated when\n  the endpoint definition includes mutation configuration. Query-only endpoints\n  skip these files entirely.\n</Note>\n\n## Usage\n\n```bash\nlakeql-cli create-endpoint --from-file ./my-endpoint.json\n```\n\n### With mutation enabled\n\n```\n✔ Loaded definition: user_events (catalog: hive, schema: analytics)\n  → schemas/custom/hive/analytics/user_events/config.ts\n  → schemas/custom/hive/analytics/user_events/interface.ts\n  → schemas/custom/hive/analytics/user_events/query-schema.ts\n  → schemas/custom/hive/analytics/user_events/mutation-schema.ts\n  → schemas/custom/hive/analytics/user_events/validations.ts\n  → schemas/custom/hive/analytics/user_events/json-schema.json\n  → schemas/custom/hive/analytics/user_events/endpoint.json\n  Load strategy: full_load\n✔ Config registry updated\n```\n\n### Without mutation (query-only)\n\n```\n✔ Loaded definition: my_table (catalog: analytics, schema: tracking)\n  → schemas/custom/analytics/tracking/my_table/config.ts\n  → schemas/custom/analytics/tracking/my_table/interface.ts\n  → schemas/custom/analytics/tracking/my_table/query-schema.ts\n  → schemas/custom/analytics/tracking/my_table/json-schema.json\n  → schemas/custom/analytics/tracking/my_table/endpoint.json\n  mutation: disabled\n✔ Config registry updated\n```\n\n## Definition file format\n\nThe JSON definition file must conform to the `EndpointDefinitionFormat` schema:\n\n```json\n{\n  \"version\": \"1.0\",\n  \"tableName\": \"user_events\",\n  \"catalog\": \"hive\",\n  \"schema\": \"analytics\",\n  \"fields\": [\n    {\n      \"name\": \"email\",\n      \"type\": \"String\",\n      \"options\": {\n        \"required\": true,\n        \"validations\": [{ \"type\": \"email\" }]\n      }\n    },\n    {\n      \"name\": \"age\",\n      \"type\": \"Integer\",\n      \"options\": {\n        \"required\": false,\n        \"validations\": [\n          { \"type\": \"min\", \"value\": 0 },\n          { \"type\": \"max\", \"value\": 150 }\n        ]\n      }\n    },\n    { \"name\": \"event_id\", \"type\": \"String\" },\n    { \"name\": \"timestamp\", \"type\": \"DateTime\" },\n    {\n      \"name\": \"metadata\",\n      \"type\": \"Object\",\n      \"fields\": [{ \"name\": \"source\", \"type\": \"String\" }]\n    },\n    {\n      \"name\": \"tags\",\n      \"type\": \"Array\",\n      \"items\": { \"type\": \"String\" }\n    }\n  ],\n  \"mutation\": {\n    \"loadStrategy\": \"full_load\",\n    \"type\": \"s3\",\n    \"bucket\": \"my-datalake\",\n    \"basePath\": \"warehouse/analytics/user_events\",\n    \"endpoint\": \"https://s3.eu-central-1.amazonaws.com\"\n  }\n}\n```\n\n### Supported field types\n\n- **Primitives:** String, Integer, Float, Boolean, Date, DateTime\n- **Object:** Nested object with child fields (max 5 levels)\n- **Array:** Array of primitives or objects\n\n### Mutation configuration\n\nThe optional `mutation` field controls whether a write pipeline is generated for this endpoint. Set it to `false` (or omit it) for query-only endpoints. Set it to a configuration object to enable the mutation pipeline.\n\n<InterfaceReference\n  file=\"schema-generator/src/endpoint-schema\"\n  name=\"MutationConfig\"\n/>\n\n<Note>\n  The `type` field defaults to `\"s3\"`. Use `\"minio\"` for local development with\n  a MinIO-compatible endpoint. See the [Mutations\n  guide](/lakeql/guides/mutations#storage-configuration) for environment\n  variable details.\n</Note>\n\n#### Mutation with partitioning options\n\n```json\n{\n  \"mutation\": {\n    \"loadStrategy\": \"append\",\n    \"type\": \"s3\",\n    \"bucket\": \"my-datalake\",\n    \"basePath\": \"warehouse/raw/events\",\n    \"partitioning\": \"event_date\",\n    \"partitioningFormat\": \"year/month\"\n  }\n}\n```\n\nThe `partitioning` and `partitioningFormat` fields are omitted from generated configs when `loadStrategy` is `full_load`. See the [Mutations guide](/lakeql/guides/mutations#partitioning) for full details on each partitioning mode.\n\nSee the [Load Strategies](/lakeql/guides/load-strategies) guide for details on when to use each strategy.\n\n<Note>\n  Endpoints generated via the `pull` command always set `mutation: false` since\n  pulled tables are query-only by default.\n</Note>\n\n### Field options\n\nEach field can include an optional `options` object to control mutation input behavior:\n\n<InterfaceReference\n  file=\"schema-generator/src/endpoint-schema\"\n  name=\"FieldOptions\"\n/>\n\n<Note>\n  When timestamp-based partitioning is active, the Endpoint Builder\n  automatically adds `load_timestamp` (DateTime), `load_timestamp_year`\n  (Integer), and `load_timestamp_month` (Integer) fields with `readOnly: true`.\n  These fields are populated by the write pipeline at runtime and are queryable\n  in Hive and directly in Parquet, but users cannot provide them as mutation\n  input.\n</Note>\n\n#### Available validations\n\n| Validation | Applies to     | Description                     | Example                                    |\n| ---------- | -------------- | ------------------------------- | ------------------------------------------ |\n| `email`    | String         | Must be a valid email address   | `{ \"type\": \"email\" }`                      |\n| `url`      | String         | Must be a valid URL             | `{ \"type\": \"url\" }`                        |\n| `uuid`     | String         | Must be a valid UUID            | `{ \"type\": \"uuid\" }`                       |\n| `min`      | Integer, Float | Minimum numeric value           | `{ \"type\": \"min\", \"value\": 0 }`            |\n| `max`      | Integer, Float | Maximum numeric value           | `{ \"type\": \"max\", \"value\": 150 }`          |\n| `regex`    | String         | Must match a regular expression | `{ \"type\": \"regex\", \"pattern\": \"^[A-Z]\" }` |\n\n### Validation rules\n\n- `tableName`, `catalog`, `schema`: alphanumeric + underscore, no leading digit, max 128 chars\n- Field names: alphanumeric + underscore, no leading digit, max 64 chars\n- No duplicate field names at the same nesting level\n- Object fields must have at least 1 child field\n\n## Workflow\n\n1. Use the [Endpoint Builder](/endpoint-builder) to define your schema visually\n2. Configure mutation support and load strategy if write operations are needed\n3. Download the JSON definition file\n4. Run `lakeql-cli create-endpoint --from-file ./your-endpoint.json`\n5. The generated mutation resolver is fully wired to the write pipeline — no manual stub implementation needed\n\n## Options\n\n<CliCommandDetails command=\"create-endpoint\" />\n","description":"Generate a custom endpoint from a JSON definition file.","navTitle":"create-endpoint","keywords":["create-endpoint","generate","custom","endpoint","definition"]}
{"schemaVersion":"1.0.0","docId":"cli/commands/create-registry","source":"cli","slug":"commands/create-registry","path":"/docs/cli/commands/create-registry","raw_path":"/raw/cli/commands/create-registry.md","title":"lakeql-cli create-registry","headings":[{"level":2,"text":"Syntax","id":"syntax"},{"level":2,"text":"Usage","id":"usage"},{"level":2,"text":"Options","id":"options"}],"documentType":"unknown","contentOrigin":"static-doc","canonicalUrl":"/docs/cli/commands/create-registry/","buildId":"local-1782300258903","generatedAt":"2026-06-24T11:24:18.903Z","content":"---\ntitle: \"lakeql-cli create-registry\"\nnavTitle: \"create-registry\"\ndescription: Generates the config registry for type-safe permissions.\n---\n\nScans your project for all `schemas/**/config.ts` files and generates a unified `config-registry.ts`. This registry enables type-safe usage of `createPermission` across your endpoints.\n\n## Syntax\n\n```bash\nlakeql-cli create-registry [options]\n```\n\n## Usage\n\n```bash\nlakeql-cli create-registry\n```\n\n```\n✔ Found 4 config files in schemas/\n✔ Generated config-registry.ts\n```\n\nThe generated file imports all discovered config modules and re-exports them as a typed registry object.\n\n## Options\n\n<CliCommandDetails command=\"create-registry\" />\n","description":"Generates the config registry for type-safe permissions.","navTitle":"create-registry","keywords":["lakeql-cli","create-registry","generates","config","registry"]}
{"schemaVersion":"1.0.0","docId":"cli/commands/generate-import-config","source":"cli","slug":"commands/generate-import-config","path":"/docs/cli/commands/generate-import-config","raw_path":"/raw/cli/commands/generate-import-config.md","title":"lakeql-cli generate-import-config","headings":[{"level":2,"text":"Syntax","id":"syntax"},{"level":2,"text":"Usage","id":"usage"},{"level":2,"text":"How it works","id":"how-it-works"},{"level":2,"text":"Options","id":"options"}],"documentType":"unknown","contentOrigin":"static-doc","canonicalUrl":"/docs/cli/commands/generate-import-config/","buildId":"local-1782300258903","generatedAt":"2026-06-24T11:24:18.903Z","content":"---\ntitle: \"lakeql-cli generate-import-config\"\nnavTitle: \"generate-import-config\"\ndescription: Generate an import.config.mjs from already-pulled schemas.\ncliCommand: \"generate-import-config\"\n---\n\nScans the `schemas/generated/` directory and generates a ready-to-use `import.config.mjs` for the [`pull --bulk`](/cli/commands/pull#bulk-mode) command.\n\nThis is useful when you have already pulled a set of schemas and want to re-use them as a bulk config — without having to maintain the file by hand.\n\n## Syntax\n\n```bash\nlakeql-cli generate-import-config [options]\n```\n\n## Usage\n\n```bash\nlakeql-cli generate-import-config\n```\n\nIf the output file does not exist yet, the command writes it directly:\n\n```\nWritten to \"/my-project/import.config.mjs\".\n```\n\n### Overwriting an existing file\n\nIf the output file already exists, the command warns and prompts for confirmation before overwriting:\n\nUse `--force` to skip the prompt entirely:\n\n```bash\nlakeql-cli generate-import-config --force\n```\n\n### Custom output path\n\n```bash\nlakeql-cli generate-import-config --output ./config/bulk.mjs\n```\n\n## How it works\n\nThe command reads your `lakeql.config` config file to determine the base path for generated files (same as all other commands).\nThe `--source-path` flag overrides the config value if needed.\n\nIt then scans the directory structure under `schemas/generated/`:\n\n```\nschemas/generated/\n└── <catalog>/\n    └── <schema>/\n        └── <table>/       ← each subdirectory becomes a table entry\n```\n\nEach catalog/schema combination becomes one entry in the generated config.\nSchemas that contain no table subdirectories are silently skipped.\n\n## Options\n\n<CliCommandDetails command=\"generate-import-config\" />\n","description":"Generate an import.config.mjs from already-pulled schemas.","navTitle":"generate-import-config","keywords":["lakeql-cli","generate-import-config","generate","importconfigmjs","already-pulled"]}
{"schemaVersion":"1.0.0","docId":"cli/commands/init","source":"cli","slug":"commands/init","path":"/docs/cli/commands/init","raw_path":"/raw/cli/commands/init.md","title":"lakeql-cli init","headings":[{"level":2,"text":"Syntax","id":"syntax"},{"level":2,"text":"Usage","id":"usage"},{"level":2,"text":"Options","id":"options"}],"documentType":"unknown","contentOrigin":"static-doc","canonicalUrl":"/docs/cli/commands/init/","buildId":"local-1782300258903","generatedAt":"2026-06-24T11:24:18.903Z","content":"---\ntitle: \"lakeql-cli init\"\nnavTitle: \"init\"\ndescription: Initialize a lakeql.config.json configuration file in your project.\n---\n\nScaffolds a `lakeql.config.json` file in the current directory. This config controls where generated code is placed.\n\nIf no `src/` directory is detected, the CLI prompts you to choose or specify a source path. If `src/` exists, it is used automatically.\n\n## Syntax\n\n```bash\nlakeql-cli init\n```\n\n## Usage\n\n```bash\nlakeql-cli init\n```\n\n```\nDetected src/ directory — generated code will be placed in src/\nCreated lakeql.config.json at /path/to/project/lakeql.config.json\n```\n\nIf `lakeql.config.json` already exists, the CLI asks whether to overwrite it.\n\n## Options\n\nThis command has no options.\n","description":"Initialize a lakeql.config.json configuration file in your project.","navTitle":"init","keywords":["lakeql-cli","initialize","lakeqlconfigjson","configuration","project"]}
{"schemaVersion":"1.0.0","docId":"cli/commands/list-columns","source":"cli","slug":"commands/list-columns","path":"/docs/cli/commands/list-columns","raw_path":"/raw/cli/commands/list-columns.md","title":"lakeql-cli list-columns","headings":[{"level":2,"text":"Syntax","id":"syntax"},{"level":2,"text":"Usage","id":"usage"},{"level":2,"text":"Options","id":"options"}],"documentType":"unknown","contentOrigin":"static-doc","canonicalUrl":"/docs/cli/commands/list-columns/","buildId":"local-1782300258903","generatedAt":"2026-06-24T11:24:18.903Z","content":"---\ntitle: \"lakeql-cli list-columns\"\nnavTitle: \"list-columns\"\ndescription: Lists columns for the specified table including types and descriptions.\n---\n\nQueries Trino and prints all columns for a specific table, including their data types, extra metadata, and descriptions.\n\n## Syntax\n\n```bash\nlakeql-cli list-columns [options]\n```\n\n## Usage\n\n```bash\nlakeql-cli list-columns --catalog hive --schema analytics --table users\n```\n\n```\n┌─────────────┬──────────┬───────┬─────────────────────┐\n│ Column Name │ Type     │ Extra │ Description         │\n├─────────────┼──────────┼───────┼─────────────────────┤\n│ id          │ varchar  │       │ Unique identifier   │\n│ email       │ varchar  │       │ User email address  │\n│ created_at  │ timestamp│       │ Account creation ts │\n│ is_active   │ boolean  │       │ Whether user active │\n└─────────────┴──────────┴───────┴─────────────────────┘\n```\n\n## Options\n\n<CliCommandDetails command=\"list-columns\" />\n","description":"Lists columns for the specified table including types and descriptions.","navTitle":"list-columns","keywords":["lakeql-cli","list-columns","lists","columns","specified"]}
{"schemaVersion":"1.0.0","docId":"cli/commands/list-schemas","source":"cli","slug":"commands/list-schemas","path":"/docs/cli/commands/list-schemas","raw_path":"/raw/cli/commands/list-schemas.md","title":"lakeql-cli list-schemas","headings":[{"level":2,"text":"Syntax","id":"syntax"},{"level":2,"text":"Usage","id":"usage"},{"level":2,"text":"Options","id":"options"}],"documentType":"unknown","contentOrigin":"static-doc","canonicalUrl":"/docs/cli/commands/list-schemas/","buildId":"local-1782300258903","generatedAt":"2026-06-24T11:24:18.903Z","content":"---\ntitle: \"lakeql-cli list-schemas\"\nnavTitle: \"list-schemas\"\ndescription: Lists available schemas for the configured catalog.\n---\n\nQueries Trino and prints all schemas available in the specified catalog.\n\n## Syntax\n\n```bash\nlakeql-cli list-schemas [options]\n```\n\n## Usage\n\n```bash\nlakeql-cli list-schemas --catalog hive\n```\n\n```\n┌─────────────┐\n│ Schema Name │\n├─────────────┤\n│ default     │\n│ analytics   │\n│ staging     │\n│ raw         │\n└─────────────┘\n```\n\n## Options\n\n<CliCommandDetails command=\"list-schemas\" />\n","description":"Lists available schemas for the configured catalog.","navTitle":"list-schemas","keywords":["lakeql-cli","list-schemas","lists","available","schemas"]}
{"schemaVersion":"1.0.0","docId":"cli/commands/list-tables","source":"cli","slug":"commands/list-tables","path":"/docs/cli/commands/list-tables","raw_path":"/raw/cli/commands/list-tables.md","title":"lakeql-cli list-tables","headings":[{"level":2,"text":"Syntax","id":"syntax"},{"level":2,"text":"Usage","id":"usage"},{"level":2,"text":"Options","id":"options"}],"documentType":"unknown","contentOrigin":"static-doc","canonicalUrl":"/docs/cli/commands/list-tables/","buildId":"local-1782300258903","generatedAt":"2026-06-24T11:24:18.903Z","content":"---\ntitle: \"lakeql-cli list-tables\"\nnavTitle: \"list-tables\"\ndescription: Lists available tables for the configured catalog and schema.\n---\n\nQueries Trino and prints all tables in the specified catalog and schema. If `--schema` is not provided, the CLI prompts you to select one interactively.\n\n## Syntax\n\n```bash\nlakeql-cli list-tables [options]\n```\n\n## Usage\n\n```bash\nlakeql-cli list-tables --catalog hive --schema analytics\n```\n\n```\n┌────────────────┐\n│ Table Name     │\n├────────────────┤\n│ users          │\n│ events         │\n│ sessions       │\n│ page_views     │\n└────────────────┘\n```\n\n## Options\n\n<CliCommandDetails command=\"list-schemas\" />\n","description":"Lists available tables for the configured catalog and schema.","navTitle":"list-tables","keywords":["lakeql-cli","list-tables","lists","available","tables"]}
{"schemaVersion":"1.0.0","docId":"cli/commands/list-views","source":"cli","slug":"commands/list-views","path":"/docs/cli/commands/list-views","raw_path":"/raw/cli/commands/list-views.md","title":"lakeql-cli list-views","headings":[{"level":2,"text":"Syntax","id":"syntax"},{"level":2,"text":"Usage","id":"usage"},{"level":2,"text":"Options","id":"options"}],"documentType":"unknown","contentOrigin":"static-doc","canonicalUrl":"/docs/cli/commands/list-views/","buildId":"local-1782300258903","generatedAt":"2026-06-24T11:24:18.903Z","content":"---\ntitle: \"lakeql-cli list-views\"\nnavTitle: \"list-views\"\ndescription: Lists available views for the configured catalog and schema.\n---\n\nQueries Trino and prints all views in the specified catalog and schema. If `--schema` is not provided, the CLI prompts you to select one interactively.\n\n## Syntax\n\n```bash\nlakeql-cli list-views [options]\n```\n\n## Usage\n\n```bash\nlakeql-cli list-views --catalog hive --schema analytics\n```\n\n```\n┌──────────────────────┐\n│ View Name            │\n├──────────────────────┤\n│ active_users         │\n│ daily_revenue        │\n│ session_aggregates   │\n└──────────────────────┘\n```\n\n## Options\n\n<CliCommandDetails command=\"list-views\" />\n","description":"Lists available views for the configured catalog and schema.","navTitle":"list-views","keywords":["lakeql-cli","list-views","lists","available","views"]}
{"schemaVersion":"1.0.0","docId":"cli/commands/pull","source":"cli","slug":"commands/pull","path":"/docs/cli/commands/pull","raw_path":"/raw/cli/commands/pull.md","title":"lakeql-cli pull","headings":[{"level":2,"text":"Usage","id":"usage"},{"level":2,"text":"Bulk mode","id":"bulk-mode"},{"level":2,"text":"Error output","id":"error-output"},{"level":2,"text":"Generated files","id":"generated-files"},{"level":2,"text":"Options","id":"options"}],"documentType":"unknown","contentOrigin":"static-doc","canonicalUrl":"/docs/cli/commands/pull/","buildId":"local-1782300258903","generatedAt":"2026-06-24T11:24:18.903Z","content":"---\ntitle: \"lakeql-cli pull\"\nnavTitle: \"pull\"\ndescription: Interactive query endpoint generation based on a remote table.\ncliCommand: \"pull\"\n---\n\nConnects to Trino, introspects table columns, and generates a full set of TypeScript files for type-safe query endpoints. When run without flags, the command walks you through interactive prompts to select a schema and tables.\n\n## Usage\n\n```bash\nlakeql-cli pull [options]\n```\n\n```bash\nlakeql-cli pull --catalog hive --schema myschema --table users\n```\n\n```\n› Pulling 1 item(s) from hive.myschema into ./src/schemas/generated...\n❯ Pull 1 item(s)\n  ✓ hive.myschema.users\n✓ Pull 1 item(s)\n✓ Create registry\n✔ Pull completed: 1 item(s) generated under ./src/schemas/generated/hive/myschema\n```\n\nThe registry is generated once after all selected items are processed.\n\nWhen more than 10 tables are selected in non-bulk mode, `pull` switches to a compact live progress view (`Completed X/Y | Active A/B`) with active load preview, instead of rendering one task line per table.\nUse `--concurrency <count>` to override the default limit of `8` concurrent pull operations.\n\n## Bulk mode\n\nWhen `--bulk` is specified, the command reads a config file and processes multiple schemas and tables in parallel — instead of using interactive prompts.\n\n### Syntax\n\n```bash\nlakeql-cli pull --bulk [options]\n```\n\n### Config file\n\nThe config file is automatically detected by looking for `import.config.{mjs,ts,js,json}` in the current directory (powered by [c12](https://github.com/unjs/c12)). You can override this with `--bulk-config`.\n\nUse the `@type` JSDoc annotation for type-safety and autocomplete:\n\n```javascript\n// import.config.mjs\n\n/** @type {import('@lakeql/cli').BulkPullConfig} */\nexport default [\n  {\n    schema: \"sales\",\n    tables: [\"orders\", \"customers\", \"products\"],\n    views: [\"daily_revenue\"],\n  },\n  {\n    schema: \"analytics\",\n    tables: [\"events\", \"sessions\"],\n  },\n  {\n    schema: \"inventory\",\n    catalog: \"warehouse\", // optional catalog override per entry\n    tables: [\"stock_levels\"],\n    views: [\"low_stock_alerts\"],\n  },\n]\n```\n\n#### Supported formats\n\nThe config file can be any of the following (in precedence order):\n\n1. `import.config.mjs`\n2. `import.config.ts`\n3. `import.config.js`\n4. `import.config.json`\n\n### Config schema\n\nEach entry in the array has the following shape:\n\n| Field     | Type       | Required | Description                      |\n| --------- | ---------- | -------- | -------------------------------- |\n| `schema`  | `string`   | Yes      | The schema to pull from          |\n| `catalog` | `string`   | No       | Catalog override for this entry  |\n| `tables`  | `string[]` | No       | Non-empty list of tables to pull |\n| `views`   | `string[]` | No       | Non-empty list of views to pull  |\n\nAt least one non-empty list (`tables` or `views`) must be provided per entry.\nEntries with both lists missing or empty fail validation before execution.\n\n### Catalog precedence\n\nThe catalog is resolved in the following order (first match wins):\n\n1. `--catalog` CLI flag (highest priority)\n2. `catalog` field in the config entry\n3. `HIVE_CATALOG` environment variable (fallback)\n\n### Execution behavior\n\n- All schema entries are processed **in parallel** for faster execution.\n- Tables and views within a single entry are processed sequentially for small entries.\n- Bulk item pulls are capped globally at 8 concurrent operations across the whole bulk run by default.\n- Bulk entries with more than 10 items switch to bounded parallel item processing under that global cap.\n- Use `--concurrency <count>` to raise or lower that limit for both bulk and non-bulk multi-item pulls.\n- The config registry is generated **once** at the end (not per entry).\n- If one entry fails, the remaining entries continue to execute.\n- Progress is displayed using a structured task list in the terminal.\n- Bulk entries with more than 10 items switch to the same compact live progress view used by large non-bulk pulls.\n\n### Usage\n\n```bash\n# Auto-detect config file (import.config.mjs, .ts, .js, or .json)\nlakeql-cli pull --bulk\n\n# Using a custom config file\nlakeql-cli pull --bulk --bulk-config=./my-import.config.mjs\n\n# With global catalog override\nlakeql-cli pull --bulk --catalog my_catalog\n\n# With a custom concurrency limit\nlakeql-cli pull --bulk --concurrency 5\n\n# Skip registry generation\nlakeql-cli pull --bulk --skip-registry\n```\n\n### Terminal output\n\n```\n⠋ Pull data\n  ✓ hive/sales — 4 item(s) pulled\n  ⠋ hive/analytics — 11 item(s)\n    › Completed 6/11 | Active 5/8\n    ›   - hive.analytics.events_6\n    ›   - hive.analytics.events_7\n    ›   - hive.analytics.events_8\n    ›   - hive.analytics.events_9\n    ›   - hive.analytics.events_10\n  ✓ warehouse/inventory — 2 item(s) pulled\n✓ Pull data\n✓ Create registry\n```\n\n## Error output\n\nWhen a request fails, the CLI prints structured output with context and hints:\n\n```text\n✖ LakeQL CLI failed.\n› Reason: Failed to list schemas.\n› Context: list-schemas (catalog=hive)\n› Root cause: fetch failed\n› Error code: ECONNREFUSED\n› Hint: Verify HIVE_HOST/HIVE_PORT, credentials and network reachability to Trino.\n```\n\nFor non-error aborts (for example prompt cancellation), the headline is shown as a warning and the command exits with code `0`.\n\n### Type export\n\nThe `BulkPullConfig` and `BulkPullEntry` types are exported from `@lakeql/cli` for use in your config file:\n\n```ts\nimport type { BulkPullConfig, BulkPullEntry } from \"@lakeql/cli\"\n```\n\n## Generated files\n\nFor each selected table, the following files are created under `schemas/generated/{catalog}/{schema}/{table}/`:\n\n- `config.ts` — Endpoint configuration\n- `interface.ts` — TypeScript interface for the table columns\n- `query-schema.ts` — GraphQL query schema definition\n- `json-schema.json` — JSON Schema representation\n- `endpoint.json` — Endpoint definition for re-generation\n\n`pull` generates query-only endpoints, so `mutation-schema.ts` is not created for pulled tables.\n\nField names from source schemas are normalized to valid identifier names during generation (for example, spaces become underscores).\nIf two source fields normalize to the same generated name, generation fails with a clear collision error instead of producing ambiguous output.\n\n## Options\n\n<CliCommandDetails command=\"pull\" />\n","description":"Interactive query endpoint generation based on a remote table.","navTitle":"pull","keywords":["lakeql-cli","interactive","query","endpoint","generation"]}
{"schemaVersion":"1.0.0","docId":"cli/configuration/config-file","source":"cli","slug":"configuration/config-file","path":"/docs/cli/configuration/config-file","raw_path":"/raw/cli/configuration/config-file.md","title":"Config File","headings":[{"level":2,"text":"Supported formats","id":"supported-formats"},{"level":2,"text":"Configuration","id":"configuration"},{"level":2,"text":"Path resolution","id":"path-resolution"},{"level":2,"text":"Examples","id":"examples"}],"documentType":"unknown","contentOrigin":"static-doc","canonicalUrl":"/docs/cli/configuration/config-file/","buildId":"local-1782300258903","generatedAt":"2026-06-24T11:24:18.903Z","content":"---\ntitle: Config File\ndescription: Reference for the lakeql config file.\n---\n\nThe lakeql config file controls where the CLI places generated code. It is created by running `lakeql-cli init`.\n\n## Supported formats\n\nThe CLI supports multiple config file formats, loaded in the following precedence order (first match wins):\n\n1. `lakeql.config.mjs` (recommended)\n2. `lakeql.config.ts`\n3. `lakeql.config.js`\n4. `lakeql.config.json`\n\nConfig loading is powered by [c12](https://github.com/unjs/c12).\n\n## Configuration\n\n<InterfaceReference file=\"cli/src/config\" name=\"LakeQLConfig\" />\n\n## Path resolution\n\n- Relative paths are resolved from the directory where the config file lives.\n- If `src/` is detected during `lakeql-cli init`, `sourcePath` is set to `\"src\"` automatically.\n- The CLI `--source-path` flag overrides the config value for that invocation.\n\n## Examples\n\n### MJS (recommended)\n\n```javascript\n// lakeql.config.mjs\n\n/** @type {import('@lakeql/cli').LakeQLConfig} */\nexport default {\n  sourcePath: \"src\",\n}\n```\n\n### JSON\n\n```json\n{\n  \"sourcePath\": \"src\"\n}\n```\n\nWith either config, running `lakeql-cli pull` places generated files under `src/schemas/generated/{catalog}/{schema}/{table}/`.\n","description":"Reference for the lakeql config file.","keywords":["config","reference","lakeql","supported","formats"]}
{"schemaVersion":"1.0.0","docId":"cli/configuration/environment-variables","source":"cli","slug":"configuration/environment-variables","path":"/docs/cli/configuration/environment-variables","raw_path":"/raw/cli/configuration/environment-variables.md","title":"Environment Variables","headings":[{"level":2,"text":"Required variables","id":"required-variables"},{"level":2,"text":"Optional variables","id":"optional-variables"},{"level":2,"text":"Example .env file","id":"example-env-file"}],"documentType":"unknown","contentOrigin":"static-doc","canonicalUrl":"/docs/cli/configuration/environment-variables/","buildId":"local-1782300258903","generatedAt":"2026-06-24T11:24:18.903Z","content":"---\ntitle: Environment Variables\ndescription: All environment variables used by the LakeQL CLI for Trino connectivity.\n---\n\nThe LakeQL CLI reads connection details from environment variables. These are required for any command that communicates with Trino.\n\n## Required variables\n\n| Variable        | Type   | Description                                                          |\n| --------------- | ------ | -------------------------------------------------------------------- |\n| `HIVE_HOST`     | string | Trino host URL including protocol (e.g. `https://trino.example.com`) |\n| `HIVE_PORT`     | number | Trino port (e.g. `443`)                                              |\n| `HIVE_USERNAME` | string | Authentication username                                              |\n| `HIVE_PASSWORD` | string | Authentication password                                              |\n| `HIVE_CATALOG`  | string | Default catalog name used when `--catalog` is not provided           |\n\n## Optional variables\n\n| Variable      | Type   | Default | Description                                        |\n| ------------- | ------ | ------- | -------------------------------------------------- |\n| `HIVE_SOURCE` | string | —       | Optional source identifier sent to Trino           |\n| `LOG_LEVEL`   | string | `warn`  | Log verbosity: `debug`, `info`, `warn`, or `error` |\n\n## Example .env file\n\n```bash\n# .env\nHIVE_HOST=https://trino.example.com\nHIVE_PORT=443\nHIVE_USERNAME=service-account\nHIVE_PASSWORD=s3cur3-p4ssw0rd\nHIVE_CATALOG=hive\nLOG_LEVEL=info\n```\n\nThe CLI does not load `.env` automatically.\nMake sure variables are present in the process environment before running commands.\n\nYou can do this in different ways:\n\n- export variables in your shell session\n- use a wrapper like `dotenv-cli`\n- run commands through your process manager or CI environment\n\nExample with `dotenv-cli`:\n\n```bash\ndotenv -e ./.env -- lakeql-cli pull\n```\n","description":"All environment variables used by the LakeQL CLI for Trino connectivity.","keywords":["variables","environment","lakeql","trino","connectivity"]}
{"schemaVersion":"1.0.0","docId":"cli/overview/installation","source":"cli","slug":"overview/installation","path":"/docs/cli/overview/installation","raw_path":"/raw/cli/overview/installation.md","title":"Installation","headings":[{"level":2,"text":"Install globally","id":"install-globally"},{"level":2,"text":"Run without installing","id":"run-without-installing"},{"level":2,"text":"Run within the monorepo","id":"run-within-the-monorepo"},{"level":2,"text":"Environment variables","id":"environment-variables"}],"documentType":"unknown","contentOrigin":"static-doc","canonicalUrl":"/docs/cli/overview/installation/","buildId":"local-1782300258903","generatedAt":"2026-06-24T11:24:18.903Z","content":"---\ntitle: Installation\ndescription: How to install and run the LakeQL CLI for schema introspection and code generation.\n---\n\nThe LakeQL CLI (`@lakeql/cli`) orchestrates schema introspection from Trino and generates TypeScript code — interfaces, query schemas, and configs — that power type-safe GraphQL query endpoints in your project.\n\n## Install globally\n\n<Command variant=\"install\">-g @lakeql/cli</Command>\n\n## Run without installing\n\nUse `npx` or `pnpm dlx` to invoke the CLI without a global install:\n\n<Command variant=\"exec\">lakeql-cli</Command>\n\n## Run within the monorepo\n\nIf you're working inside the LakeQL monorepo:\n\n```bash\npnpm -F cli cli\n```\n\n## Environment variables\n\nThe CLI connects to Trino for schema introspection. Set the following environment variables before running any command:\n\n| Variable        | Required | Description                       |\n| --------------- | -------- | --------------------------------- |\n| `HIVE_HOST`     | Yes      | Trino host URL including protocol |\n| `HIVE_PORT`     | Yes      | Trino port                        |\n| `HIVE_USERNAME` | Yes      | Authentication username           |\n| `HIVE_PASSWORD` | Yes      | Authentication password           |\n| `HIVE_CATALOG`  | Yes      | Default catalog name              |\n\nCreate a `.env` file in your project root:\n\n```bash\n# .env.example\nHIVE_HOST=https://trino.example.com\nHIVE_PORT=443\nHIVE_USERNAME=your-username\nHIVE_PASSWORD=your-password\nHIVE_CATALOG=hive\n```\n\nThe CLI does not auto-load `.env` files.\nLoad variables into the process environment before invocation.\n\n```bash\n# Option 1: export in your shell\nexport HIVE_HOST=https://trino.example.com\nexport HIVE_PORT=443\nexport HIVE_USERNAME=your-username\nexport HIVE_PASSWORD=your-password\nexport HIVE_CATALOG=hive\nlakeql-cli pull\n\n# Option 2: use dotenv-cli\ndotenv -e ./.env -- lakeql-cli pull\n```\n","description":"How to install and run the LakeQL CLI for schema introspection and code generation.","keywords":["install","installation","lakeql","schema","introspection"]}