mockql-cli 0.0.3

Command-line interface for GenAI-powered GraphQL response mocking via @mock
mockql-cli-0.0.3 is not a library.

mockql-cli

The mockql command-line binary. A thin, composable layer that decorates any GraphQL server with GenAI-powered response mocking via the @mock directive.

This crate is deliberately small: it parses arguments, loads a schema, builds a provider configuration, and hands everything to mockql-core, which does the real work (planning, prompting, upstream calls, merging). If you want to understand how mocking happens, read that crate's README. This one is about the surface a user touches.

A CLI is the smallest possible integration surface: any language, agent, script, or demo environment can run a process.

The three subcommands

main.rs defines one clap command with three subcommands. Each has its own module under commands/ with an args.rs (the flags) and a mod.rs (the exec_* function).

Subcommand What it does
oneshot Execute a single operation and print the result to stdout
proxy Run an HTTP server that mocks GraphQL responses per request (with a GraphiQL UI)
schema Print a schema decorated with the @mock directive (optionally minified)

oneshot and proxy are the same engine wrapped two ways — single-shot vs. long-running. schema doesn't execute anything, it's a schema-inspection helper.

Glossary

The argument-level vocabulary a user encounters:

Term What it means
Transport How to reach the LLM: a local cli provider or an http provider
Provider The specific backend — claude/codex/opencode (CLI) or github-copilot/gemini (HTTP)
Serialization format json or toon — how generated data is requested and parsed
Schema source A local SDL file or a URL to introspect
Schema extension Extra SDL applied before planning, so you can @mock not-yet-real fields
Variables Operation variables, read from a JSON file
Headers name:value pairs forwarded to the upstream GraphQL server

The shared argument plumbing is the glue worth knowing: it's where CLI flags become the mockql-core types (ProviderConfig, Header, SerializationFormat, the variables map, and the schema-extension payload) — translating user-facing strings into the strongly-typed inputs MockService expects.

How a command runs

  1. main.rs parses args and dispatches to one of exec_oneshot / exec_proxy / exec_schema.
  2. The command loads a schema (load_schema), builds a reqwest::Client, and — for oneshot/proxy — turns the chosen transport into a ProviderConfig via TransportArg::into_provider_config.
  3. It constructs a MockService and either calls execute once (oneshot), serves it over HTTP (proxy), or just prints the schema (schema).
  4. Errors bubble up as CliError; main prints them to stderr and returns a non-zero exit code.

Install & usage

cargo install mockql-cli   # installs the `mockql` binary

Prerequisites, provider setup, end-to-end examples, and the directive spec live in the top-level docs rather than here, to avoid duplication: