oneshot

oneshot executes one GraphQL operation and prints the JSON response to stdout.

mockql oneshot [OPTIONS] --operation <OPERATION> --graphql-url <GRAPHQL_URL> <COMMAND>

<COMMAND> is the provider transport: cli or http.

CLI Provider

Use cli when you want MockQL to call an installed assistant CLI.

mockql oneshot \
  --operation ./examples/swapi/partial-list-items.graphql \
  --variables ./examples/swapi/partial-list-items.json \
  --graphql-url https://swapi-graphql.netlify.app/graphql \
  cli --provider codex --model gpt-5.4-mini

The provider transport and provider options come after the oneshot options. CLI provider setup and defaults are documented in CLI Providers.

mockql oneshot [command options] cli --provider <provider> [provider options]

HTTP Provider

Use http when you want MockQL to call an HTTP provider.

mockql oneshot [command options] http <provider> [provider options]

HTTP provider setup, flags, and authentication are documented in HTTP Providers.

Mocking Fields Outside The Schema

Some use cases require mocking fields or types that are not part of the upstream GraphQL schema yet. MockQL supports this with GraphQL schema extensions through --schema-extension.

For example, SWAPI does not expose a productionBrief field on Film. Define the missing field and type in an extension file:

extend type Film {
  productionBrief: ProductionBrief
}

type ProductionBrief {
  tone: String
  behindTheScenesNote: String
  marketingTagline: String
}

Then select the extended field with @mock and pass the extension file to oneshot:

mockql oneshot \
  --operation ./schema-extension-example.graphql \
  --variables ./schema-extension-example.json \
  --schema-extension ./schema-extension.graphql \
  --graphql-url https://swapi-graphql.netlify.app/graphql \
  cli --provider codex --model gpt-5.4-mini

Because productionBrief is not resolved by SWAPI, it should be selected with @mock.

Options