Skip to main content
ClawQL

Spec configuration

ClawQL builds an in-memory operation index from OpenAPI 3 (JSON/YAML), Swagger 2 (auto-upgraded), Google Discovery documents, or bundled presets under providers/, optionally extended with native GraphQL and gRPC sources via env. Selection follows a two-stage precedence implemented in src/spec-loader.ts.

Overview

  • Multi-spec mode: one merged search index. execute uses REST per OpenAPI/Discovery operation on the owning spec, and native GraphQL / gRPC for bundled linear or env-configured sources (CLAWQL_GRAPHQL_*, CLAWQL_GRPC_SOURCES) in the same index; native ops use HTTP GraphQL or gRPC unary (GraphQL layer).
  • Single-spec mode: one OpenAPI/Discovery document; execute can use the internal OpenAPI→GraphQL layer when translation succeeds, with REST fallback on failure. Native protocol ops behave the same when configured.

Stage 1 — Multi-spec merge

User-facing model: for multi-spec there is no hidden “partial” default. Either you rely on the one built-in unconfigured merge (all-providers, step 4), or you choose a merge (local paths, bundled id list, or a merged CLAWQL_PROVIDER shortcut). CLAWQL_GOOGLE_TOP50_SPECS / CLAWQL_GOOGLE_CLOUD_SPECS do not select a merge on their own.

Precedence (order matters) when a merge is selected or defaulted:

  1. CLAWQL_SPEC_PATHS — merge local files (comma, semicolon, or newline separated).
  2. CLAWQL_BUNDLED_PROVIDERS — comma/semicolon/newline-separated bundled provider ids and/or google (full GCP on-disk set).
  3. CLAWQL_PROVIDER — merged shortcut (google, all-providers, atlassian, …) when not building a list yourself.
  4. Built-in default — only when no merge was selected: all-providers.

Stage 2 — Single spec

If Stage 1 does not apply, the first match wins:

  1. CLAWQL_SPEC_PATH (aliases: OPENAPI_SPEC_PATH, OPENAPI_FILE)
  2. CLAWQL_SPEC_URL (alias: OPENAPI_SPEC_URL)
  3. CLAWQL_DISCOVERY_URL (alias: GOOGLE_DISCOVERY_URL)
  4. CLAWQL_PROVIDER — single bundled vendor (cloudflare, github, linear, …), not a merged preset
  5. Rare fallback (kind: "default" in code)

Examples: CLAWQL_SPEC_PATH=./openapi.yaml skips Stage 1. CLAWQL_PROVIDER=cloudflare alone loads Cloudflare as a single bundle. An empty environment (nothing above) uses all-providers; for a custom subset, set CLAWQL_BUNDLED_PROVIDERS=…, not another implicit default.

Environment variables

VariableMeaning
CLAWQL_SPEC_PATHLocal OpenAPI JSON/YAML
CLAWQL_SPEC_PATHSMultiple paths → merge
CLAWQL_BUNDLED_PROVIDERSIds to merge: BUNDLED_PROVIDERS keys and/or google
CLAWQL_SPEC_URLFetch OpenAPI from HTTPS
CLAWQL_DISCOVERY_URLGoogle Discovery JSON URL
CLAWQL_PROVIDERMerged preset (Stage 1) or single vendor (Stage 2)
CLAWQL_PROVIDER_AUTH_JSONOne JSON object: specLabel → token string or headers (multi-vendor execute)
CLAWQL_HTTP_HEADERSGlobal header JSON; with CLAWQL_PROVIDER_AUTH_JSON, omit Authorization here
CLAWQL_INTROSPECTION_PATHPregenerated GraphQL introspection JSON for OpenAPI→GraphQL field hints (optional)
CLAWQL_GRAPHQL_URL / CLAWQL_GRAPHQL_NAME / CLAWQL_GRAPHQL_HEADERSSingle native GraphQL endpoint; optional CLAWQL_GRAPHQL_SCHEMA_PATH / CLAWQL_GRAPHQL_INTROSPECTION_PATH if introspection is blocked
CLAWQL_GRAPHQL_SOURCESJSON array — merge native GraphQL HTTP endpoints into search / execute (optional per-source schemaPath / introspectionPath)
CLAWQL_GRPC_SOURCESJSON array — merge unary gRPC RPCs from .proto paths
CLAWQL_API_BASE_URLOverride REST base URL
CLAWQL_BUNDLED_OFFLINE1 / true — do not fetch missing bundled files from the network

Full list: .env.example in the repo.

Google Discovery

Use CLAWQL_DISCOVERY_URL for GCP and other Google APIs, for example:

export CLAWQL_DISCOVERY_URL="https://compute.googleapis.com/\$discovery/rest?version=v1"

The repo vendors a lookup snapshot and docs for refreshing it: docs/providers/google-apis-lookup.md. The bundled Google Cloud API set (on-disk manifest under providers/google/) powers merged preset google.

Bundled providers and presets